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. Please first review the Quickstart guide and API docs on how to start an Ignition session, if you have not already.

​
Configure an Ignition session for event handling

Your POST request to /ignition can include the following request body:
  • redirectUri (optional) - the URL Axle Ignition will redirect the user to upon completion, exit, or error outcomes of the Ignition session, defaults to no redirect
  • webhookUri (optional) - the URL Axle will send events to as the user proceeds through the Ignition session, defaults to no webhook events
  • user (required) - user to attach. Please refer to startIgnition for more details.
  • metadata (optional) - optional Ignition session metadata, please refer to startIgnition for more details
Request Sample
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 '{
  "redirectUri": "https://example.com/insurance/redirect",
  "webhookUri": "https://example.com/insurance/webhook",
  "user": {"id": "usr_123456789"}
  }'
You can also receive Ignition status updates through the browser Window interface. This is most useful when initializing an Ignition session in an iframe element in your application.If you would like to receive MessageEvent messages to your main application Window from Ignition, you must specify an origin as a URL parameter when initalizing Ignition. The origin should not include any path, just the base domain as a URI.Example: https://ignition.axle.insure/?origin=http://example.com

​
Redirect and Window MessageEvent parameters

On Ignition status change, the following parameters will be shared via URL to the redirectUri provided and in the Window MessageEvent. status: String
  • complete
  • exit
  • error
Additional parameters (dependent on status, see below)
  • authCode: String - authorization code that can be exchange for accessToken for scoped access to connected account and/or policy
  • client: String - the client ID associated with the session. This is primarily useful for platforms who have multiple clients. See the Axle for Platforms guide for more information about platforms.
  • result: String - “link” (direct carrier connection was made and policy is available) OR “manual” (policy details were collected via document or form) OR “proxy” (operation was completed on behalf of user)
  • step: String - the step where the Ignition session was exited
  • message: String - additional information about the Ignition session error
Redirect sample URL
  https://example.com/insurance/redirect?status=complete&authCode=cod_LwPJhgxnjinMEPfGYc-XV&client=cli_mZj6YGXhQyQnccN97aXbq&result=link

​
onComplete

When the user successfully connects to their carrier account and shares authorized access to a selected policy, OR when the user submits their policy information and/or documentation through Axle’s manual collection form. 
{
  "status": "complete",
  "authCode": "<authCode>",
  "client": "<client-id>",
  "result": "link" || "manual" || "proxy"
}

​
onExit

When the user opts out of connecting to their carrier account and/or selecting a policy, OR when the user opts out of sharing the requested policy information and/or documentation. 
{
  "status": "exit",
  "step": "<step-name>",
  "client": "<client-id>"
}

​
onError

When Axle is unable to retrieve account or policy information from a selected carrier, OR when Axle is unable to collect policy information and/or documentation from the user. 
{
  "status": "error",
  "message": "<message-body>",
  "client": "<client-id>"
}
Never send requests from your client to the Axle API. The client should only be used to handle Ignition status through redirect or Window MessageEvent.

​
Webhooks

If an optional webhookUri is provided, a POST request will be sent to the webhookUri with the following payload. The individual parameters included within data are the same as those listed above for the corresponding status, with the addition of user and metadata shared via the Ignition request body:
Example webhook payload
{
  "id": "<event_id>",
  "type": "ignition.completed",
  "data": {
    "client": "<client-id>",
    "token": "ign_Z4ni-JHBvkn9PlKJHPEwk",
    ...{ parameters }
  },
  "createdAt": "2022-10-05T14:48:00.000Z"
}
TypeData
ignition.createdclient : String, token : String, user: Object, metadata: Object
ignition.completedclient : String, token : String, user: Object, metadata: Object, authCode : String, result : String
ignition.openedclient : String, token : String, user: Object, metadata: Object
ignition.exitedclient : String, token : String, user: Object, metadata: Object, step : String
ignition.erroredclient : String, token : String, user: Object, metadata: Object, message : String
Custom webhook headers can be configured to support uses cases like authentication. Please contact the Axle team if you would like to configure custom webhook headers!