CoverHound Quotes JSON API (version 1) reference

Introduction

This document describes how to utilize the CoverHound Quotes API (version 1).

Quotes API

The Quotes API provides a channel for you to post customer lead data to CoverHound and receive back quotes from our collaborating carriers.

Use of the Quotes API requires an API key and an API secret. Note that any API credentials shown in this document are examples and will not work in a real situation.

The Quotes API is JSON based, it accepts JSON input, and returns a JSON response. You can use a tool such as curl to easily try out the API.

Authentication

The Quotes API requires the use of your API key and secret to authenticate yourself and get an access token. This token will then be used to make quote requests. The token will be valid until you decide otherwise and invalidate it.

Getting an access token

  POST /api/oauth/access_token
  Accept: application/json
  Content-type: application/json
  {
    "apiKey": "eb6ad34d-6989-4f94-874d-e2f848dede63",
    "apiSecret": "1337648ad51d99be78e446f8d721e8aa",
    "grantType": "credentials"
  }

Returns your access token as a string like

"f3657af5975b2fd1b148307570a4c2fe"

Invalidating an access token

  POST /api/oauth/invalidate
  Accept: application/json
  Content-type: application/json
  {
    "apiKey": "eb6ad34d-6989-4f94-874d-e2f848dede63",
    "apiSecret": "1337648ad51d99be78e446f8d721e8aa",
    "accessToken": "f3657af5975b2fd1b148307570a4c2fe"
  }

Returns a 401 (Unauthorized) with header X-Error-Detail "Invalid token." if the token doesn't exist.

If your credentials are wrong, you will get a 401 (Unauthorized) with header X-Error-Detail "Invalid credentials".

Request

  POST https://coverhound.com/api/auto/quotes
  Accept: application/json
  Content-type: application/json
  Access-Token: f3657af5975b2fd1b148307570a4c2fe
  {
    "userId":"john.walsh.id",
    "carriers":["ESRNC"],
    "usePolling": false,
    "applicant":{
      "mailingAddress1":"1 California St",
      "mailingAddress2":"#1100",
      "mailingZip":"94111",
      "phone1":"5558675309",
      "email":"john.walsh@example.com",
      "effectiveDate":"12-07-2014",
      "vehicles":[
        {
          "vin":"1FMDU63K3U",
          "use":"Commute",
          "mileage":10000,
          "commuteDistance":9,
          "commuteFrequency":5,
          "purchaseDate":"06-15-2015",
          "ownership":"Paid in Full",
          "commuteNyNj":false,
          "primaryDriver":0
        }
      ],
      "drivers":[
        {
          "primaryApplicant":true,
          "primaryVehicle":0,
          "firstName":"John",
          "middleName":"Trevor",
          "lastName":"Walsh",
          "birthDate":"05-01-1975",
          "gender":"M",
          "marital":"Married",
          "education":"High School",
          "careerStatus":"Full-Time Student",
          "homeowner":true,
          "residenceType":"Condo",
          "ageLicensed":16,
          "goodStudent":true,
          "distantStudent": false,
          "licenseStatus":"Valid",
          "sr22":false,
          "excluded":false,
          "vehicles":[0]
        },
        {
          "primaryApplicant":false,
          "primaryVehicle":0,
          "firstName":"Janet",
          "lastName":"Walsh",
          "birthDate":"12-25-1978",
          "gender":"F",
          "marital":"Married",
          "education":"Some High School",
          "careerStatus":"Employed",
          "occupationIndustry":"Art/Design/Media",
          "occupation":"Actor",
          "homeowner":true,
          "residenceType":"Condo",
          "relationPrimary":"Spouse",
          "addressPrimarySame":true,
          "ageLicensed":20,
          "licenseStatus":"Valid",
          "sr22":false,
          "excluded":false,
          "vehicles":[0]
        }
      ],
      "incidents":[
        {
          "incidentType":"Accident",
          "incidentDetails":"At Fault (Less than $750 damage)",
          "incidentDate":"09-01-2010",
          "driverNum":0
        }
      ],
      "priorPolicy":{
        "insuredDuration": "2 years",
        "insuredDurationDetail": "2 years",
        "expirationDate": "12-01-2015",
        "priorBIPerson": 100000,
        "priorBIAccident": 300000,
        "priorCarrier": "OTHER"
      }
    },
    "coverages":{
      "policy": {
        "biPerson": 15000,
        "biAccident": 30000,
        "mp": 5000,
        "pd": 5000,
        "umpd": 0,
        "umbiPerson": 15000,
        "umbiAccident": 30000
      },
      "vehicles": [
        {
          "coll": 0,
          "comp": 0
        }
      ]
    }
  }

