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

# Request a policy update

> Send a policy update, override its details, and handle errors.

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

```bash Request Sample: cURL theme={null}
curl --request POST \
  --url https://api.axle.insure/policies/pol_mZj6YGXhQyQnccN97aXbq/updates \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
  --header 'x-client-secret: RZM-5BErZuChKqycbCS1O' \
  --data '{
  "operation": "update-third-party"
}'
```

A successful response returns the ID of the created policy update, a [`processesInstantly`](https://docs.axle.insure/guides/policy-updates#processesinstantly) flag, and `unsupportedInputs`, the [input](#input) fields that weren't sent to the insurance carrier.

```json Response Sample theme={null}
{
  "success": true,
  "data": {
    "id": "plu_mZj6YGXhQyQnccN97aXbq",
    "processesInstantly": false,
    "unsupportedInputs": []
  }
}
```

## Input

By default, Axle uses the details from your policy update configuration and the insurance carrier's own defaults. To set them for one request, pass them in `input`. Which fields an operation accepts, and how each insurance carrier handles them, is listed on the operation's page; see [Operations](https://docs.axle.insure/guides/policy-updates.md#operations).

```bash Request Sample: cURL theme={null}
curl --request POST \
  --url https://api.axle.insure/policies/pol_mZj6YGXhQyQnccN97aXbq/updates \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
  --header 'x-client-secret: RZM-5BErZuChKqycbCS1O' \
  --data '{
  "operation": "update-third-party",
  "input": {
    "effectiveDate": "2026-12-01",
    "loanNumber": "0022405666"
  }
}'
```

Each insurance carrier handles these fields differently:

* **Required:** some insurance carriers need a field to make the change. If it's missing from both `input` and your policy update configuration, Axle rejects the request with a `400` and the `policy-update-input-required` error code, and nothing is sent to the insurance carrier.
* **Not supported:** when an insurance carrier can't apply a field, Axle makes the change without it and lists the field in `unsupportedInputs`, in the response and in the policy update's [webhooks](https://docs.axle.insure/guides/policy-updates/events.md).

```json Response Sample: a field the insurance carrier can't apply theme={null}
{
  "success": true,
  "data": {
    "id": "plu_mZj6YGXhQyQnccN97aXbq",
    "processesInstantly": false,
    "unsupportedInputs": ["effectiveDate"]
  }
}
```

```json Response Sample: a required field is missing theme={null}
{
  "success": false,
  "message": "Policy update \"update-third-party\" requires loanNumber for this policy",
  "errorCode": "policy-update-input-required"
}
```

> [!NOTE]
>
> `input` only accepts the fields its operation lists. Any other key, or one of these fields sent outside `input`, returns a `400`.

## Error codes

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

### 400 Bad Request

| errorCode | message | When it occurs |
| - | - | - |
| `policy-update-not-supported` | Policy update `<operation>` is not supported for this policy. | The requested operation is not available for this policy. |
| `policy-update-input-required` | Policy update `<operation>` requires `<fields>` for this policy. | A field the policy's insurance carrier needs is missing from both [`input`](#input) and your policy update configuration. |

### 409 Conflict

| errorCode | message | When it occurs |
| - | - | - |
| `policy-update-in-progress` | A policy update is already in progress for this policy. Please try again later. | Another policy update on this policy hasn't finished yet. Wait for its webhook events before sending the next one. |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.