Proxy

Overview

Axle’s Ignition session is the main interface that allows your users to connect to their insurance accounts and authorize access to scoped data from their insurance policies. However, sometimes insurance information is shared to you on behalf of your user, such as when an insurance carrier or agent sends documents via mail directly to the policy lienholder. In these cases, you can “proxy” an Ignition session, effectively sharing information on behalf of your user instead of initializing Ignition for the user to complete it themself. Axle will then process and/or verify this information, depending on the use case.

When proxying an Ignition session, you are agreeing that you have received consent from user to share their insurance information with Axle, a data processor, as persuant to Axle’s Privacy Policy and End User Terms.

Configure Ignition to receive webhooks

Ensure that the request made to generate an Ignition token includes the webhookUri where you would like to receive Ignition events.

Request Sample: cURL

curl --request POST \
  --url https://api.axle.insure/ignition \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
  --header 'x-client-secret: RZM-5BErZuChKqycbCS1O' \
  --data '{
  "webhookUri": "https://example.com/webhook",
  "user": {"id": "usr_123456789"},
  "template": "template_abc123"
}'

The Axle Team can set up Ignition templates to overwrite the default configuration that is set per client.To apply one, pass the template in the Start Ignition request body. The template scopes to that single Ignition session. Contact the Axle team to set up a template.

Send proxy request

Select a supported operation and provide the required insurance information for the operation in the POST /ignition/{ignitionToken}/proxy request body. See Proxy Ignition API reference for more details on how to invoke the Proxy Ignition endpoint.

When Proxy Ignition request is made, Axle will queue the proxy operation immediately. Completion times may vary by operation and current Axle volume, but will be under 24 hours.

Process Ignition events

Once the submitted insurance information has been processed and/or verified, an POST request will be sent to the webhookUri specified when generating the Ignition session. See Ignition events for more details on the payloads of each event.

ignition.completed
ignition.attempted
ignition.errored

Continue from Step 3 in the Quickstart guide. In summary, you will need to exchange the short-lived authCode specified for an accessToken, which can then be used to retrieve Axle Account and Policy objects.

The result of the ignition.completed event will be the selected proxy operation. If you are using the same webhookUri across proxied and non-proxied Ignition sessions, you can use this result to filter the events.

Fired when the operation was attempted but could not be completed due to invalid or incompatible inputs, or a policy-related block such as an inactive policy or missing lienholder. Unlike ignition.errored, which indicates a system error, this event reflects an issue with the provided data or policy state. The errorCode identifies the specific issue — correcting the inputs or resolving the policy condition before retrying may result in a different outcome.

Fired when the operation failed due to a system error. Unlike ignition.attempted, this event is not caused by the provided inputs or policy state. The errorCode and message can be used to determine next steps — retrying the Proxy Ignition request may result in a different outcome.

Supported operations

Currently, only certain Ignition proxy operations are supported. Please reach out to the Axle team if you would like to request new operations.

Process insurance carrier policy document into Axle Policy

Leverage Axle’s Document AI to extract information from a policy document, such as a declarations page, policy renewal, ID card, or new business binder, and transform it into an Axle Policy object.In the request body, you must provide the following:

operation: process-document
input:
- name for the document (such as the unique identifier of the document in your system)
- source of the document (either user or carrier)
- policyType of the document (auto or home)
- url that can used to access the document.
This operation supports documents in the following formats: pdf, jpg, jpeg, and png. The url must directly serve the document via a HTTP GET request. For security, it is recommended to use a url with an 24-hour expiry, such as an AWS S3 signed url.

Example request body

{
  "operation": "process-document",
  "input": {
    "name": "DOC_ABC",
    "source": "carrier",
    "policyType": "auto",
    "url": "https://your-document-bucket.s3.amazonaws.com/declarations-page.pdf"
  }
}

If the operation does not succeed, you may receive an ignition.attempted event or an ignition.errored event.

`ignition.attempted` webhook event

errorCode	message	When it occurs
`document-data-empty`	The uploaded document appears to be empty. Please try uploading it again.	The document url was empty, the downloaded document had no data, or Axle’s Document AI determined the uploaded file was empty or an invalid PDF.
`document-download-failed`	We were unable to retrieve the document you provided. Please check the file and try again.	The file could not be downloaded from the specified url.
`unsupported-document`	Please make sure to upload an image or pdf document with your policy information clearly legible.	The document was not supported by Axle’s Document AI as it is either the wrong format, not legible, or not an insurance document.
`unsupported-document`	The extracted text does not appear to be a valid insurance document	Document AI extracted text from the document, but it didn’t validate as an insurance document.
`document-type-not-supported`	This document type is not supported by the current client	The document type is not enabled for this client.
`document-type-not-supported`	This document type is not currently supported by Document AI	The document type is not supported by Document AI.
`document-missing-fields`	The document is missing required data fields	Document AI parsed the document but required fields (e.g. carrier) could not be extracted from it.
`ignition-completed`	Ignition session is already completed. Please create a new Ignition session.	The Ignition session has already completed. Create a new Ignition session before retrying.

`ignition.errored` webhook event

errorCode	message	When it occurs
`default`	Oops something went wrong. Please try again later.	An unknown error occurred. Retrying may result in a successful operation.

Lookup insurance policy using policy details

Leverage Axle’s carrier integrations to lookup insurance policy information.In the request body, you must provide the following:

