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"
}
'

{
  "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": {
    "policyStartDate": {
      "year": 2025,
      "month": 1,
      "day": 1,
      "timezone": "America/New_York"
    },
    "policyEndDate": {
      "year": 2025,
      "month": 12,
      "day": 31,
      "timezone": "America/New_York"
    },
    "primaryInsuredJoin": "550e8400-e29b-41d4-a716-446655440010"
  },
  "fullTermPolicyBillingInfo": {
    "policyPremium": 42500,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 45500
  },
  "fullTermPolicyRatingResult": null,
  "segments": [
    {
      "startDate": "2025-01-01",
      "endDate": "2025-06-14",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "active",
          "cancellationEffectiveOnDate": {
            "year": 2025,
            "month": 6,
            "day": 15,
            "timezone": null
          },
          "annualPremium": 85000,
          "fullTermPolicyInfo": {
            "policyStartDate": {
              "year": 2025,
              "month": 1,
              "day": 1,
              "timezone": "America/New_York"
            },
            "policyEndDate": {
              "year": 2025,
              "month": 12,
              "day": 31,
              "timezone": "America/New_York"
            },
            "primaryInsuredJoin": "550e8400-e29b-41d4-a716-446655440010"
          },
          "fullTermPolicyBillingInfo": {
            "policyPremium": 42500,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 45500
          }
        }
      }
    },
    {
      "startDate": "2025-06-15",
      "endDate": "2025-12-31",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "cancelled",
          "cancellationEffectiveOnDate": {
            "year": 2025,
            "month": 6,
            "day": 15,
            "timezone": null
          },
          "annualPremium": 85000,
          "fullTermPolicyInfo": {
            "policyStartDate": {
              "year": 2025,
              "month": 1,
              "day": 1,
              "timezone": "America/New_York"
            },
            "policyEndDate": {
              "year": 2025,
              "month": 12,
              "day": 31,
              "timezone": "America/New_York"
            },
            "primaryInsuredJoin": "550e8400-e29b-41d4-a716-446655440010"
          },
          "fullTermPolicyBillingInfo": {
            "policyPremium": 42500,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 45500
          }
        }
      }
    }
  ]
}

Transactions

Cancel Policy Transaction

Cancels a policy as of a given date via a CANCEL transaction. The policy must be active at the cancellation date.

cancellationDate (= the transaction effective date) is sugar the server expands into per-segment, segment-scoped deltas on framework-required fields. policyStatus flips to cancelled from the cancellation date through end of term (splitting the segment at the boundary), and a single cancellationEffectiveOnDate is recorded uniformly across the whole term — the same value on both sides of the boundary. policyStatus alone marks which side a segment is on. There is no policyEarlyTerminationDate and no status-enum machinery.

Two optional derived channels are whole-object overwrites of a policy-root full-term container — necessarily whole-term, so neither carries dates nor an element-level form:

fullTermPolicyBillingInfo — full-term billing (e.g. short-rate penalties, cancellation fees). Its policyPremium must equal the earned premium through the cancellation date. When fullTermPolicyBillingInfo is omitted, the policy’s existing full-term billing carries forward and that carried-forward policyPremium is validated against earned premium — so a bare cancellationDate body only succeeds when the carried-forward premium already equals the earned premium through the cancellation date.
fullTermPolicyRatingResult — the canonical policy-level rating result.

Required permission: policy:update

POST

api

external

companies

{companyId}

policies

{policyId}

transaction

cancel

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"
}
'

{
  "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": {
    "policyStartDate": {
      "year": 2025,
      "month": 1,
      "day": 1,
      "timezone": "America/New_York"
    },
    "policyEndDate": {
      "year": 2025,
      "month": 12,
      "day": 31,
      "timezone": "America/New_York"
    },
    "primaryInsuredJoin": "550e8400-e29b-41d4-a716-446655440010"
  },
  "fullTermPolicyBillingInfo": {
    "policyPremium": 42500,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 45500
  },
  "fullTermPolicyRatingResult": null,
  "segments": [
    {
      "startDate": "2025-01-01",
      "endDate": "2025-06-14",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "active",
          "cancellationEffectiveOnDate": {
            "year": 2025,
            "month": 6,
            "day": 15,
            "timezone": null
          },
          "annualPremium": 85000,
          "fullTermPolicyInfo": {
            "policyStartDate": {
              "year": 2025,
              "month": 1,
              "day": 1,
              "timezone": "America/New_York"
            },
            "policyEndDate": {
              "year": 2025,
              "month": 12,
              "day": 31,
              "timezone": "America/New_York"
            },
            "primaryInsuredJoin": "550e8400-e29b-41d4-a716-446655440010"
          },
          "fullTermPolicyBillingInfo": {
            "policyPremium": 42500,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 45500
          }
        }
      }
    },
    {
      "startDate": "2025-06-15",
      "endDate": "2025-12-31",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "cancelled",
          "cancellationEffectiveOnDate": {
            "year": 2025,
            "month": 6,
            "day": 15,
            "timezone": null
          },
          "annualPremium": 85000,
          "fullTermPolicyInfo": {
            "policyStartDate": {
              "year": 2025,
              "month": 1,
              "day": 1,
              "timezone": "America/New_York"
            },
            "policyEndDate": {
              "year": 2025,
              "month": 12,
              "day": 31,
              "timezone": "America/New_York"
            },
            "primaryInsuredJoin": "550e8400-e29b-41d4-a716-446655440010"
          },
          "fullTermPolicyBillingInfo": {
            "policyPremium": 42500,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 45500
          }
        }
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

API key authentication. Send your raw API key as the Authorization header value with NO scheme prefix — Authorization: YOUR-API-KEY. Do NOT prefix it with Bearer or ApiKey , and do not use an X-API-Key header; those are not accepted.

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

fullTermPolicyBillingInfo

object

Optional whole-object overwrite of the policy-root full-term billing summary (e.g. short-rate penalties, cancellation fees). policyPremium must equal the earned premium through the cancellation date.

fullTermPolicyRatingResult

object

Optional whole-object overwrite of the policy-root canonical rating result.

Response

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

Endorsable full-term policy info, hoisted as a read-once convenience (also duplicated in every segment). Contains term dates, the renewal pointer (previousPolicyId), and the primary insured reference. Term bounds are sourced here. Segment-scoped policyStatus is not part of this object.

fullTermPolicyBillingInfo

object

Derived full-term billing aggregates, hoisted as a read-once convenience (also duplicated in every segment). Contains premium, taxes, fees, and grand total for the full policy term.

fullTermPolicyRatingResult

object

Derived canonical policy-level rating result for the full term, hoisted as a read-once convenience (also duplicated in every segment). Element-level rating output (crossSegmentRatingOutputs) stays inline at its host and is not hoisted.

Endorse Policy Transaction Reinstate Policy Transaction

⌘I