NAV
python

Introduction

Welcome to the AutoComplete Partner API! Dealer partners can use this API to create zero-effort insurance-shopping experiences for their customers.

For each customer you submit, AutoComplete will generate and return a personalized insurance-shopping link (e.g. "https://app.autocomplete.io/aBcDeF"). When visiting that link, your customer will see his/her own contact, household, and vehicle details — in addition to your dealer info — already pre-populated.

You can use this personalized shopping link in one of several ways:

  1. Embed this link into your digital retail experience,
  2. Send this link to your customer through your own CRM system or sales process, or
  3. Have AutoComplete engage your customer directly.

We refer to options (1) and (2) as Dealer-Initiated Messaging, and option (3) as AutoComplete-Initiated Messaging.

Example Use Case

Example submission to POST /people:

{
    "first_name": "Jon",
    "middle_name": "Aegon",
    "last_name": "Snow",
    "date_of_birth": "1986-12-26",
    "gender": "male",
    "marital_status": "married",
    "education": "bachelors",
    "employment_status": "employed",
    "residence_ownership_type": "own",
    "age_first_licensed": 16,
    "phone_numbers": [
        {
            "number": "+15551230000",
            "type": "mobile",
            "sms_consent": true
        },
        {
            "number": "+15551231111",
            "type": "home"
        }
    ],
    "emails": [
        {
            "email": "jon.snow@nightswatch.com",
            "preferred": true
        }
    ],
    "addresses": [
        {
            "type": "physical",
            "address_1": "555 Main St.",
            "city": "Pleasantville",
            "state": "CA",
            "postal_code": "94105"
        },
        {
            "type": "mailing",
            "address_1": "PO Box 100",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94105"
        }
    ],
    "drivers_license": {
        "number": "D1234567",
        "state": "CA",
        "status": "active",
        "issued_date": "2015-11-11",
        "expiration_date": "2025-11-11"
    },
    "new_vehicles": [
        {
            "vin": "WAULH54B0YN028245",
            "year": 2022,
            "make": "Audi",
            "model": "A4",
            "trim": "45 TFSI",
            "ownership_start": "2022-03-09",
            "ownership_type": "leased",
            "lease_duration": 36,
            "annual_mileage": 12000,
            "odometer": 57,
            "cost_new": 3990000,
            "lienholder": "Toyota Financial Services",
            "primary_use": "pleasure",
            "rideshare": false,
            "addresses": [
                {
                    "type": "garaging",
                    "address_1": "555 Main St",
                    "city": "Pleasantville",
                    "state": "CA",
                    "postal_code": "94105-1023"
                },
                {
                    "type": "lienholder",
                    "address_1": "1 Toyota Way",
                    "city": "Plano",
                    "state": "TX",
                    "postal_code": "75024"
                }
            ]
        }
    ],
    "trade_ins": [
        {
            "vin": "5TD2A23C645204309",
            "year": 2015,
            "make": "Toyota",
            "model": "Camry",
            "odometer": 78001
        }
    ],
    "policies": [
        {
            "policy_type": "auto",
            "carrier_name": "geico",
            "carrier_policy_number": "604-80-35-635",
            "effective_date": "2021-12-20",
            "expiry_date": "2022-05-20"
        }
    ],
    "related_people": [
        {
            "first_name": "Ygritte",
            "last_name": "Wildling",
            "date_of_birth": "1987-02-09",
            "marital_status": "married",
            "relationship": "spouse"
        }
    ],
    "source": {
        "dealer_id": "4119799d-215f-4f49-b38a-0b94c2448399",
        "type": "cdk",
        "external_customer_number": "928880",
        "external_deal_number": "41706"
    },
}

Example response:

{
    "id": "ec694d9a-a3f8-4a55-95ff-de97d1bc945a",
    "first_name": "Jon",
    "last_name": "Snow",
    ...
    "flow": {
        "flow_id": "uVwXyZ",
        "flow_url": "https://app.autocomplete.io/uVwXyZ", // Jon's personalized shopping link
    }
}

Example error:

{
    "status_code": 400,
    "message": "Field 'new_vehicles' cannot be empty."
}

Let's say your customer, Jon Snow, wants to trade in an old Toyota Camry for a new Audi A4.

Once that deal is desked, you submit all of Jon's DMS (dealer management system) data to the AutoComplete API using the POST /people endpoint.