General

userId

string
Required
Identifier you use to identify a customer.

usePolling

boolean
Optional
Make a polling request - gets you a transactionId that you can use to fetch updates about your request

carriers

array
Required
Codes of the carriers you want to quote.

Please use following mapping values:

Carrier	Code
Acuity	ACUIT
Bristol West	BRSTL
CAIC	CAIC
Dairyland	DAIRY
Infinity	INFINI
Kemper	KEMPR
MAPFRE	MAPFR
National General Insurance	GMAC
Nationwide	NTNWD
Progressive	PROGR
Safeco	SAFEC
State Auto	STATA
The General	GENRL

Applicant (attribute: applicant)

General

mailingAddress1

string
Required
The first line of the street address used to receive written communication. (eg "1 California St")

mailingAddress2

string
Optional
The second line of the street address used to receive written communication. (eg "#1100")

mailingZip

string
Required
The 5-digit zip code associated with the mailing address of the applicant
Possible values: ZIPs within the 50 states and Washington DC, except for AK, HI, and MA.

phone1

string
Optional
The primary phone number of the shopper. Must be 10 digits, no punctuation.

phone2

string
Optional
The secondary phone number of the shopper. Must be 10 digits, no punctuation.

string
Required
The email address of the shopper.

effectiveDate

string
Required
The date the shopper would like her policy to start. Must be at least 1 day after the request.

Vehicles (attribute: vehicles)

vin

string
Required
The VIN (pattern)
Possible values:
- Any valid 17-digit VIN for US vehicles manufactured 1981 or later. The VIN should not contain asterisks.
- Any valid VIN pattern for US vehicles manufactured 1981 or later. For data from the Polk database, this will be a 17-digit string with asterisks in positions 9 and 11-17, for example "YV1RH592*8*******". For all others, this should be a 10-digit string consisting of the values from positions 1-8 and 10-11 of the vehicle's VIN, for example "YV1RH59282".

use

string
Required
The primary usage of the vehicle.
Possible values:
- Commute
- Pleasure
- Business

mileage

integer
Required
The estimated annual mileage driven.

commuteDistance

integer
Required when use is "Commute"
The estimated miles to work one way.

commuteFrequency

integer (1-7)
Required when use is "Commute"
The number of days driven to work per week.

purchaseDate

mm-dd-yyyy
Optional
The date the customer purchased the vehicle.

ownership

string
Required
The ownership of the vehicle
Possible values:
- Paid in Full
- Financed
- Leased

commuteNyNj

boolean
Required if the mailing address is located in Pennsylvania
Possible values:
- true if the vehicle is used to commute to either New York or New Jersey
- false otherwise

primaryDriver

integer
Required
The primary driver of this vehicle
Possible values: 0-based index in vehicles

Drivers (attribute: drivers)

primaryApplicant

boolean
Required
Is this driver the primary applicant on the new policy?
Possible values: true, false

firstName

string
Required
The first name of the driver

lastName

string
Required
The last name of the driver

middleName

string
Optional
The middle name of the driver

birthDate

mm-dd-yyyy
Required
The birth date of the driver

gender

string
Required
Possible values:
- 'M' for Male
- 'F' for Female

marital

string
Required
The marital status of the driver
Possible values:
- Single
- Married
- Divorced
- Separated
- Widowed
- Domestic Partner

dlNum

string
Optional
The driver's license number

dlState

string
Required if dlNum is given
The abbrevation for the driver's license state, for example "TX"

education

string
Required
The level of education completed by the driver
- Some High School
- High School
- Some College
- 2 Year College
- 4 Year College
- Graduate Degree
- Doctorate

careerStatus

string
Required
The career status of the driver
Possible values:
- Employed
- Unemployed
- Full-Time Student
- Retired
- Disabled

occupationIndustry

The occupation industry of the driver
Required if careerStatus = Employed
We accept standard ACORD values for occupation industries. See this CSV file for the mappings between occupationIndustry and occupation. All accepted values are included.

occupation

