firmIdstring(uuid)required
ID of the firm
Retrieve a firm's unmasked FEIN
Returns the full, unmasked Federal Employer Identification Number for the specified firm. The FEIN is masked everywhere else in the API and returned in full only by this endpoint. Every access is recorded in a durable audit log. Cross-customer or unknown ids return 404 (never 403) so resource existence is not leaked across customer boundaries.
get
Path Parameters
Response
application/json
Response
application/json
Full unmasked FEIN retrieved successfully.
FeinDto
Carries a firm’s full, unmasked Federal Employer Identification Number. Returned only by GET /v2/firms/{firmId}/fein; the FEIN is masked in all other responses.
firmIdstring(uuid)required
The unique identifier of the firm.
Example:550e8400-e29b-41d4-a716-446655440000
feinstringrequired
The full, unmasked Federal Employer Identification Number (9 digits).
Example:123456789
get/v2/firms/{firmId}/fein
Authentication
Path Parameters
application/json
Persons
Operations for managing person identities
Create a person
Creates a new producer identity and associates them with the authenticated customer. The new person is immediately visible to the caller’s organization.
When sendInvite is omitted or false, the person is created without sending an email invitation. Set sendInvite: true to trigger the same invite email as the V1 ?sendInvite=true path.
Returns 400 when required fields are missing or field values fail validation.
post
Headers
Idempotency-Keystring(uuid)
Client-generated UUID used to deduplicate retried requests. When provided, the server caches the first successful response for this key and returns it for any subsequent request with the same key from the same client, without re-processing.
Body
application/json
Body
application/json
CreatePersonRequest
Fields for creating a new person. firstName, lastName, and primaryEmail are required. sendInvite defaults to false; set it to true to trigger an email invitation. Internal-only fields (customer ID, intake ID) are not accepted.
firstNamestringrequired
Example:Jane
lastNamestringrequired
Example:Smith
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(email)required
Example:jane.smith@example.com
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
sendInviteboolean
When true, sends an email invitation to the person. Defaults to false.
Default:false
Response
application/json
Response
application/json
Person created 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
post/v2/persons
Authentication
Headers
Body
{
"firstName": "Jane",
"lastName": "Smith",
"primaryEmail": "jane.smith@example.com"
}
application/json
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
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
Authentication
Query Parameters
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
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