Using the information you just submitted plus data from third-party partners, AutoComplete creates a personalized shopping link for Jon containing his contact information, household drivers, new and existing vehicles, and prior coverages. The quality of this personalization is determined by the level of detail you submit, which means you should submit as many available fields as possible.

If you've configured your integration for Dealer-Initiated Messaging, AutoComplete simply returns Jon's personalized link (e.g. "https://app.autocomplete.io/aBcDeF") back to you. On the other hand, if you've configured your integration for AutoComplete-Initiated Messaging, AutoComplete will engage with Jon directly via his preferred contact method.

Finally, Jon visits his personalized link, where he confirms his personal information, compares quotes, and purchases a policy.

Optional Responses

By default, any submissions to the POST /people endpoint will only return the customer's personalized flow_id and flow_url ("uVwXyZ" and "https://app.autocomplete.io/uVwXyZ", respectively, in the example above). However, you can obtain additional responses, if desired:

Current Insurance

To request the customer's current insurance information when calling /people:

{
    "first_name": "Jon",
    "last_name": "Snow",
    ...
    "return_current_insurance": true,
}

As part of the shopping process, AutoComplete attempts to retrieve the customer's current insurance policy from insurer databases. This data helps AutoComplete select more suitable insurers and insurance policies for the customer, but can also be useful for dealers (a) to confirm that the customer is actively insured, as required by law, and (b) to confirm that the customer has adequate levels of asset coverage to meet lienholder requirements.

To indicate that you would like us to return the current insurance details (if available), set the optional parameter return_current_insurance to true.

Initial Quote

To request an initial quote for the customer when calling /people:

{
    "first_name": "Jon",
    "last_name": "Snow",
    ...
    "return_initial_quote": true,
}

AutoComplete can also generate a preliminary, "initial" insurance quote for any new customer. This initial quote will obviously not reflect any customizations that would require further user interaction, such as additional household cars or drivers not already contained in your submitted payload. However, this initial quote can still be useful to gauge customer interest and calculate potential savings.

To indicate you would like us to return an initial quote, set the optional parameter return_initial_quote to true. Please note that your customer must have already consented to an insurance quote before you submit this request.

Receiving Results

AutoComplete typically requires 15 to 60 seconds to obtain this optional data. As such, we will return this data to you asynchrously. We support two methods — you can either:

To set up a callback, please provide AutoComplete a URL and authorization token during your integration setup. AutoComplete will make a POST request to your specified URL as soon as results are available. The structure of the webhook payload is identical to the returned from GET .../results.

Technical Overview

Example Request:

import requests

api_key = # <Your API Key>
api_secret = # <Your API Secret>

headers = {'Content-Type': 'application/json'}

r = requests.get('https://api.autocomplete.io/people', auth=(api_key, api_secret), headers=headers)

The AutoComplete Partner API is served exclusively over HTTPS, requests are authenticated using Basic Authentication with your API Key and API Secret, and all request bodies and responses are JSON-encoded. We also use standard HTTP headers, verbs, and response codes.

Requests are rate limited to one request per second.

Endpoints

POST /people

Example with minimum required fields:

import requests

api_key = # <Your API Key>
api_secret = # <Your API Secret>

headers = {'Content-Type': 'application/json'}

data = {
    "first_name": "Jon",
    "last_name": "Snow",
    "date_of_birth": "1986-12-26",
    "phone_numbers": [
        {
            "number": "+15551230000",
            "type": "mobile"
        }
    ],
    "addresses": [
        {
            "address_1": "555 Main St",
            "city": "Pleasantville",
            "state": "CA",
            "postal_code": "94105"
        }
    ],
    "new_vehicles": [
        {
            "vin": "WAULH54B0YN028245"
        }
    ],
    "source": {
        "dealer_id": "4119799d-215f-4f49-b38a-0b94c2448399"
    }
}

r = requests.post('https://api.autocomplete.io/people', auth=(api_key, api_secret), headers=headers, json=data)

if r.status_code == 200:
    print(r.text)

Upload all customer information using this endpoint. All fields are preferred, only some fields are required.

Minimum Required Fields

Parameter Notes
first_name
last_name
date_of_birth
phone_numbers Must contain at least one valid phone number when configured for AutoComplete-Initiated Messaging
addresses Must contain at least one valid address
new_vehicles Must contain at least one vehicle, with vin
source Indicates the dealer of origin

For all preferred fields, see Models - Person.

