Usage Info

The Person entity stores comprehensive information about individuals, including personal details, contact information, identification, and addresses. This entity can be associated with businesses as owners or used independently within a Subject Record. Use this method during onboarding or when adding new stakeholders to an existing business relationship.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
subject_record_id	string	Yes	The Subject Record to add this Business to.
person	object	No	The person parameter defined in the tables below.

Person Parameters

Parameter	Type	Required	Description
email	string	No	The personal email address of the person. The email must be a validly formatted email address.
first_name	string	No	The legal first given name for the person.
middle_name	string	No	The legal middle name for the person.
last_name	string	No	The legal last name for the person.
date_of_birth	string	No	The legal date of birth for the person. This must be in the YYYY-MM-DD format and contain only digits [0-9] and dashes. The value cannot be in the future nor can the value be more than 130 years in the past.
tax_id	string	No	The tax ID for the person. In the US this is typically the SSN or ITIN. This field must be 9 characters long and only contain digits [0-9]. Dashes are not accepted.
citizenship	string	No	Two character code for the country of citizenship for the person. Must be one of the COUNTRIES .
phone_number	string	No	The primary personal phone number of the person. This field must be 10 characters long and must be in the pattern of NXXNXXXXXX, where N represents any digit from 2-9 and X represents any digit from 0-9. It must follow all other requirements of the North American Number Plan.
addresses	array	No	The list of addresses for the person. Only one address of each type can be added to the list. This parameter is not required. However, if an address parameter is provided, then type is required. At this time, only one a single entry of Person Address Type of `PRIMARY_RESIDENCE` is allowed. No other entries are supported.

Addresses Parameters

Parameter	Type	Required	Description
type	string	Yes	The type of address. Must be one of the PERSON_ADDRESS_TYPES.
line1	string	No	Primary street address information (building number, street name).
line2	string	No	Secondary address information (apartment, suite, unit, etc.)
city	string	No	City or municipality name
state	string	No	Two character code for the state. Must be one of the STATES.
postal_code	string	No	ZIP or postal code for mail delivery
country	string	No	Two character code for the country where the address is located. Must be one of the COUNTRIES.

Example

{
  "subject_record_id": "sr_57WfSCnafMnxDiWMKcy3EW",
  "person": {
    "email": "[email protected]",
    "first_name": "Sarah",
    "middle_name": "Elizabeth",
    "last_name": "Johnson",
    "date_of_birth": "1985-07-15",
    "tax_id": "123456789",
    "citizenship": "US",
    "phone_number": "5551234567",
    "addresses": [
      {
        "type": "PRIMARY_RESIDENCE",
        "line1": "123 Maple Avenue",
        "line2": "Apartment 4B",
        "city": "Portland",
        "state": "OR",
        "postal_code": "97204",
        "country": "US"
      }
    ]
  }
}

Response

Data

Parameter	Type	Description
person	object	The person parameter defined in the tables below.

Person Parameters

Parameter	Type	Description
person_id	string	The identifier for the Person just created.

Example

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_3XsPP17u8mU3k29x944ygx",
    "version": "2025-03-24"
  },
  "data": {
    "person": {
      "person_id": "p_4PYsekjAX8VMuAOfmW81C7"
    }
  }
}

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	Required parameters not provided. Enum value provided does not correspond to an available type.
ENTITY_NOT_FOUND	400	The `subject_record_id` provided does not exist.

System Rule Violations

When a SYSTEM_RULE_VIOLATION error occurs, the response will include additional entity_type and sub_code fields to provide more specific information:

Entity Type	Sub-code	Description
Subject Record	MAX_PERSON_LIMIT	The maximum number of persons has been reached for this Subject Record.