Search
K
Identity API

List persons

Returns persons paginated by opaque continuation token, ordered by (modifiedDate, id) ascending. Supply updated_since to fetch only records modified at or after a given timestamp, or firm_id to restrict results to persons associated with a specific firm.

Returns 404 if firm_id is supplied but is not owned by your organization. Returns 401 when the request carries no token and 403 when the token lacks the required scope.

get

Query Parameters

page_tokenstring

Opaque continuation token returned by the previous response’s page.nextToken. Omit on the first request. Format is server-controlled and may change without an API version bump.

page_sizeinteger(int32)

Requested number of items in the response. Defaults to 25 when omitted; values outside [1, 250] are rejected with 400 (not clamped). The actual size returned is reflected in page.size and may be smaller (last page or empty result).

Default:25

>= 1<= 250

updated_sincestring(date-time)

RFC3339 UTC timestamp (e.g. 2026-06-01T00:00:00Z). When supplied, filters to persons whose record was modified at or after this instant (inclusive).

Example:2026-06-01T00:00:00Z

firm_idstring(uuid)

UUID of a firm. When supplied, restricts the result to persons associated with that firm. Returns 404 if the firm is not visible to the authenticated customer (never 403, so firm existence is not leaked across customer boundaries).

Example:550e8400-e29b-41d4-a716-446655440000

Response

application/json

A page of persons.

itemsarray[object]required

A single person row returned by GET /v2/persons. Carries the person’s core identity fields. Related resources such as addresses, phones, employments, and licenses are not included here — retrieve them via the single-resource and dedicated collection endpoints.

Show Child Parameters
pageobjectrequired

Page metadata for a token-based list response.

Show Child Parameters
get/v2/persons
 
application/json

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

personIdstring(uuid)required

ID of the person

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}
 
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

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

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}

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

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
 
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

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

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

Body

{ "firmId": "550e8400-e29b-41d4-a716-446655440000" }
 
application/json