GET /people/<flow_id>/results

Example:

import requests

api_key = # <Your API Key>
api_secret = # <Your API Secret>

headers = {'Content-Type': 'application/json'}

flow_id = 'uVwXyZ'  # From the /people endpoint

r = requests.get(f'https://api.autocomplete.io/people/{flow_id}/results', auth=(api_key, api_secret), headers=headers, json=data)

if r.status_code == 200:
    print(r.text)

Example response:

{
    "flow_id": "uVwXyZ",
    "current_insurance_status": "found",
    "current_insurance": {
        "policy_type": "auto",
        "carrier_name": "Allstate",
        "carrier_policy_number": "5789000AZ",
        "effective_date": "2023-01-01",
        "expiry_date": "2023-06-01",
        "coverages": {
            "bodily_injury_liability": {
                "per_person_limit": 3000000,
                "per_incident_limit": 6000000
            },
            "property_damage_liability": {
                "per_incident_limit": 2500000
            },
            "comprehensive": {
                "deductible": 100000
            },
            "collision": {
                "deductible": 100000
            }
        }
    },
    "initial_quote_status": "success",
    "initial_quote": {
        "carrier_name": "Progressive",
        "effective_monthly_price": 12399,
    }
}

If requested as part of the original submission, retrieve the customer's current insurance policy and/or initial insurance quote. See the Optional Responses section for more information.

Parameter Type Description
flow_id string Used to associate responses to customers when returned by an asynchronous callback
current_insurance_status string Possible values: pending, found, not_found. Note that a status of not_found only indicates that AutoComplete failed to locate the customer's current insurance — not that the customer definitively has no current insurance.
current_insurance Policy If found, the customer's current auto insurance policy
initial_quote_status string Possible values: pending, found, not_found
initial_quote If found, the winning initial quote carrier and price

Models

Person

This is the model used to represent a customer.

Parameter Type Description
first_name string
middle_name string
last_name string
date_of_birth string "YYYY-MM-DD" format
gender string Valid options: male, female, non_binary
marital_status string Valid options: single, married, other
relationship string Required when the Person is an element of an array, such as in the .related_people field. Valid options: spouse, sibling, parent, parent_in_law, child, child_in_law, housemate, other
education string Highest level of education achieved. Valid options: associates, bachelors, doctorate, no_high_school_diploma, high_school, masters, medical_school, law_school, vocational_certificate, other
employment_status string Valid options: employed, retired, student, unemployed
residence_ownership_type string Valid options: own, rent
age_first_licensed integer
phone_numbers Array<PhoneNumber>
emails Array<Email>
addresses Array<Address>
drivers_license <DriversLicense>
policies Array<Policy>
new_vehicles Array<Vehicle> Used only when submitting to POST /people
trade_ins Array<Vehicle> Used only when submitting to POST /people
vehicles Array<Vehicle> Never submitted. Only available when reading from GET /people
related_people Array<Person>
flow <Flow> Never submitted
source <Source> Used only when submitting to POST /people

PhoneNumber

Example:

{
    "number": "+15551230000",
    "type": "mobile",
    "sms_consent": true
}
Parameter Type Description
number string Formatted as "+[Country Code][Number]", e.g. "+15551230000"
type string Valid options: mobile, home, work
sms_consent boolean

Email

Example:

{
    "email": "john.doe@gmail.com",
    "preferred": true
}
Parameter Type Description
email
string e.g. "john@gmail.com"
preferred boolean

Address

Example:

{
    "type": "mailing",
    "address_1": "1650 17th St NW",
    "address_2": "Suite 100",
    "city": "Washington",
    "state": "DC",
    "postal_code": "20500"
}

All addresses are assumed to be in the United States.

Parameter Type Description
type string Valid options: mailing, physical, garaging, lienholder. Defaults to physical
address_1 string The first line of the address, e.g. "530 Howard St"
address_2 string The second line of the address, e.g. "Unit 470"
city string e.g. "San Francisco"
state string Two-letter postal abbreviation, e.g. "CA"
postal_code string e.g. "94105" or "94105-0907"

DriversLicense

Example:

{
    "number": "D123456",
    "state": "CA",
    "status": "active",
    "issued_date": "2018-10-25",
    "expiration_date": "2028-10-25"
}
Parameter Type Description
number string Alphanumeric, e.g. "D1234567"
state string Two-letter postal abbreviation, e.g. "CA"
status string Valid options: active, suspended, revoked, expired
issued_date string "YYYY-MM-DD" format
expiration_date string "YYYY-MM-DD" format

