Search
K
Identity API

Firms

Operations for managing firm identities

List firms (customer-scoped, keyset-paginated)

Returns a keyset-paginated list of firms visible to the authenticated customer, sorted by (modifiedDate ASC, id ASC). Optionally filters to records modified on or after updated_since (RFC3339 instant, inclusive).

The FEIN is always masked to ****. Empty results return items: [], page.size: 0, nextToken: null.

Returns 403 when the caller’s 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 timestamp. When supplied, only firms modified at or after this instant are returned.

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

Response

application/json

Firm list retrieved successfully.

FirmV2List

Keyset-paginated list of firms (F5 envelope).

itemsarray[object]required

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

Show Child Parameters
pageobjectrequired

Page metadata for a token-based list response.

Show Child Parameters
get/v2/firms
 
application/json

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