Cancel Policy Transaction

Cancels a policy as of a given date via a CANCEL transaction. The policy must be Active at the cancellation date. The action sets policyStatus to cancelled from the cancellation date through the end of the policy term and records a policyEarlyTerminationDate on fullTermPolicyInfo.

Optional fullTermDeltas allow adjusting fullTermPolicyBilling fields (e.g. short-rate penalties, cancellation fees). Only fullTermPolicyBilling-prefixed paths are accepted — per-segment data and policy dates are not modifiable via cancel. Dates are not accepted on these deltas because they always span the full policy term; the server injects them.

Required permission: company.policy:update

POST /api/v1/external/companies/{companyId}/policies/{policyId}/transaction/cancel

cURL

simpleCancellation

curl --request POST \
  --url https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/transaction/cancel \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cancellationDate": "2025-06-15"
}
'

201

success

{
  "policyId": "550e8400-e29b-41d4-a716-446655440001",
  "policyVersion": 2,
  "transactionId": "550e8400-e29b-41d4-a716-446655440040",
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "createdAt": "2025-06-15T10:30:00.000Z",
  "fullTermPolicyInfo": {
    "policyStatus": "active",
    "policyStartDate": {
      "year": 2025,
      "month": 1,
      "day": 1,
      "timezone": "America/New_York"
    },
    "policyEndDate": {
      "year": 2025,
      "month": 12,
      "day": 31,
      "timezone": "America/New_York"
    },
    "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440010",
    "policyEarlyTerminationDate": "2025-06-15"
  },
  "fullTermPolicyBilling": {
    "policyPremium": 85000,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 85500
  },
  "segments": [
    {
      "startDate": "2025-01-01",
      "endDate": "2025-06-14",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "active",
          "annualPremium": 85000,
          "fullTermPolicyInfo": {
            "policyStatus": "active",
            "policyStartDate": {
              "year": 2025,
              "month": 1,
              "day": 1,
              "timezone": "America/New_York"
            },
            "policyEndDate": {
              "year": 2025,
              "month": 12,
              "day": 31,
              "timezone": "America/New_York"
            },
            "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440010",
            "policyEarlyTerminationDate": "2025-06-15"
          },
          "fullTermPolicyBilling": {
            "policyPremium": 85000,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 85500
          }
        }
      }
    },
    {
      "startDate": "2025-06-15",
      "endDate": "2025-12-31",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "cancelled",
          "annualPremium": 85000,
          "fullTermPolicyInfo": {
            "policyStatus": "active",
            "policyStartDate": {
              "year": 2025,
              "month": 1,
              "day": 1,
              "timezone": "America/New_York"
            },
            "policyEndDate": {
              "year": 2025,
              "month": 12,
              "day": 31,
              "timezone": "America/New_York"
            },
            "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440010",
            "policyEarlyTerminationDate": "2025-06-15"
          },
          "fullTermPolicyBilling": {
            "policyPremium": 85000,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 85500
          }
        }
      }
    }
  ]
}

Authorizations

Authorization · string · header · required

API key authentication. Include your API key in the Authorization header.

Path Parameters

companyId · string<uuid> · required

Company identifier

policyId · string<uuid> · required

Policy identifier

Body

application/json

cancellationDate · string<date> · required

The date the cancellation takes effect in ISO 8601 format. Must fall within the policy term, and the policy must be Active at this date.

transactionTimestamp · string<date-time>

When the business decision was made. Defaults to the current time if omitted. Set explicitly for imports (e.g., aligning to a bordereau booking date).

fullTermDeltas · object[]

Optional billing-only deltas. Each delta specifies a fullTermPolicyBilling path and a new value. These are applied as Overwrite actions across the full policy term (since fullTermPolicyBilling is a cross-segment invariant that must be identical in every segment).

Show child attributes

Response

201

application/json

Policy cancelled successfully

Response returned by policy transaction endpoints. Contains the policy version produced by the transaction, including all derived segments.

policyId · string<uuid> · required

Policy identifier

policyVersion · integer · required

Sequential version number produced by this transaction

transactionId · string<uuid> · required

Identifier of the transaction that produced this version

startDate · string<date> · required

Policy term start date (ISO 8601)

endDate · string<date> · required

Policy term end date (ISO 8601)

createdAt · string<date-time> · required

When the transaction was created (ISO 8601)

segments · object[] · required

Derived segments for this policy version. Each segment represents a maximal contiguous date range where policy state is identical. Adjacent segments with identical data are automatically merged.

Show child attributes

fullTermPolicyInfo · object

Full-term policy information. Contains policy status, term dates, and primary insured reference.

fullTermPolicyBilling · object

Full-term billing aggregates. Contains premium, taxes, fees, and grand total for the full policy term.