> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axle.insure/llms.txt
> Use this file to discover all available pages before exploring further.
# Proxy
> As an alternative to initializing Ignition, proxy insurance information on behalf of your user to Axle for processing and/or verification.
### 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](https://www.axle.insure/legal/privacy-policy) and
[End User Terms](https://www.axle.insure/legal/end-user-terms).
Ensure that the request made to generate an Ignition token includes the `webhookUri` where you would like to receive Ignition events.
```bash Request Sample: cURL theme={null}
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"}
}'
```
Select a supported [`operation`](/guides/proxy-ignition#supported-operations) and provide the required insurance information for the operation in the `POST /ignition/{ignitionToken}/proxy` request body. See [Proxy Ignition](/api-reference/ignition/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.
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](/guides/ignition-events) for more details on the payloads of each event.
Continue from Step 3 in the [Quickstart](/guides/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.
Each operation will specify different `message`, which can be used to
determine next steps. Unless specified, retrying the Proxy Ignition request
with the same submitted insurance information will not 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.
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](/api-reference/policies/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.
```json Example request body theme={null}
{
"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, one of the following messages will be returned as part of the `ignition.errored` event, which you can use to determine next steps.
* `Document data is empty.` - The document had no data.
* `Failed to download the file from the specified url.` - The file could not be downloaded from the specified url. Please ensure that the url directly serves the 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 DocumentAI as it is either the wrong format, not legible, or not an insurance document.
* `Oops something went wrong. Please try again later.` - An unknown error occured. Retrying may result in a successful operation.
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](/api-reference/carriers/get-carriers) 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).
```json Example request body theme={null}
{
"operation": "policy-lookup",
"input": {
"carrier": "progressive",
"policyType": "auto",
"policyNumber": "123456789",
"vin": "1HGCM82633A004352",
"insuredName": "John Smith",
"address": "123 Main Street, New York, NY 10001"
}
}
```
```json Use naicCode instead of carrier theme={null}
{
"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"
}
}
}
```
```json Example request body theme={null}
{
"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"
}
}
```
```json Use naicCode instead of carrier theme={null}
{
"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 or an `ignition.errored` event.
#### 400 Bad Request
| errorCode | message | When it occurs |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user-input-invalid` | Invalid input for operation "policy-lookup". {validationDetails} | 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 {policyType}. | 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.errored` 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. |
| `default` | Oops something went wrong. Please try again later. | An unknown error occurred during the lookup. Retrying may succeed. |