> ## 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.

# Policy Actions

> Execute an action on a policy on behalf of your user.

## 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`.

```bash Request Sample: cURL theme={null}
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.

```json Response Sample theme={null}
{
  "success": true,
  "data": {
    "id": "pla_mZj6YGXhQyQnccN97aXbq"
  }
}
```

## Webhooks

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

<Tip>
  You must specify a `webhookUri` when generating an Ignition token to receive
  webhook events. See [Start Ignition](/api-reference/ignition/start-ignition)
  for more details.
</Tip>

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`.

```json Example webhook payload theme={null}
{
  "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`.

### 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

After a successful insurance carrier request, Axle was able to retrieve the latest policy data.

### policy-action.policy-refresh-failed

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. |