Policy Actions

Overview

Policy actions allow you to request carrier-side changes to a policy on behalf of your user. Once submitted, Axle will process the request and the policy will be updated once the action is complete. The following operations are currently supported:

Operation	Description
`request-primary-lienholder`	Request that your organization be added as the primary lienholder on the policy.

Executing a Policy Action

Submit a POST /policies/{policyId}/actions request with the desired operation.

Request Sample: cURL

curl --request POST \
  --url https://api.axle.insure/policies/pol_mZj6YGXhQyQnccN97aXbq/actions \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
  --header 'x-client-secret: RZM-5BErZuChKqycbCS1O' \
  --data '{
  "operation": "request-primary-lienholder"
}'

A successful response returns the ID of the created policy action and an processesInstantly flag.

Response Sample

{
  "success": true,
  "data": {
    "id": "pla_mZj6YGXhQyQnccN97aXbq",
    "processesInstantly": false
  }
}

Webhooks

A POST request will be sent to the webhookUri you provided when generating the Ignition token at each stage of the action lifecycle.

You must specify a webhookUri when generating an Ignition token to receive webhook events. See Start Ignition for more details.

All policy action webhook events include top-level id, type, and createdAt. The data object includes client, policy, operation, input, and optionally user and metadata.

Example webhook payload

{
  "id": "<event_id>",
  "type": "policy-action.request-initiated",
  "data": {
    "client": "<client-id>",
    "policy": "<policy-id>",
    "operation": "request-primary-lienholder",
    "user": {
      "firstName": "John",
      "lastName": "Doe",
      "id": "usr_123456789",
      "email": "john.doe@gmail.com"
    },
    "metadata": {
      "claimNumber": "123456"
    },
    "input": {
      "lenderCode": "ABC123"
    },
    "createdAt": "2026-01-01T00:00:00.000Z",
  }
}

Event types

Events follow this lifecycle: policy-action.request-initiated -> policy-action.request-succeeded or policy-action.request-failed -> (on success) policy-action.policy-refresh-succeeded or policy-action.policy-refresh-failed. Which events you receive depends on the processesInstantly flag returned by Execute Policy Action:

processesInstantly: true - If the policy action succeeds, the change is reflected on the policy right away. You’ll receive a policy-action.policy-refresh-succeeded or policy-action.policy-refresh-failed event right after policy-action.request-succeeded, confirming whether Axle was able to retrieve the updated policy.
processesInstantly: false - The effects of the policy action are not available immediately, even if the action itself was successful, so you’ll only receive events up through policy-action.request-succeeded or policy-action.request-failed. To find out when the policy has been updated as a result of the action, opt in to Monitoring to receive the policy.modified event.

policy-action.request-initiated

The action has been received and Axle has begun processing the insurance carrier request.

policy-action.request-succeeded

The insurance carrier successfully processed the request.

policy-action.request-failed

The insurance carrier request failed, or the action expired before completing.

policy-action.policy-refresh-succeeded

Sent only for policy actions where processesInstantly: true. After a successful insurance carrier request, Axle was able to retrieve the latest policy data.

policy-action.policy-refresh-failed

Sent only for policy actions where processesInstantly: true. After a successful insurance carrier request, Axle was unable to refresh the policy data. The carrier request itself succeeded, but the policy data may not yet reflect the change.

Error Codes

If the request does not succeed, you may receive a 400 Bad Request or 500 Internal Server Error response.

400 Bad Request

errorCode	message	When it occurs
`policy-action-not-supported`	Policy action `<operation>` is not supported for this policy.	The requested operation is not available for this policy.

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.

Home

Guides

API Reference

Advanced

Policy Actions

Overview

Executing a Policy Action

Webhooks

Event types

policy-action.request-initiated

policy-action.request-succeeded

policy-action.request-failed

policy-action.policy-refresh-succeeded

policy-action.policy-refresh-failed

Error Codes

400 Bad Request

500 Internal Server Error

​Overview

​Executing a Policy Action

​Webhooks

​Event types

​policy-action.request-initiated

​policy-action.request-succeeded

​policy-action.request-failed

​policy-action.policy-refresh-succeeded

​policy-action.policy-refresh-failed

​Error Codes

​400 Bad Request

​500 Internal Server Error

Overview

Executing a Policy Action

Webhooks

Event types

policy-action.request-initiated

policy-action.request-succeeded

policy-action.request-failed

policy-action.policy-refresh-succeeded

policy-action.policy-refresh-failed

Error Codes

400 Bad Request

500 Internal Server Error