Sign in

v1

latestOpenAPI 3.0.12026-07-268028223.9 KB
People

Create a person

Create a new person in a household

post/v1/households/{household_id}/people

Headers

Idempotency-Keystring

Unique key to ensure idempotent request handling. If a request with the same key was already processed, the original response will be returned.

Request body

first_namestring required

First name

last_namestring required

Last name

middle_namestring

Middle name

preferred_namestring

Preferred name

salutationstring

Salutation

suffixstring

Suffix

gender'female' | 'male' | 'nonbinary' | 'other' | 'prefer_not_to_say'

Gender

designationsstring

Professional designations

household_role'head_of_household' | 'partner' | 'spouse' | 'dependent_child' | 'other_adult' | 'non_dependent_child' | 'other_dependent' | 'unknown' | 'deceased' | 'grandchild'

Role in the household

date_of_birthstring date

Date of birth

job_titlestring

Job title

ssnstring

Social security number

drivers_license_numberstring

Driver's license number

custom_fieldsobject

Custom field values as key-value pairs

Example request

{
  "first_name": "John",
  "last_name": "Doe",
  "middle_name": "Robert",
  "preferred_name": "Johnny",
  "salutation": "Mr.",
  "suffix": "Jr.",
  "gender": "male",
  "designations": "CPA, CFP",
  "household_role": "spouse",
  "date_of_birth": "1985-06-15",
  "job_title": "Software Engineer",
  "email_addresses": [
    {
      "email": "john@example.com",
      "email_type": "personal",
      "is_primary": true
    }
  ],
  "phone_numbers": [
    {
      "phone_number": "+15555551234",
      "phone_type": "mobile",
      "is_primary": true
    }
  ],
  "addresses": [
    {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country_code": "US",
      "address_type": "home",
      "is_primary": true
    }
  ],
  "employments": [
    {
      "business_name": "Acme Corp",
      "role": "Software Engineer",
      "start_date": "2023-01-15",
      "end_date": "2024-12-31",
      "actively_employed": true
    }
  ],
  "ssn": "123-45-6789",
  "drivers_license_number": "DL-1234567890",
  "custom_fields": {
    "preferred_contact_method": "Email"
  }
}

Response

person created

idstring required

The person ID

book_idstring required

The book ID

household_idstring nullable

The household ID

contact_idstring nullable

The contact ID (present when person belongs to a contact)

role_type'client' | 'prospect' | 'contact' | 'past_client' nullable

The entity type this person belongs to

first_namestring required
middle_namestring nullable
last_namestring required
salutationstring nullable
suffixstring nullable
maiden_namestring nullable
gender'female' | 'male' | 'nonbinary' | 'other' | 'prefer_not_to_say' nullable
designationsstring nullable
household_role'head_of_household' | 'partner' | 'spouse' | 'dependent_child' | 'other_adult' | 'other_dependent' | 'unknown' | 'deceased' | 'non_dependent_child' | 'grandchild' nullable

Only present when person belongs to a household

preferred_namestring nullable
date_of_birthstring date nullable

Date of birth

job_titlestring nullable

Job title

ssnstring nullable

Obfuscated social security number

drivers_license_numberstring nullable

Obfuscated driver's license number

custom_fieldsobject

Custom field values as key-value pairs

Example response

{
  "id": "abc123xyz",
  "book_id": "book123xyz",
  "household_id": "xyz789abc",
  "contact_id": "cnt456def",
  "role_type": "client",
  "first_name": "John",
  "middle_name": "Robert",
  "last_name": "Doe",
  "salutation": "Mr.",
  "suffix": "Jr.",
  "maiden_name": "Smith",
  "gender": "male",
  "designations": "CPA, CFP",
  "household_role": "head_of_household",
  "preferred_name": "Johnny",
  "date_of_birth": "1985-06-15",
  "job_title": "Software Engineer",
  "ssn": "***-**-6789",
  "drivers_license_number": "******7890",
  "email_addresses": [
    {
      "email": "john.doe@example.com",
      "email_type": "personal",
      "is_primary": true
    }
  ],
  "phone_numbers": [
    {
      "phone_number": "+15555551234",
      "extension": "1234",
      "phone_type": "mobile",
      "is_primary": true
    }
  ],
  "addresses": [
    {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country_code": "US",
      "address_type": "home",
      "is_primary": true
    }
  ],
  "employments": [
    {
      "id": "emp123xyz",
      "person_id": "abc123xyz",
      "business_name": "Acme Corp",
      "role": "Software Engineer",
      "start_date": "2023-01-15",
      "end_date": "2024-12-31",
      "actively_employed": true
    }
  ],
  "custom_fields": {
    "preferred_contact_method": "Email",
    "risk_tolerance": "Moderate"
  }
}