The occupation of the driver
Required if careerStatus = Employed
We accept standard ACORD values for occupations. See this CSV file for the mappings between occupation_industry and occupation. All accepted values are included.

goodStudent

boolean
Required if careerStatus = Full-Time Student
Possible values:
- true if the driver has an overall GPA of 3.0 or better
- false otherwise

distantStudent

boolean
Optional
Possible values:
- true if the driver is a distant student
- false if the driver is not a distant student

homeowner

boolean
Required
true if the driver is a homeowner, false otherwise.
Possible values: true, false

residenceType

string
Required if homeowner = true
The type of residence the driver owns
Possible values:
- Home
- Condo
- Townhouse
- Mobile Home
- Other

relationPrimary

string
Required if the driver is not the primary applicant
The driver's relationship to the primary applicant
Possible values:
- Spouse
- Domestic Partner
- Child
- Parent
- Other

addressPrimarySame

boolean
Required if the driver is not the primary applicant
Possible values:
- true if the driver lives at the same address at the primary applicant
- false otherwise

ageLicensed

integer
Required
The age that the driver was first licensed
Possible values: 15 - 100 (inclusive)

licenseStatus

string
Required
The license status of the driver
Possible values:
- Valid
- Permit
- Expired
- Suspended
- Cancelled
- Not Licensed
- Permanently Revoked

sr22

boolean
Required
Does the driver require an SR-22?
Possible values: true, false

ssn

string
Optional
The driver's social security number

excluded

boolean
Required
Should this driver be excluded from the policy?
Possible values: true, false

vehicles

array of integer
Required
The vehicles this driver will drive
Possible values: 0-based indexes of vehicles

primaryVehicle

integer
Required
Vehicle that driver primarily drives
Possible values: 0-based index in vehicles (applicant's not driver's)

Incidents (attribute: incidents)

incidentType

string
Required if incident is present
The type of incident
Possible values:
- Accident
- Claim
- DUI
- Moving Violation
- Other Violation
- Speeding

incidentDetails

string
The details associated with the respective incident
Required if incident is present
We accept standard ACORD values for incident detail. See this CSV file for the mappings between incident_type and incident_detail. All accepted values are included.

incidentDate

string
Required if incident is present
The date on which the incident occurred
Format: mm-dd-yyyy

driverNum

integer
Required if incident is present
Identifies the driver the incident is associated with.
Possible values: 0-based index in drivers

Prior Policy (attribute: priorPolicy)

insuredDuration

string
Required
The amount of time the shopper has been continuously insured
Possible values:
- Not Currently Insured
- 0-6 months
- 6-12 months
- 1 year
- 2 years
- 3 years
- 4 years
- 5 years
- 6+ years

insuredDurationDetail

string
Optional
The amount of time the shopper has been continuously insured (detail)
Possible values:
- Not Currently Insured
- 1 month
- 2 months
- 3 months
- 4 months
- 5 months
- 6 months
- 7 months
- 8 months
- 9 months
- 10 months
- 11 months
- 1 year
- 2 years
- 3 years
- 4 years
- 5 years
- 6 years
- 7 years
- 8 years
- 9 years
- 10 years
- 11 years
- 12 years
- 13 years
- 14 years
- 15 years
- 16 years
- 17 years
- 18 years
- 19 years
- 20 years
- 21+ years

lapseDuration

string
Required when insuredDuration = Not Currently Insured
The amount of time the shopper has not been insured
Possible values:
- Never Insured
- < 1 Month
- > 1 Month

expirationDate

string
Optional
The expiration date of the shopper's current or previous policy
Format: mm-dd-yyyy

priorBIPerson

integer
Optional
The per person BI limit for the shopper's current or previous policy
Accepted values are outlined on this page by state (shown as biPerson / biAccident)

priorBIAccident

integer
Optional
The per person BI limit for the shopper's current or previous policy
Accepted values are outlined on this page by state (shown as biPerson / biAccident)..

priorCarrier

string
Optional
Code of the shopper's previous carrier.

Please use following mapping values:

