API Reference

Getting Started

Session Information

The Auto Insurance API requires basic sessionInformation (the end user's IP address and user agent) with every offer search.
Carriers use this information as part of underwriting, compliance, and fraud-prevention checks, so it must be collected from the live user session and passed through accurately.

Authentication & Environments

A representative from Engine by Gen will set up an account and provide an authorization token to access the Engine API.

An authorization token is required to authenticate every request. Include it in the request headers; otherwise the API returns an error.
Every request must also include an Api-Version header. The current supported version for the Auto Insurance API is 2026-02-25.
Test and production tokens are separate. Requests made with a test token are not reflected in performance reporting or payable events. Switch to the production token once testing is complete.
A test token only works against the test environment, and a production token only works against production. Using a token against the wrong environment returns 401 Unauthorized.
For more information, see our API Reference page

Environment

Base URL

Token Type

Test / Dev

https://dev-api.engine.tech

Test authorization token

Production

https://api.engine.tech

Production authorization token

Rate tables are environment-specific

A uuid created in the test environment cannot be polled against production (and vice versa). Doing so returns 404 Not Found.

Required Headers

Header

Value

Authorization

Bearer <AUTH_TOKEN>

Api-Version

Most recent API Version, e.g. 2026-02-25

Content-Type

application/json

Step 1: Retrieve Supported Issuers

Before submitting an offer search, retrieve the list of supported insurance carriers:

curl --location 'https://api.engine.tech/leads/autoInsurance/issuers' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/json'

Example response:

[
  {
    "id": "statefarm",
    "name": "State Farm",
    "logoImageUrl": "https://cdn.trellisconnect.com/sdk/v1.1/assets/images/logos/statefarm.ico"
  }
]

Pass the issuer's id as the value of autoInsuranceInformation.currentIssuer in your offer search:

{
  "autoInsuranceInformation": {
    "currentIssuer": "statefarm"
  }
}

The name and logoImageUrl fields are provided for display purposes only. Use the id value when making requests.

Step 2: Submit the Offer Search

Set productTypes to ["AutomobileInsurance"]
Submit a POST request to /offerSearches/

Sample Request/Response

curl --location 'https://api.engine.tech/offerSearches/' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Api-Version: 2026-02-25' \
--header 'Content-Type: application/json' \
--data '{
  "autoInsuranceInformation": {
    "currentIssuer": "notinsured",
    "policyHolderInformation": {
      "isHomeOwner": true,
      "isMilitary": false
    },
    "numberOfVehicles": 1
  },
  "sessionInformation": {
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0"
  },
  "personalInformation": {
    "zipcode": "94103",
    "dateOfBirth": "1990-06-15"
  },
  "clientTags": {
    "subId": ["2ee169ef"]
  },
  "productTypes": [
    "AutomobileInsurance"
  ]
}

{
  "uuid": "11111111-1111-4111-8111-111111111111",
  "leadUuid": "22222222-2222-4222-8222-222222222222",
  "createdAt": "2026-08-25T19:30:00.000Z",
  "pendingResponses": [],
  "offers": [
    {
      "uuid": "33333333-3333-4333-8333-333333333333",
      "productType": "AutomobileInsurance",
      "productDisplayName": "Example Auto Insurance",
      "productVersions": [2],
      "version": 1,
      "status": "active",
      "headline": "Get an auto insurance quote",
      "descriptionPoints": [
        "Compare coverage options",
        "View sample rates in minutes",
        "Manage your policy online"
      ],
      "url": "https://offers.engine.tech/channelTrackingOfferRedirects/11111111-1111-4111-8111-111111111111/33333333-3333-4333-8333-333333333333",
      "unmonetizedUrl": "https://www.example.com/auto-insurance",
      "isMonetized": true,
      "financialInstitutionUuid": "44444444-4444-4444-8444-444444444444",
      "financialInstitutionDisplayName": "Example Auto Insurance",
      "financialInstitutionImageUrl": "https://cdn.example.com/logos/example-auto.png",
      "recommendationScore": 14,
      "rank": 1,
      "createdAt": "2026-08-25T19:30:01.000Z",
      "updatedAt": "2026-08-25T19:30:01.000Z"
    },
    {
      "uuid": "55555555-5555-4555-8555-555555555555",
      "productType": "AutomobileInsurance",
      "productDisplayName": "Sample Mutual",
      "productVersions": [2],
      "version": 1,
      "status": "active",
      "headline": "Compare auto insurance rates",
      "descriptionPoints": [
        "Customize your coverage",
        "Discounts may be available",
        "24/7 customer support"
      ],
      "url": "https://offers.engine.tech/channelTrackingOfferRedirects/11111111-1111-4111-8111-111111111111/55555555-5555-4555-8555-555555555555",
      "unmonetizedUrl": "https://www.example.com/sample-mutual",
      "isMonetized": true,
      "financialInstitutionUuid": "66666666-6666-4666-8666-666666666666",
      "financialInstitutionDisplayName": "Sample Mutual",
      "financialInstitutionImageUrl": "https://cdn.example.com/logos/sample-mutual.png",
      "recommendationScore": 13,
      "rank": 2,
      "createdAt": "2026-08-25T19:30:01.000Z",
      "updatedAt": "2026-08-25T19:30:01.000Z"
    }
  ]
}

Request Fields

Fields marked Recommended for POST /offerSearches/ are technically optional, but providing them meaningfully improves quote accuracy and offer matching.

Omitting an optional field implies "no information" for that attribute.

Required fields

Field

Type

Purpose

productTypes

array of strings

Types of products the user is interested in. Use ["AutomobileInsurance"].

sessionInformation.ipAddress

string

IP address of the end user's live session, used for underwriting and fraud checks.

sessionInformation.userAgent

string

User agent string of the end user's browser or device, captured from the live session.

Recommended fields

Field

Type

Purpose

autoInsuranceInformation.currentIssuer

string

The lead's current or most recent auto insurance carrier. Use "notinsured" if the lead has no current coverage. Must be a valid issuer ID returned by GET /leads/autoInsurance/issuers.

autoInsuranceInformation.numberOfVehicles

integer

Number of vehicles the lead wants to insure.

autoInsuranceInformation.policyHolderInformation.isHomeOwner

boolean

Whether the lead owns their home. Used by carriers as a rating factor and may unlock bundling discounts.

autoInsuranceInformation.policyHolderInformation.isMilitary

boolean

Whether the lead is active-duty military, an honorable veteran, or a military family member. Used to surface military discounts.

personalInformation.zipCode

string

ZIP code of the lead's residence. Used to match the lead with carriers licensed in their state and to rate the offer.

personalInformation.dateOfBirth

string

Date of birth of the lead, in YYYY-MM-DD format. Used for age-based eligibility and rating.

Optional tracking fields

Field

Type

Purpose

clientTags

array of strings

Client-defined tag(s) for tracking and attribution, such as a sub-affiliate or campaign ID. See Client Tags for Attribution below.

Client Tags for Attribution

Partners can optionally pass clientTags.subId, an array of client-defined string tags, with each offer search request.

Engine includes these tags in reporting, letting a partner attribute leads and revenue back to a specific sub-affiliate, campaign, or placement. This field has no effect on which offers are returned; it is purely for tracking.

See the Attribution Tracking page for more information

Step 3: Poll for the Rate Table

Capture the uuid returned in the Step 1 response and issue a GET request to the Offer Searches endpoint:

GET https://api.engine.tech/offerSearches/{uuid}

Polling Process

After the POST in Step 1, poll GET /offerSearches/{uuid} once per second for up to 15 seconds.
Check pendingResponses on each response:
- Not empty: Engine is still waiting on one or more partners. Keep polling.
- Empty: Every partner has finished. Stop polling; offers is the final set.
As each partner responds, its offers are added to offers and that partner is removed from pendingResponses.

Sample Responses

Immediately after submitting the offer search, the response may show no offers yet, with one or more partners listed under pendingResponses:

{
 "uuid": "6204740b-25ca-407a-9927-d229c2b3e315",
 "leadUuid": "ad5cc266-b358-4c57-85f1-968f746ae0e4",
 "offers": [],
 "pendingResponses": [
 {
 "partner": {
 "uuid": "0ac9a64b-177f-4699-910b-7c301772331a",
 "name": "Sample Carrier Co.",
 "description": "-",
 "disclaimer": "-",
 "supportsPreSelect": false,
 "shouldDisplayPreSelect": false,
 "supportsPersonalizedOffers": true,
 "imageUrl": "https://images.engine.tech/logos/dev/sample-carrier-autoinsurance.svg",
 "brandName": "Sample Carrier",
 "brandUuid": "871f6802-d27d-4092-8f82-d1d205c7a478"
 },
 "offerCatalogProductTypes": [
 "AutomobileInsurance"
 ]
 }
 ],
 "createdAt": "2026-07-30T17:58:31.957182Z"
}

Once a partner has responded, its offer(s) appear in the offers array and pendingResponses no longer contains that partner:

{
 "uuid": "6204740b-25ca-407a-9927-d229c2b3e315",
 "leadUuid": "ad5cc266-b358-4c57-85f1-968f746ae0e4",
 "offers": [
 {
 "descriptionPoints": [
 "Free rate quote online — no sales calls",
 "Compare top carrier rates instantly, save up to $800+/yr",
 "Shop trusted carriers to find your best rate",
 "Rates starting as low as $12/wk. Save now!"
 ],
 "impressionTrackingPixelUrls": [
 "https://track.engine.tech/p/impr.gif?ad_pos=1&ad_num=1;<tracking_token>"
 ],
 "uuid": "88090bc3-dda6-445b-bb91-5a1e53dc18a5",
 "version": 1,
 "url": "https://offers.engine.tech/ref/999dfd70-e06e-466d-a8ad-e35661ba5423",
 "unmonetizedUrl": "https://offers.engine.tech/uref/999dfd70-e06e-466d-a8ad-e35661ba5423",
 "recommendationScore": 11,
 "productDisplayName": "Compare-Discounts",
 "rank": 1,
 "headline": "Compare Auto Insurance Rates From Top-Rated Carriers",
 "productType": "AutomobileInsurance",
 "status": "active",
 "isMonetized": true,
 "financialInstitutionUuid": "8f04c171-85db-4753-bdc7-31bb11c59f4c",
 "financialInstitutionImageUrl": "https://images.engine.tech/logos/dev/sample-carrier-logo.png",
 "financialInstitutionDisplayName": "Sample Auto Insurance Provider"
 }
 ],
 "pendingResponses": [],
 "createdAt": "2026-07-30T17:58:31.957182Z"
}

Response Fields

Field

Type

Description

Example

uuid

string

Rate table UUID. Use this value to poll the rate table endpoint.

"6204740b-25ca-407a-9927-d229c2b3e315"

leadUuid

string

Unique identifier for the lead associated with the offer search.

"ad5cc266-b358-4c57-85f1-968f746ae0e4"

offers

array

Array of completed auto insurance offers returned so far. See Offer Fields below.

—

pendingResponses

array

Array of partners Engine is still waiting to hear back from. Keep polling while this array is non-empty.

—

pendingResponses[].partner

object

Metadata about a partner whose response is still pending. See Partner Fields below.

—

pendingResponses[].offerCatalogProductTypes

array of strings

Product type(s) the pending partner was queried for.

["AutomobileInsurance"]

createdAt

string (ISO 8601)

Timestamp the rate table was created.

"2026-07-30T17:58:31.957182Z"

Fields on pendingResponses[].partner. These describe a pending carrier/partner and supply the branding and disclosure content you may need to display.

Field

Type

Description

Example

uuid

string

Unique identifier for the partner.

"0ac9a64b-177f-4699-910b-7c301772331a"

name

string

Partner name.

"Sample Carrier Co."

brandName

string

Brand name shown to the consumer.

"Sample Carrier"

brandUuid

string

Unique identifier for the brand.

"871f6802-d27d-4092-8f82-d1d205c7a478"

imageUrl

string (url)

Partner/brand logo URL.

"https://images.engine.tech/logos/dev/sample-carrier-autoinsurance.svg"

description

string

Optional partner description. May be empty.

—

disclaimer

string

Partner-level disclaimer / license text. When populated, this must be displayed to the user. May be empty.

—

supportsPreSelect

boolean

Whether the partner supports pre-selection.

false

shouldDisplayPreSelect

boolean

Whether pre-selection should be displayed.

false

supportsPersonalizedOffers

boolean

Whether the partner supports personalized offers.

true

Field

Type

Description

Example

uuid

string

Unique identifier for the individual offer.

"88090bc3-dda6-445b-bb91-5a1e53dc18a5"

version

integer

Version number of the offer.

1

rank

integer

Engine's recommended display rank. Display offers in ascending order by rank (rank 1 first).

1

recommendationScore

number

Present in responses but not used for auto insurance ranking — use rank instead.

11

headline

string

Primary marketing headline to display on the offer card.

"Compare Auto Insurance Rates From Top-Rated Carriers"

descriptionPoints

array of strings

Marketing bullet points describing the offer. Display as checkmark bullets on the offer card.

["Free rate quote online — no sales calls", "..."]

productType

string

Product type of the offer.

"AutomobileInsurance"

productDisplayName

string

Display name for the product/offer type (e.g., internal labeling or subheadline).

"Compare-Discounts"

status

string

Status of the offer. Only display offers with status "active".

"active"

isMonetized

boolean

Whether the offer is monetized. Use with url / unmonetizedUrl.

true

url

string (url)

Click-through URL for the offer's monetized destination. Use as the "View Rate" CTA when isMonetized is true.

"https://offers.engine.tech/ref/..."

unmonetizedUrl

string (url)

Click-through URL for the offer's unmonetized destination. Use when the offer should not be tracked for monetization.

"https://offers.engine.tech/uref/..."

impressionTrackingPixelUrls

array of strings (url)

One or more tracking pixel URLs that must be fired when the offer is rendered/viewed. See Impression Tracking in Building Your UI.

["https://track.engine.tech/p/impr.gif?..."]

financialInstitutionUuid

string

Unique identifier for the carrier/financial institution offering the policy.

"8f04c171-85db-4753-bdc7-31bb11c59f4c"

financialInstitutionDisplayName

string

Display name of the carrier/financial institution.

"Sample Auto Insurance Provider"

financialInstitutionImageUrl

string (url)

URL of the carrier/financial institution's logo.

"https://images.engine.tech/logos/dev/sample-carrier-logo.png"

Response Codes & Error Handling

Successful Request (2xx)

`201 Created`

Endpoint: POST /offerSearches/

Meaning: The request was accepted and a rate table was created. This does not mean offers were returned.

Next action: Check offers and pendingResponses. Poll when pendingResponses is non-empty.

`200 OK`

Endpoint: GET /offerSearches/{uuid}

Meaning: The rate table was found and returned. offers may still be empty.

Next action: Check offers and pendingResponses. Keep polling until pendingResponses is empty.

Completed searches with no offers

An empty offers array and empty pendingResponses array means no matches were found. This is a silent failure. The request succeeded, but there are no offers to display.

Common causes include:

Missing FCRA consent.
State exclusions.
Missing required fields.
Automated risk screening.
Carrier unavailability.

Unsuccesful Request (4xx)

`400 Bad Request`

Endpoint: Any

Meaning: The request was malformed and was not processed.

Next action: Fix the malformed input.

Common causes:

Missing or invalid Api-Version header — required on every request; it must match a supported version, such as 2026-02-25.
Invalid JSON — the request body could not be parsed.
Malformed UUID — a path parameter, such as /offerSearches/{uuid}, used an invalid UUID format.

The response body contains error objects describing the failed field and reason.

`401 Unauthorized`

Endpoint: Any

Meaning: The authorization header is missing, expired, or invalid.

Next action: Verify the bearer token and environment. Test tokens only work with dev-api.engine.tech. Production tokens only work with api.engine.tech.

`404 Not Found`

Endpoint: GET /offerSearches/{uuid}

Meaning: The rate table UUID does not exist.

Next action: Verify the UUID and environment.

This can happen when:

The UUID was copied incorrectly.
A dev UUID is requested from production, or the reverse.

`422 Unprocessable Entity`

Endpoint: Any

Meaning: The Api-Version header is present, but its version string is not recognized.

Next action: Use a supported version. See Authentication & Environments.

Retry Request (429 & 5xx)

`429 Too Many Requests`

Endpoint: Any

Meaning: Too many requests were sent in a short window. This usually results from polling faster than the recommended cadence.

Next action: Slow polling, honor Retry-After when present, and retry with exponential backoff.

Poll no more than about once per second per rate table.
If Retry-After is present, wait that many seconds before retrying.
On repeated 429 responses, back off exponentially, such as 1s, 2s, then 4s.

`500` / `503` Server Error

Endpoint: Any

Meaning: Engine encountered a temporary internal error or is briefly unavailable. These responses are transient and are not caused by malformed input.

Next action: Retry with exponential backoff within the polling window. Contact your Engine representative if the error persists.

Retry with exponential backoff, such as 1s, 2s, then 4s.
Do not treat a single 5xx response as a failed search. Keep polling within your timeout window.
If 5xx responses continue past the timeout, stop polling and show a graceful error.

Last updated 2 days ago

Was this helpful?

Getting Started

Session Information

Authentication & Environments

Required Headers

Step 1: Retrieve Supported Issuers

Step 2: Submit the Offer Search

Sample Request/Response

Request Fields

Client Tags for Attribution

Step 3: Poll for the Rate Table

Polling Process

Sample Responses

Response Fields

Response Codes & Error Handling

Successful Request (2xx)

201 Created

200 OK

Unsuccesful Request (4xx)

400 Bad Request

401 Unauthorized

404 Not Found

422 Unprocessable Entity

Retry Request (429 & 5xx)

429 Too Many Requests

500 / 503 Server Error

`201 Created`

`200 OK`

`400 Bad Request`

`401 Unauthorized`

`404 Not Found`

`422 Unprocessable Entity`

`429 Too Many Requests`

`500` / `503` Server Error