Policy

Example:

{
    "policy_type": "auto",
    "carrier_name": "geico",
    "carrier_policy_number": "604-80-35-635",
    "effective_date": "2021-12-20",
    "expiry_date": "2022-05-20"
}
Parameter Type Description
policy_type string Valid options: see Enums - Policy Type
carrier_name string Valid options: see Enums - Carrier
carrier_policy_number string e.g. "6048035635"
effective_date string "YYYY-MM-DD" format
expiry_date string "YYYY-MM-DD" format

Vehicle

Example:

{
    "vin": "2T3RWRFV3KW021971",
    "year": 2019,
    "make": "Toyota",
    "model": "RAV4",
    "trim": "XLE",
    "ownership_start": "2019-08-21",
    "ownership_type": "leased",
    "lease_duration": 36,
    "finance_duration": null,
    "annual_mileage": 12000,
    "odometer": 48,
    "cost_new": 3999500,
    "primary_use": "work",
    "lienholder": "Toyota Financial Services",
    "anti_lock_brakes": true,
    "anti_theft_device": true,
    "rideshare": false,
    "addresses": [
        {
            "type": "garaging",
            "address_1": "530 Howard St",
            "address_2": "Ste 470",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94105"
        },
        {
            "type": "lienholder",
            "address_1": "PO BOX 105386",
            "city": "Atlanta",
            "state": "GA",
            "postal_code": "30348-5386"
        }
    ]
}
Parameter Type Description
vin string 17 alphanumeric characters
year integer e.g. 2021
make string Valid options: see Enums - Vehicle Make
model string e.g. "RAV4"
trim string e.g. "XLE"
ownership_start string "YYYY-MM-DD" format
ownership_type string Only available when reading from GET /people. Valid options: owned, financed, leased, trade_in, other
lease_duration integer Only applicable when .type == "leased". In months
finance_duration integer Only applicable when .type == "financed". In months
annual_mileage integer In miles
odometer integer In miles
cost_new integer In cents
primary_use string Valid options: work, pleasure, school, business, agricultural
lienholder string e.g. "Toyota Financial Services"
anti_lock_brakes boolean
anti_theft_device boolean
rideshare boolean
addresses Array<Address>

Flow

Example:

{
    "flow_id": "aBcDeF",
    "flow_url": "https://app.autocomplete.io/aBcDeF", 
}

The flow_url is the personalized insurance-shopping link for that customer.

Parameter Type Description
flow_id string e.g. "aBcDeF"
flow_url string e.g. "https://app.autocomplete.io/aBcDeF"

Source

Example describing a customer originating from CDK:

{
    "dealer_id": "4119799d-215f-4f49-b38a-0b94c2448399", // AutoComplete-assigned
    "type": "cdk",
    "external_customer_number": "928880", // CDK refers to this field as <CustNo>
    "external_deal_number": "41706", // CDK refers to this field as <DealNo>
}

Example describing a customer originating from DealerTrack:

{
    "dealer_id": "88753dfc-5ede-49cd-92b4-7b63d235d16c", // AutoComplete-assigned
    "type": "dealertrack",
    "external_customer_number": "1028648", // DealerTrack refers to this field as <CustomerNumber>
    "external_deal_number": "6302", // DealerTrack refers to this field as <DealNumber>
}

Informs AutoComplete about the origin of customer information. This is usually a specific combination of dealer, DMS type, and customer number.

Parameter Type Description
dealer_id string AutoComplete's internal UUID of the origin dealer, e.g. "4119799d-215f-4f49-b38a-0b94c2448399"
type string Valid options: automate, cdk, dealertrack, reynolds
external_customer_number string The customer identifier used by the DMS
external_deal_number string The deal identifier used by the DMS

Enums

When submitting, all values are case-insensitive. Spaces and underscores are interchangeable.

For example, "american_family", "american family", and "AMERICAN FAMILY" will all be accepted as a valid alternatives for "American Family". However, responses returned from the API will always be formatted as shown.

Carrier