operation: policy-lookup
input:
- Exactly one of carrier ID or naicCode. Use the Get Carriers endpoint for a list of supported carriers and their IDs.
- policyType of the policy (auto, home, or condo)
- policyNumber of the policy
For auto policies:
- vin of the vehicle
- insuredName of the primary policyholder (either a full name string such as "John Smith" or an object with firstName and lastName)
- address mailing address of the primary policyholder (either a string such as "123 Main Street, New York, NY 10001" or an address object with addressLine1, addressLine2, city, state, postalCode, and country)
For home and condo policies:
- address property address (either a string such as "123 Main Street, New York, NY 10001" or an address object with addressLine1, addressLine2, city, state, postalCode, and country)
- insuredName of the primary policyholder (either a full name string such as "John Smith" or an object with firstName and lastName)

Instead of carrier, you may provide naicCode to identify the carrier by NAIC code (e.g., "11851" for Progressive).

Auto
Home / Condo

Example request body

{
  "operation": "policy-lookup",
  "input": {
    "carrier": "progressive",
    "policyType": "auto",
    "policyNumber": "123456789",
    "vin": "1HGCM82633A004352",
    "insuredName": "John Smith",
    "address": "123 Main Street, New York, NY 10001"
  }
}

Use naicCode instead of carrier

{
  "operation": "policy-lookup",
  "input": {
    "naicCode": "11851",
    "policyType": "auto",
    "policyNumber": "123456789",
    "vin": "1HGCM82633A004352",
    "insuredName": {
      "firstName": "John",
      "lastName": "Smith"
    },
    "address": {
      "addressLine1": "123 Main St",
      "addressLine2": null,
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }
}

Example request body

{
  "operation": "policy-lookup",
  "input": {
    "carrier": "progressive",
    "policyType": "home",
    "policyNumber": "123456789",
    "address": {
      "addressLine1": "123 Main St",
      "addressLine2": null,
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "insuredName": "John Smith"
  }
}

Use naicCode instead of carrier

{
  "operation": "policy-lookup",
  "input": {
    "naicCode": "11851",
    "policyType": "home",
    "policyNumber": "123456789",
    "address": "123 Main Street, New York, NY 10001",
    "insuredName": "John Smith"
  }
}

If the operation does not succeed, you may receive a 400 Bad Request response, an ignition.attempted event, or an ignition.errored event.

400 Bad Request

errorCode	message	When it occurs
`user-input-invalid`	Invalid input for operation “policy-lookup”.	Required fields are missing or invalid.
`user-input-invalid`	Sorry, the provided address is invalid or we are unable to process this address. Please update and try again.	The provided address could not be parsed or validated.
`carrier-not-found`	Carrier not found. Please verify the carrier and try again.	The provided carrier identifier (`carrier` ID or `naicCode`) is invalid or not supported.
`policy-lookup-not-supported`	This carrier does not support policy lookup.	The carrier does not support this operation.
`policy-lookup-not-supported`	This carrier does not support policy lookup for type .	The carrier does not support this operation for the specified policy type.
`ignition-processing`	A request for this Ignition session is already in progress. Please retry once the current operation has completed.	The request was submitted while another request for the same Ignition session is still in process. This error is primarily used for when an ignition session is invoked via proxy.
`no-credentials`	No active lienholder portal credentials were found for the provided carrier. Please contact Axle to set up credentials.	The client does not have lienholder portal credentials configured for this carrier.

500 Internal Server Error

errorCode	message	When it occurs
`default`	Oops something went wrong. Please try again later.	Default when an unexpected server error occurs. Retrying may succeed.

`ignition.attempted` webhook event

errorCode	message	When it occurs
`user-input-invalid`	Your lookup is invalid or the policy cannot be found. Verify you have the correct details and try again.	The policy could not be found with the provided details. Update the input fields (e.g. policy number, VIN, address) before trying again.
`lienholder-required`	Sorry, we are unable to access this policy because there is no lienholder present or the lienholder provided is not listed on this policy. Please try again with another verification method.	No lienholder is present, or the requesting client is not the lienholder on file.
`policy-not-active`	Policy is not active.	The policy exists but is not currently active.
`policy-active-unknown`	Sorry, we didn’t find any compatible policies. Please try again using another verification method.	The policy status could not be confirmed as active.
`ignition-completed`	Ignition session is already completed. Please create a new Ignition session.	The Ignition session has already completed. Create a new Ignition session before retrying.
`policy-type-mismatch`	We were able to locate the policy but do not yet support this policy type. Please check back soon as we work on adding support.	The policy was found, but its type does not match the requested `policyType` or is not yet supported by Axle.

`ignition.errored` webhook event

errorCode	message	When it occurs
`default`	Oops something went wrong. Please try again later.	Default when an unexpected server error occurs. Retrying may succeed.

Home

Guides

API Reference

Advanced

Overview

Configure Ignition to receive webhooks

Send proxy request

Process Ignition events

Supported operations

`ignition.attempted` webhook event

`ignition.errored` webhook event

400 Bad Request

500 Internal Server Error

`ignition.attempted` webhook event

`ignition.errored` webhook event

​Overview

Configure Ignition to receive webhooks

Send proxy request

Process Ignition events

​Supported operations

​ignition.attempted webhook event

​ignition.errored webhook event

​400 Bad Request

​500 Internal Server Error

​ignition.attempted webhook event

​ignition.errored webhook event

Overview

Supported operations

`ignition.attempted` webhook event

`ignition.errored` webhook event

400 Bad Request

500 Internal Server Error

`ignition.attempted` webhook event

`ignition.errored` webhook event