Carrier	Code
21st Century	21CEN
AAA	AAA
AARP	AARP
Acuity	ACUIT
Allstate	ALLST
AmFam	AMFAM
Amica	AMMUT
Auto Club	AUTOC
Bristol West	BRSTL
CAIC	CAIC
Century National	CENTN
COUNTRY	CNTRY
CSE	CSEI
Dairyland	DAIRY
Direct General	DIRGG
Electric	ELECT
Elephant	ELEPH
Encompass	ENCMP
Erie	ERIEG
Esurance	ESRNC
Farmers	FARMS
Fireman's Fund	FIREM
Foremost	FOREM
Geico	GEICO
Good2Go	OMNIG
High Point	PALIS
iMingle	IMING
Infinity	INFINI
Kemper	KEMPR
Liberty Mutual	LBRTY
MAPFRE	MAPFR
Mercury	MRMCC
MetLife	METRO
National General Insurance	GMAC
Nationwide	NTNWD
Other	OTHER
Pacific Specialty	PACSP
Plymouth Rock	PLYMT
Progressive	PROGR
SafeAuto	SAFEA
Safeco	SAFEC
Shelter Insurance	SHLTR
State Auto	STATA
State Farm	SFARM
Stillwater	FIDNT
The General	GENRL
The Hartford	HARTF
Titan	TITAN
Travelers	TRAVL
Unitrin	UNTRN
Universal North America	UNAIC
USAA	USAAG
Workmen's	WRKMN

Coverages (attribute: coverages)

Policy (attribute: policy)

Coverages for the policy.
integers
Required: biPerson biAccident mp pd umpd umbiPerson umbiAccident
Optionals: uim uimPerson uimAccident pip pipDeductible apip workLoss optbiPerson optbiAccident pipOptions accidentalDeath brb supplemental wageLoss limCollDed firstParty extraMedicalExp uimpd tortLimitation funeralExpense combinationFirstParty stackedUm pipAppliesTo extendedMedical medicalExpense autoDeathIndemnity medicalExpenseExclusion pipApplies incomeLoss stackedUim supplementalSpousalLiability additionalDeath um-option obel threshold healthcare pipStacking pipWorkLossWaiver propertyProtectionInsurance umUimConversion
See this page for the possible values, depending on the state of the shopper. All accepted values are included.
biPerson and biAccident will be found under bi like this: "biPerson / biAccident".
Same for uim, umbi, workloss, and optbi.

Vehicles (attribute: vehicles)

For each vehicle, in the same order as the vehicles attribute, list all the coverages in an object.

integers
Required: coll comp
Optionals: loanLeaseGap rrDay rrMonth tl
See this page for the possible values, depending on the state of the shopper. All accepted values are included.
rrDay and rrMonth will be found under rr like this: "rrDay / rrMonth".

Responses

Successful Response - Successful Quote

Status code: 201, Success

  {
    "userId":"john.walsh.id",
    "transactionId":"232c552e-3756-43a6-a641-be32755e28d3",
    "customerId":628171,
    "coverages":{
      "policy":{
        "biPerson":15000
        "biAccident":30000,
        "mp":5000,
        "pd":5000,
        "umpd":0,
        "umbiPerson":0,
        "umbiAccident":0
      },
      "vehicles":[
        {
          "coll":0,
          "comp":0,
          "tl":0,
          "rrDay":0,
          "rrMonth":0
        }
      ]
    },
    "quotes":[
      {
        "carrierCode":"ESRNC",
        "carrierName":"Esurance",
        "payPlans":[
          {
            "payPlanName":"Pay in Full",
            "payPlanDesc":"Pay in Full",
            "termLength":6,
            "downPayment":"376.9",
            "installment":"0.0",
            "numInstallments":0,
            "nextInstallment":"08-01-2014",
            "totalPremium":"376.9"
          },
          {
            "payPlanName":"Monthly, Automatic Payments",
            "payPlanDesc":"Monthly, Automatic Payments",
            "termLength":6,
            "downPayment":"126.33",
            "installment":"67.63",
            "numInstallments":4,
            "nextInstallment":"08-01-2014",
            "totalPremium":"396.85"
          }
        ]
      }
    ],
    "purchaseUrl":"https://coverhound.com/resume/167565ae-83f4-45d5-b8e1-21032c29e41a?source=202",
    "purchasePhone":"8556419932"
  }

Successful Response - Carrier does not wish to write the risk