"AAA"
"Acuity"
"Adirondack"
"Allmerica"
"Allstate"
"Ally Insurance"
"American Family"
"American National"
"American Strategic"
"Amica Mutual"
"AmTrust Insurance"
"Arrowhead"
"ASI Progressive"
"Aspire Advantage"
"Aspire Savings"
"AssuranceAmerica"
"Auto Owners"
"Bear River"
"Branch"
"Bristol West"
"Chubb"
"Cincinnati"
"Clarendon"
"Clearcover"
"CNA Insurance"
"Commonwealth"
"Country Financial"
"Cover"
"Dairyland"
"Direct General"
"Electric"
"Elephant"
"Encompass"
"Encova"
"Equity Insurance"
"Erie"
"Esurance"
"Farmers"
"Farmers Union Insurance"
"Fiesta"
"First Chicago"
"Foremost"
"Freedom National"
"GAINSCO"
"GEICO"
"Germania"
"GMAC"
"Good2Go"
"Grange"
"Hallmark"
"Hanover"
"Heritage"
"Hippo"
"Home State County Mutual"
"Homesite"
"Horace Mann"
"Infinity"
"Infinity RSVP"
"Infinity Special"
"Integrity"
"Kemper"
"Kentucky Farm Bureau"
"Leader"
"Liberty Mutual"
"Mapfre"
"Markel Insurance"
"Mendota Insurance"
"Mercury"
"Meritplan"
"Metlife"
"Metromile"
"Mile Auto"
"National General"
"National General"
"Nationwide"
"Newport"
"NYCM"
"Plymouth Rock"
"Progressive"
"QBE"
"Redpoint"
"Root"
"Safe Auto"
"Safeco"
"Safeway"
"Secura"
"SelectQuote"
"Shelter"
"Starr Indemnity"
"State Auto"
"State Farm"
"Stillwater"
"Sun Coast"
"Texas Farm Bureau"
"The General"
"The Hartford"
"Titan"
"Travelers"
"TSC Direct"
"21st Century"
"Universal"
"USA Underwriters"
"USAA"
"West Bend Mutual"
"Westfield"

Policy Type

"auto"
"boat"
"business_owners"
"combo"
"commercial_auto"
"commercial_umbrella"
"condo"
"earthquake"
"farmowner"
"fire"
"flood"
"homeowners"
"landlord"
"life"
"motorcycle"
"personal_articles"
"recreational_vehicle"
"renters"
"snowmobile"
"term_life"
"trailer"
"umbrella"
"universal_life"
"whole_life"

Vehicle Make

"Acura"
"Alfa Romeo"
"Aston Martin"
"Audi"
"BMW"
"Bentley"
"Bugatti"
"Buick"
"Cadillac"
"Chevrolet"
"Chrysler"
"Dodge"
"Ferrari"
"Fiat"
"Fisker Automotive"
"Ford"
"GMC"
"Genesis"
"Honda"
"Hummer"
"Hyundai"
"Infiniti"
"Jaguar"
"Jeep"
"Karma"
"Kia"
"Lamborghini"
"Land Rover"
"Lexus"
"Lincoln"
"Lordstown"
"Lotus"
"Lucid"
"Maserati"
"Maybach"
"Mazda"
"McLaren"
"Mercedes Benz"
"Mercury"
"Mini"
"Mitsubishi"
"Nikola"
"Nissan"
"Oldsmobile"
"Polestar"
"Pontiac"
"Porsche"
"Plymouth"
"RAM"
"Rivian"
"Rolls Royce"
"Saab"
"Saturn"
"Scion"
"Smart"
"Subaru"
"Suzuki"
"Tesla"
"Toyota"
"Volkswagen"
"Volvo"

Response Codes

Response Code Definition
200 (OK) The request was processed as expected, and the response includes some data.
204 (No Content) The request was processed as expected, but the response is empty.
400 (Bad Request) A parameter, format, or structure of the request is incorrect.
401 (Unauthorized) The authentication credentials are missing or incorrect.
403 (Forbidden) The provided credentials do not have access to this endpoint or resource.
404 (Not Found) Either the endpoint does not exist, or the requested resource does not exist.
429 (Too Many Requests) The number of requests have exceeded the rate limit, see Rate Limits.
5XX An uncaught server error has occurred. This usually indicates a system-level failure. Please contact us if you see this repeatedly.

Errors

Sample error response:

{
  "status_code": 400,
  "message": "Field name 'vehicle.vin' must be a 17-character alphanumeric string."
}

The category of error will generally be indicated by the HTTP response code. Additionally, the API will attempt to return a human-readable error message.

python