Endorse Policy Transaction

Applies an ENDORSE transaction to an existing policy. Endorsements modify policy state over specified date ranges using per-field deltas. Each delta targets a specific path within the policy data (e.g. policy.annualPremium, policy.exposures) and can Add, Remove, or Overwrite values.

Deltas come in two flavors:

• deltas — segmented deltas for per-segment fields. Each delta specifies a startDate / endDate within the policy term.
• fullTermDeltas — deltas for cross-segment invariant fields (fullTermPolicyBilling, fullTermPolicyInfo, fullTermPolicyRatingResponse, fullTermExposureRatingResponse). These are applied uniformly across the entire policy term, so no dates are accepted — the server injects policyStartDate → policyEndDate automatically.

Mixing the two is a validation error: fullTerm* paths in deltas are rejected, and non-fullTerm* paths in fullTermDeltas are rejected. At least one of the two arrays must be non-empty.

The engine recomputes segments after applying all deltas — adjacent segments with identical data are automatically merged. The response includes the full set of resulting segments.

Required permission: company.policy:update

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

cURL

midTermPremiumChange

curl --request POST \
  --url https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/transaction/endorse \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "effectiveDate": "2025-04-01",
  "deltas": [
    {
      "startDate": "2025-04-01",
      "endDate": "2025-12-31",
      "path": "policy.annualPremium",
      "action": "Overwrite",
      "value": 102000
    }
  ],
  "fullTermDeltas": [
    {
      "path": "policy.fullTermPolicyBilling",
      "action": "Overwrite",
      "value": {
        "policyPremium": 102000,
        "policyTaxes": 0,
        "policyFees": 500,
        "policyGrandTotal": 102500
      }
    }
  ]
}
'

201

success

{
  "policyId": "550e8400-e29b-41d4-a716-446655440001",
  "policyVersion": 2,
  "transactionId": "550e8400-e29b-41d4-a716-446655440030",
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "createdAt": "2025-04-01T10: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"
  },
  "fullTermPolicyBilling": {
    "policyPremium": 102000,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 102500
  },
  "segments": [
    {
      "startDate": "2025-01-01",
      "endDate": "2025-03-31",
      "fieldModelV1Data": {
        "policy": {
          "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"
          },
          "fullTermPolicyBilling": {
            "policyPremium": 102000,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 102500
          }
        }
      }
    },
    {
      "startDate": "2025-04-01",
      "endDate": "2025-12-31",
      "fieldModelV1Data": {
        "policy": {
          "annualPremium": 102000,
          "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"
          },
          "fullTermPolicyBilling": {
            "policyPremium": 102000,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 102500
          }
        }
      }
    }
  ]
}

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

effectiveDate · string<date> · required

The effective date of the endorsement in ISO 8601 format.

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

deltas · object[]

Per-segment deltas. Each delta specifies a date range (startDate / endDate) within the policy term, a path within the policy data, an action (Add, Remove, or Overwrite), and the new value. Paths targeting fullTerm* fields must be sent via fullTermDeltas instead.

Show child attributes

fullTermDeltas · object[]

Cross-segment invariant deltas. Each delta targets a fullTerm* path (policy.fullTermPolicyBilling, policy.fullTermPolicyInfo, policy.fullTermPolicyRatingResponse, policy.fullTermExposureRatingResponse). The server applies each delta across the entire policy term — no startDate / endDate is accepted. Paths not matching a fullTerm* prefix are rejected.

Show child attributes

Response

201

application/json

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