personIdstring(uuid)required
ID of the person
Get a person by ID
Returns the customer-facing identity for the specified person. The person must be owned by the authenticated customer. SSN is masked — only the last four digits are present via ssnLast4. The full unmasked SSN is available only via GET /v2/persons/{personId}/ssn.
Returns 404 if the person does not exist or is not visible to the authenticated customer.
get
Path Parameters
Response
application/json
Response
application/json
Person retrieved successfully.
PersonV2
Customer-facing producer identity. SSN is masked — only the last four digits are present via ssnLast4. The full unmasked SSN is available only via GET /v2/persons/{personId}/ssn.
idstring(uuid)requiredread-only
The unique identifier of the person.
Example:550e8400-e29b-41d4-a716-446655440000
titlestring | null
The person’s honorific title.
Allowed values:DRMRMRSMSMISS
Example:MS
firstNamestring
The person’s first name.
Example:Jane
preferredFirstNamestring | null
The name the person prefers to be addressed by, when different from their legal first name.
Example:Janey
middleNamestring | null
The person’s middle name.
Example:Quincy
lastNamestring
The person’s last name.
Example:Smith
suffixstring | null
The person’s name suffix.
Allowed values:JRSRIIIIIIOBEMBEBSCJPGM
Example:JR
primaryEmailstring | null(email)
The person’s primary contact email address.
Example:jane.smith@example.com
secondaryEmailstring | null(email)
The person’s secondary contact email address.
Example:jane.alt@example.com
dateOfBirthstring | null(date)
The person’s date of birth (YYYY-MM-DD).
Example:1990-05-15
genderstring | null
The person’s gender.
Allowed values:MALEFEMALE
Example:FEMALE
citizenshipCountrystring | null
The person’s country of citizenship.
Example:US
residentStatestring | null
The person’s state of residence.
Example:CO
unitedStatesCitizenboolean | null
Whether the person is a United States citizen.
Example:true
unitedStatesWorkAuthorizedboolean | null
Whether the person is authorized to work in the United States.
Example:true
marriedboolean | null
Whether the person is married.
Example:false
npnstring | null
National Producer Number.
Example:12345678
npnVerifiedbooleanrequiredread-only
Whether the person’s NPN has been verified against NIPR.
finraCrdNumberstring | null
The person’s FINRA Central Registration Depository (CRD) number.
Example:1234567
ssnLast4string | null
Last four digits of the Social Security Number. Full SSN available only via GET /v2/persons/{personId}/ssn.
Example:6789
createdAtstring(date-time)requiredread-only
RFC3339 timestamp when the person record was created.
Example:2026-01-15T10:30:00Z
updatedAtstring(date-time)requiredread-only
RFC3339 timestamp of the most recent modification.
Example:2026-06-01T14:22:00Z
get/v2/persons/{personId}
Authentication
Path Parameters
application/json
Update a person
Partially updates the specified person’s identity fields. Only the fields present in the request body are applied — omitted fields retain their existing values. The person must be owned by the authenticated customer.
Returns 404 if the person does not exist or is not visible to the authenticated customer (cross-customer access returns 404, not 403).
put
Path Parameters
personIdstring(uuid)required
ID of the person
Body
application/json
Body
application/json
UpdatePersonRequest
Fields to apply to a person. Only non-null fields are applied — omitted or null fields leave the stored value untouched (partial update). firstName and lastName are required.
firstNamestringrequired
Example:Grace
lastNamestringrequired
Example:Hopper
middleNamestring | null
preferredFirstNamestring | null
<= 100 characters
titlestring | null
The person’s honorific title.
Allowed values:DRMRMRSMSMISS
Example:MS
suffixstring | null
The person’s name suffix.
Allowed values:JRSRIIIIIIOBEMBEBSCJPGM
Example:JR
dateOfBirthstring | null(date)
genderstring | null
The person’s gender.
Allowed values:MALEFEMALE
Example:FEMALE
primaryEmailstring | null(email)
secondaryEmailstring | null(email)
citizenshipCountrystring | null
residentStatestring | null
unitedStatesCitizenboolean | null
unitedStatesWorkAuthorizedboolean | null
marriedboolean | null
npnstring | null
National Producer Number. Must start with a non-zero digit and contain only digits.
Match pattern:^[1-9][0-9]*$
<= 12 characters
finraCrdNumberstring | null
FINRA CRD number. Must contain only digits.
Match pattern:^[0-9]+$
<= 11 characters
ssnstring | null
Social Security Number. Must be exactly 9 digits.
Match pattern:^[0-9]*$
>= 9 characters<= 9 characters
Response
application/json
Response
application/json
Person updated successfully.
PersonV2
Customer-facing producer identity. SSN is masked — only the last four digits are present via ssnLast4. The full unmasked SSN is available only via GET /v2/persons/{personId}/ssn.
idstring(uuid)requiredread-only
The unique identifier of the person.
Example:550e8400-e29b-41d4-a716-446655440000
titlestring | null
The person’s honorific title.
Allowed values:DRMRMRSMSMISS
Example:MS
firstNamestring
The person’s first name.
Example:Jane
preferredFirstNamestring | null
The name the person prefers to be addressed by, when different from their legal first name.
Example:Janey
middleNamestring | null
The person’s middle name.
Example:Quincy
lastNamestring
The person’s last name.
Example:Smith
suffixstring | null
The person’s name suffix.
Allowed values:JRSRIIIIIIOBEMBEBSCJPGM
Example:JR
primaryEmailstring | null(email)
The person’s primary contact email address.
Example:jane.smith@example.com
secondaryEmailstring | null(email)
The person’s secondary contact email address.
Example:jane.alt@example.com
dateOfBirthstring | null(date)
The person’s date of birth (YYYY-MM-DD).
Example:1990-05-15
genderstring | null
The person’s gender.
Allowed values:MALEFEMALE
Example:FEMALE
citizenshipCountrystring | null
The person’s country of citizenship.
Example:US
residentStatestring | null
The person’s state of residence.
Example:CO
unitedStatesCitizenboolean | null
Whether the person is a United States citizen.
Example:true
unitedStatesWorkAuthorizedboolean | null
Whether the person is authorized to work in the United States.
Example:true
marriedboolean | null
Whether the person is married.
Example:false
npnstring | null
National Producer Number.
Example:12345678
npnVerifiedbooleanrequiredread-only
Whether the person’s NPN has been verified against NIPR.
finraCrdNumberstring | null
The person’s FINRA Central Registration Depository (CRD) number.
Example:1234567
ssnLast4string | null
Last four digits of the Social Security Number. Full SSN available only via GET /v2/persons/{personId}/ssn.
Example:6789
createdAtstring(date-time)requiredread-only
RFC3339 timestamp when the person record was created.
Example:2026-01-15T10:30:00Z
updatedAtstring(date-time)requiredread-only
RFC3339 timestamp of the most recent modification.
Example:2026-06-01T14:22:00Z
put/v2/persons/{personId}
Authentication
Path Parameters
Body
{
"firstName": "Grace",
"lastName": "Hopper"
}
application/json
Retrieve a person's unmasked SSN
Returns the full, unmasked Social Security Number for the specified person. The SSN is masked everywhere else in the API and returned in full only by this endpoint. Every access is recorded in a durable audit log.
Returns 404 if the person does not exist, is not visible to the authenticated customer, or has no SSN on record. A 403 is returned only when the caller’s token lacks the required scope; cross-customer access returns 404, not 403.
get
Path Parameters
personIdstring(uuid)required
ID of the person
Response
application/json
Response
application/json
SSN retrieved successfully.
SsnResponse
Carries a person’s full, unmasked Social Security Number. Returned only by GET /v2/persons/{personId}/ssn; the SSN is masked in all other responses.
personIdstring(uuid)requiredread-only
The unique identifier of the person.
Example:550e8400-e29b-41d4-a716-446655440000
ssnstringrequiredread-only
The full, unmasked Social Security Number (9 digits).
Example:123456789
get/v2/persons/{personId}/ssn
Authentication
Path Parameters
application/json
Associate a person with a firm
Associates an existing person with an existing firm. This is a distinct operation from creating either resource — it only links a person to a firm the caller already owns. Both the person and the firm must be visible to the authenticated customer; if either is unknown or belongs to another customer the response is 404 (never 403), so resource existence is not leaked across customer boundaries.
When role is omitted, it defaults to PRINCIPAL. Re-associating the same person and firm is idempotent and returns 201 with the current association.
post
Path Parameters
personIdstring(uuid)required
ID of the person
Body
application/json
Body
application/json
AssociateFirmRequestV2
Identifies the existing firm to associate with the person, and optionally the person’s role in it.
firmIdstring(uuid)required
The unique identifier of the firm to associate.
Example:550e8400-e29b-41d4-a716-446655440000
rolestring
The person’s role in the firm. Defaults to PRINCIPAL when omitted.
Allowed values:PRINCIPALAGENT_FIRM_MANAGERAGENT
Default:PRINCIPAL
Example:PRINCIPAL
Response
application/json
Response
application/json
Association created.
PersonFirmV2
An association between a person and a firm.
personIdstring(uuid)requiredread-only
The unique identifier of the associated person.
Example:550e8400-e29b-41d4-a716-446655440000
firmIdstring(uuid)requiredread-only
The unique identifier of the associated firm.
Example:660e8400-e29b-41d4-a716-446655440111
rolestringrequired
The person’s role in the firm.
Allowed values:PRINCIPALAGENT_FIRM_MANAGERAGENT
Example:PRINCIPAL
post/v2/persons/{personId}/firms
Authentication
Path Parameters
Body
{
"firmId": "550e8400-e29b-41d4-a716-446655440000"
}
application/json
Addresses
Operations for managing addresses