{ "userId":"john.walsh.id", "transactionId":"232c552e-3756-43a6-a641-be32755e28d3", "customerId":628171, "coverages":{ "policy":{ "biPerson":15000 "biAccident":30000, "mp":5000, "pd":5000, "umpd":0, "umbiPerson":0, "umbiAccident":0 }, "vehicles":[ { "coll":0, "comp":0, "tl":0, "rrDay":0, "rrMonth":0 } ] }, "quotes":[ { "carrierCode":"ESRNC", "carrierName":"Esurance", "error":"Esurance does not wish to quote this risk type" } ], "purchaseUrl":"https://coverhound.com/resume/167565ae-83f4-45d5-b8e1-21032c29e41a?source=202", "purchasePhone":"8556419932" }

Successful Response - Carrier integration issue

{ "userId":"john.walsh.id", "transactionId":"232c552e-3756-43a6-a641-be32755e28d3", "customerId":628171, "coverages":{ "policy":{ "biPerson":15000 "biAccident":30000, "mp":5000, "pd":5000, "umpd":0, "umbiPerson":0, "umbiAccident":0 }, "vehicles":[ { "coll":0, "comp":0, "tl":0, "rrDay":0, "rrMonth":0 } ] }, "quotes":[ { "carrierCode":"ESRNC", "carrierName":"Esurance", "error":"We are currently unable to provide a quote from Esurance for an unexpected reason. We will look to resolve shortly." } ], "purchaseUrl":"https://coverhound.com/resume/167565ae-83f4-45d5-b8e1-21032c29e41a?source=202", "purchasePhone":"8556419932" }

userId

string
Identifier you use to identify the customer.

transactionId

string
Unique identifier for this request.

customerId

integer
Identifier we use to identify the customer.

coverages

object
The same representation of coverages as in the request but with eventual changes or default values.

quotes

array
For successful quotes, contains array of payment plans and array of discounts. For unsuccessful quotes, contains error message. Both contain carrier code and carrier name.

purchaseUrl

string
A link to CoverHound where the shopper can retrieve their quotes and finalize the transaction.

purchasePhone

string
A phone line to CoverHound where the shopper can ask for advice and finalize the transaction.

Response with errors

Status code: 400, Bad syntax or bad data. If JSON is well formed, the errors object will describe any data problems.

  {
    "status":400,
    "message":"applicant[vehicles][ownership] does not have a valid value",
    "errors":{
      "applicant[vehicles][ownership]":[
        "does not have a valid value"
      ]
    }
  }

Status code: 401, Bad API key. Either the API key is missing or invalid.

  {
    "status":"Fail",
    "error_message":"Bad Key"
  }

Status code: 503, Timeout. Service unavailable or carrier unresponsive.

  {
    "status":503,
    "message":"The service is currently unavailable due to a server failure."
  }

Status code: 5xx, Something is wrong on CoverHound's side.

Polling

Why should I use polling?

There are two major benefits to using polling:

Speed

If you request quotes from multiple carriers, polling allows you to receive quotes as they become available. When using a single request, you need to wait until all quotes are available before you receive any. So if Carrier A is ready in 6 seconds and Carrier B takes 30 seconds, polling allows you to receive and display the Carrier A quote in 6 seconds and the Carrier B quote in 30 seconds. If you use a single, long-running request you will receive quotes from both Carrier A and Carrier B after 30 seconds.

Scaling

Polling allows us to serve many concurrent requests because all of the requests can be answered quickly. If you send many concurrent long-running requests, our servers may become overloaded and performance will suffer

How do I use polling?

In your initial request, send a top-level entry for "usePolling": true. You will get back a response that looks something like this:

  {
    "userId":"john.walsh.id",
    "transactionId":"232c552e-3756-43a6-a641-be32755e28d3",
  }

You can then use that transactionId and check this endpoint for updates:

  GET https://coverhound.com/api/auto/quotes/[transactionId]
  Accept: application/json
  Content-type: application/json
  Access-Token: f3657af5975b2fd1b148307570a4c2fe

We suggest a polling interval of 5 seconds. The responses mirror those without polling where quotes are added as they complete. Quotes can have statuses of started, error or complete.

  {
    [...]
    "quotes": [
      {
        "carrierCode": "SAFEC",
        "carrierName": "Safeco",
        "status": "error",
        "error": "Safeco does not wish to quote this risk type."
      },
      {
        "carrierCode": "CSEI",
        "carrierName": "CSE",
        "status": "started"
      },
      {
        "carrierCode": "PROGR",
        "carrierName": "Progressive",
        "status": "complete",
        "payPlans": [...],
        "purchaseUrl": ""
      }
    ]
  }