Search
K
Identity API

Get a firm by ID

Returns a single firm visible to the authenticated customer. The FEIN is always masked to **** and never returned in full here; use GET /v2/firms/{firmId}/fein (audited) for the full value.

Returns 404 if the firm does not exist or is not visible to the authenticated customer. A 403 is returned only when the caller’s token lacks the required scope; cross-customer access returns 404, not 403.

get

Path Parameters

firmIdstring(uuid)required

ID of the firm

Response

application/json

Firm retrieved successfully.

FirmV2

Customer-facing firm resource. The FEIN is always masked to ****; the full FEIN is available only via GET /v2/firms/{firmId}/fein (audited).

idstring(uuid)requiredread-only

The unique identifier of the firm.

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

npnstringrequiredread-only

National Producer Number.

Example:1234567

namestring

Legal name of the firm.

Example:Acme Insurance LLC

emailstring(email)

Primary contact email address.

Example:contact@acme.com

typestring

Business entity type (SC, LLC, SP).

Example:LLC

finraCrdNumberstring

FINRA CRD number (digits only, max 11 characters).

Example:12345

feinstringread-only

Masked Federal Employer Identification Number. Always returned as ****. The full FEIN is never exposed by this endpoint.

Example:****6789

testAccountboolean

Whether this is a test account.

Example:false

createdAtstring(date-time)requiredread-only

ISO-8601 UTC timestamp when the firm was created.

Example:2024-01-15T10:30:00Z

updatedAtstring(date-time)read-only

ISO-8601 UTC timestamp of the last update.

Example:2024-06-01T14:22:00Z

get/v2/firms/{firmId}
 
application/json

Update a firm by ID

Updates mutable fields on a firm visible to the authenticated customer. The fields npn and fein are immutable and cannot be changed via this endpoint. Omitted fields leave the stored value unchanged (partial update).

Returns 404 if the firm does not exist or is not visible to the authenticated customer. A 403 is returned only when the caller’s token lacks the required scope; cross-customer access returns 404, not 403.

put

Path Parameters

firmIdstring(uuid)required

ID of the firm

Body

application/json

UpdateFirmRequest

Fields that may be updated on a firm. All fields are optional — omitted fields leave the stored value unchanged. The npn and fein fields are immutable and cannot be set via this endpoint.

namestring

Legal name of the firm.

Example:Acme Insurance LLC

emailstring(email)

Primary contact email address.

Example:contact@acme.com

typestring

Business entity type (SC, LLC, SP).

Example:LLC

finraCrdNumberstring

FINRA CRD number (digits only, max 11 characters).

Match pattern:^[0-9]*$

<= 11 characters

Example:12345

Response

application/json

Firm updated successfully.

FirmV2

Customer-facing firm resource. The FEIN is always masked to ****; the full FEIN is available only via GET /v2/firms/{firmId}/fein (audited).

idstring(uuid)requiredread-only

The unique identifier of the firm.

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

npnstringrequiredread-only

National Producer Number.

Example:1234567

namestring

Legal name of the firm.

Example:Acme Insurance LLC

emailstring(email)

Primary contact email address.

Example:contact@acme.com

typestring

Business entity type (SC, LLC, SP).

Example:LLC

finraCrdNumberstring

FINRA CRD number (digits only, max 11 characters).

Example:12345

feinstringread-only

Masked Federal Employer Identification Number. Always returned as ****. The full FEIN is never exposed by this endpoint.

Example:****6789

testAccountboolean

Whether this is a test account.

Example:false

createdAtstring(date-time)requiredread-only

ISO-8601 UTC timestamp when the firm was created.

Example:2024-01-15T10:30:00Z

updatedAtstring(date-time)read-only

ISO-8601 UTC timestamp of the last update.

Example:2024-06-01T14:22:00Z

put/v2/firms/{firmId}

Body

{}
 
application/json

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

firmIdstring(uuid)required

ID of the firm

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

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

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

Body

{ "firstName": "Jane", "lastName": "Smith", "primaryEmail": "jane.smith@example.com" }
 
application/json