Fat Agent Standard / Core Objects
v1.0Endorsement
Represents a change, amendment, or transaction applied to an existing insurance Policy.
Endorsement MUST reference other Fat Agent Standard objects rather than duplicate their underlying data. It records the contractual change, not the current Policy.
Identity
One Endorsement belongs to exactly one Policy. Endorsement status describes this transaction, not the Policy status. cancelled means the endorsement was withdrawn, not that the Policy was cancelled.
| Field | Type | Required | Description |
|---|---|---|---|
endorsement_id | string | Yes | Unique identifier for the Endorsement |
| policy_id | string | Yes | Policy being changed |
endorsement_number | string | No | Carrier-assigned endorsement or transaction number |
status | enum | Yes | Current workflow status of the Endorsement Allowed: requested, pending, approved, declined, issued, cancelled, other |
status_description | string | Yes* | Custom value when status is other. Required when status is other. MUST NOT be set otherwise. |
Dates
request_date, effective_date, and issue_date represent different events and MUST NOT be assumed to be identical.
| Field | Type | Required | Description |
|---|---|---|---|
request_date | string (date) | No | Date the policy change was requested |
effective_date | string (date) | No | Date the change takes effect |
issue_date | string (date) | No | Date the carrier formally issued the Endorsement |
Changes
changes is a required array of one or more individual changes. One Endorsement MAY add, remove, modify, cancel, or reinstate multiple policy elements. previous_value and new_value MAY be any JSON value. Reference Standard objects by target_id instead of embedding them.
| Field | Type | Required | Description |
|---|---|---|---|
change_id | string | Yes | Unique identifier for the individual change |
change_type | enum | Yes | Action being performed Allowed: add, remove, modify, cancel, reinstate, other |
change_type_description | string | Yes* | Custom value when change_type is other. Required when change_type is other. MUST NOT be set otherwise. |
target_type | enum | Yes | Type of policy data being changed Allowed: coverage, person, organization, vehicle, property, producer, policy_term, billing, other |
target_type_description | string | Yes* | Custom value when target_type is other. Required when target_type is other. MUST NOT be set otherwise. |
target_id | string | No | ID of the specific Standard object being changed |
field | string | No | Specific field being changed when applicable |
previous_value | any | No | Value before the change |
new_value | any | No | Value after the change |
description | string | No | Human-readable explanation of the change |
Premium Impact
premium_change is signed: positive increase, negative decrease, zero no change. new_policy_premium is the carrier-reported resulting Policy premium. Do not assume old premium plus premium_change equals new_policy_premium. currency is required when either premium field is supplied.
| Field | Type | Required | Description |
|---|---|---|---|
premium_change | number | No | Increase or decrease caused by the Endorsement |
new_policy_premium | number | No | Resulting Policy premium after the Endorsement |
currency | string | No | ISO 4217 currency code. Required when premium_change or new_policy_premium is supplied. |
Documents
document_ids references Document/Evidence objects associated with the Endorsement. Document metadata belongs on Document/Evidence.
| Field | Type | Required | Description |
|---|---|---|---|
document_ids | array[string] | No | Documents associated with the Endorsement |
External References
external_references maps the Endorsement to identifiers from carriers or other systems, such as carrier transaction IDs, AMS transaction IDs, or policy administration IDs.
| Field | Type | Required | Description |
|---|---|---|---|
system | string | Yes | External system |
reference_id | string | Yes | Identifier assigned by that system |
reference_type | string | No | Type of reference |
Target Types
target_type identifies the Fat Agent Standard object or Policy-level information being changed. Endorsement MUST reference those objects rather than duplicate them. Health insurance and group insurance are outside Fat Agent Standard v1.0.
| Line of Business | Allowed product_type |
|---|---|
coverage | Coverage |
person | Person |
organization | Organization |
vehicle | Vehicle |
property | Property |
producer | Producer / Agency |
policy_term | Policy-level contractual information |
billing | Policy billing information |
other | Requires target_type_description |
Validation Rules
- endorsement_id, policy_id, status, and changes MUST be supplied.
- changes MUST contain at least one Change. Each Change MUST have a unique change_id, change_type, and target_type.
- One Endorsement belongs to exactly one Policy. One Policy MAY have unlimited Endorsements.
- Endorsements represent discrete policy transactions and MUST remain historically distinct.
- When an enum value is other, the companion {field}_description field is required and MUST be a non-empty string. That companion field MUST NOT be set unless the enum value is other.
- Endorsement MUST reference Coverage, Person, Organization, Vehicle, Property, and Producer objects rather than duplicating those schemas.
- target_id SHOULD identify the affected Standard object when one exists. It MAY be omitted for policy_term, billing, or other policy-level targets.
- previous_value and new_value MAY be any JSON value.
- premium_change MAY be positive, negative, or zero.
- new_policy_premium, when supplied, MUST be greater than or equal to zero.
- currency MUST use ISO 4217 and is required when premium_change or new_policy_premium is supplied.
- Do not calculate new_policy_premium from premium_change. Preserve the carrier-reported resulting premium.
- Endorsement status describes the endorsement transaction, not the Policy status.
- Dates MUST use ISO 8601 date format (YYYY-MM-DD).
- Health insurance and group insurance MUST NOT appear on Endorsement.