Fat Agent Standard / Core Objects
v1.0Person
Represents a human individual within Fat Agent Standard.
A Person exists once. Roles such as insured, owner, beneficiary, driver, payer, annuitant, claimant, or authorized signer are relationships to other objects and MUST NOT create duplicate Person records.
Identity
| Field | Type | Required | Description |
|---|---|---|---|
person_id | string | Yes | Unique identifier for the Person |
first_name | string | Yes | Legal first name |
middle_name | string | No | Legal middle name |
last_name | string | Yes | Legal last name |
suffix | string | No | Name suffix such as Jr., Sr., II, III |
preferred_name | string | No | Preferred or commonly used first name |
date_of_birth | string (date) | No | Date of birth in YYYY-MM-DD format |
gender | enum | No | Gender value Allowed: male, female, unknown |
ssn | string | No | U.S. Social Security Number |
Contact — Phones
phones is an optional array.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum | Yes | Type of phone number Allowed: mobile, home, work, other |
type_description | string | Yes* | Custom value when type is other. Required when type is other. MUST NOT be set otherwise. |
number | string | Yes | Phone number |
extension | string | No | Phone extension |
Contact — Emails
emails is an optional array.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum | Yes | Type of email address Allowed: personal, work, other |
type_description | string | Yes* | Custom value when type is other. Required when type is other. MUST NOT be set otherwise. |
address | string (email) | Yes | Email address |
Addresses
addresses is an optional array of references. Each item contains address_id, type, and type_description when type is other. The Address schema is defined on the Address object and MUST NOT be duplicated here.
| Field | Type | Required | Description |
|---|---|---|---|
| address_id | string | Yes | ID of the related Address object |
type | enum | Yes | Person's relationship to the address Allowed: residence, mailing, previous, other |
type_description | string | Yes* | Custom value when type is other. Required when type is other. MUST NOT be set otherwise. |
Personal
| Field | Type | Required | Description |
|---|---|---|---|
marital_status | enum | No | Current marital status Allowed: single, married, divorced, widowed, separated, domestic_partner, unknown |
citizenship | string | No | Country of citizenship |
country_of_birth | string | No | Country of birth |
occupation | string | No | Person's occupation |
occupation_description | string | No | Additional description of occupation or duties |
annual_income | number | No | Annual income attributable to this Person |
household_income | number | No | Total annual household income as reported |
Driver's License
drivers_license is an optional object. number is required only when the drivers_license object is supplied.
| Field | Type | Required | Description |
|---|---|---|---|
number | string | Yes* | Driver's license number |
state | string | No | Issuing state/province |
country | string | No | Issuing country |
issue_date | string (date) | No | Issue date |
expiration_date | string (date) | No | Expiration date |
status | enum | No | Current license status Allowed: valid, expired, suspended, revoked, restricted, unknown |
Relationships
relationships is an optional array connecting this Person to another Person.
| Field | Type | Required | Description |
|---|---|---|---|
| related_person_id | string | Yes | ID of the related Person |
relationship_type | enum | Yes | Relationship between the people Allowed: spouse, domestic_partner, child, parent, sibling, guardian, other |
relationship_type_description | string | Yes* | Custom value when relationship_type is other. Required when relationship_type is other. MUST NOT be set otherwise. |
Validation Rules
- person_id MUST be a non-empty string.
- first_name MUST be a non-empty string.
- last_name MUST be a non-empty string.
- date_of_birth, issue_date, and expiration_date MUST use YYYY-MM-DD.
- Email addresses MUST be valid email-formatted strings.
- Enum fields MUST contain one of their defined values.
- 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.
- annual_income and household_income MUST be numbers greater than or equal to zero.
- Every address_id MUST reference an Address object.
- Address fields such as line1, city, state, and postal_code MUST NOT appear on Person or inside addresses[]. Those belong on Address.
- Every related_person_id MUST reference another Person object.
- A Person MUST NOT be duplicated merely because that Person has multiple insurance roles.
- Insurance-specific underwriting data such as tobacco use, height, weight, medical history, medications, health questions, and driving history MUST NOT be stored in Person. Those belong in Underwriting.