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
    }
  ],
  "fullTermPolicyBillingInfo": {
    "policyPremium": 102000,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 102500
  }
}
'

{
  "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": {
    "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": 102000,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 102500
  },
  "fullTermPolicyRatingResult": null,
  "segments": [
    {
      "startDate": "2025-01-01",
      "endDate": "2025-03-31",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "active",
          "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": 102000,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 102500
          }
        }
      }
    },
    {
      "startDate": "2025-04-01",
      "endDate": "2025-12-31",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "active",
          "annualPremium": 102000,
          "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": 102000,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 102500
          }
        }
      }
    }
  ]
}

Transactions

Endorse Policy Transaction

Applies an ENDORSE transaction to an existing policy. An endorsement carries one or more of five channels. The engine recomputes segments after applying every channel — adjacent segments with identical data are automatically merged — and the response includes the full resulting segment set.

Input channels (mutually exclusive — deltas XOR fullTermDeltas):

deltas — per-segment changes. Each carries its own startDate / endDate within the policy term, a path, an action (Add / Remove / Overwrite), and a value. The path must not contain any reserved full-term container.
fullTermDeltas — endorsements to policy.fullTermPolicyInfo only (term bounds, renewal pointer, primary insured). No dates are carried — the change applies across the whole term because full-term fields are invariant. When present, effectiveDate must equal the policy start date.

Sending both deltas and fullTermDeltas is a validation error — a per-segment endorsement and a policy-info endorsement are separate transactions.

Derived channels (additive on either input channel):

fullTermPolicyBillingInfo — whole-object overwrite of the policy-root billing summary.
fullTermPolicyRatingResult — whole-object overwrite of the policy-root canonical rating result (the twin of fullTermPolicyBillingInfo).
crossSegmentRatingOutputs — element-level rating output, [{ path, value }]. Each path terminates at a crossSegmentRatingOutputs container on a list element (or the policy); value is the whole rating-output object for that host. There is no action (always an Overwrite) and no dates — the server derives each write’s range from the host’s presence across segments, so it applies cleanly to part-term hosts.

At least one channel is required.

Path syntax — predicate addressing. Index into a list by a predicate on any field: policy.exposures[id = '<uuid>'].bedCount, policy.coverages[coverageType = 'GL'].limits[name = 'occurrence']. The predicate must resolve to exactly one element wherever it is applied (throws on zero or multiple matches) — this uniqueness rule is the cross-segment identity guarantee.

Required permission: policy:update

POST

api

external

companies

{companyId}

policies

{policyId}

transaction

endorse

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
    }
  ],
  "fullTermPolicyBillingInfo": {
    "policyPremium": 102000,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 102500
  }
}
'

{
  "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": {
    "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": 102000,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 102500
  },
  "fullTermPolicyRatingResult": null,
  "segments": [
    {
      "startDate": "2025-01-01",
      "endDate": "2025-03-31",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "active",
          "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": 102000,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 102500
          }
        }
      }
    },
    {
      "startDate": "2025-04-01",
      "endDate": "2025-12-31",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "active",
          "annualPremium": 102000,
          "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": 102000,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 102500
          }
        }
      }
    }
  ]
}

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

effectiveDate

string<date>

required

The effective date of the endorsement in ISO 8601 format. When fullTermDeltas is present this must equal the policy start 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).

deltas

object[]

Per-segment deltas. Each delta specifies a date range (startDate / endDate) within the policy term, a predicate path, an action (Add / Remove / Overwrite), and the new value. Paths must not contain any reserved full-term container (fullTermPolicyInfo, fullTermPolicyBillingInfo, fullTermPolicyRatingResult, crossSegmentRatingOutputs). Mutually exclusive with fullTermDeltas.

Show child attributes

fullTermDeltas

object[]

Endorsements to policy.fullTermPolicyInfo (term bounds, renewal pointer, primary insured). Each delta targets a path under policy.fullTermPolicyInfo and applies across the entire policy term — no startDate / endDate is accepted. Mutually exclusive with deltas. When present, effectiveDate must equal the policy start date. (Extending or shortening the term is a fullTermDeltas write to policy.fullTermPolicyInfo.policyEndDate.)

Show child attributes

fullTermPolicyBillingInfo

object

Optional whole-object overwrite of the policy-root full-term billing summary. Additive on either input channel.

fullTermPolicyRatingResult

object

Optional whole-object overwrite of the policy-root canonical rating result. The twin of fullTermPolicyBillingInfo; additive on either input channel.

crossSegmentRatingOutputs

object[]

Optional element-level rating output. Each entry overwrites the crossSegmentRatingOutputs container at its host; the server derives the write range from the host's presence across segments (write where the host-selector resolves to exactly one element, skip where zero, throw on many or if it never resolves). Additive; ENDORSE only.

Show child attributes

Response

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

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.

New Business Transaction Cancel Policy Transaction

⌘I