personIdstring(uuid)required
ID of the person
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
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
Delete an address by ID
Deletes a single address by its ID, scoped to the authenticated customer.
Returns 404 if the address 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.
delete
Path Parameters
addressIdstring(uuid)required
ID of the address
Response
Response
Address deleted successfully.
delete/v2/addresses/{addressId}
Authentication
Path Parameters
Update an address by ID
Updates a single address by its ID, scoped to the authenticated customer.
Returns 404 if the address 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. Returns 400 when the request body fails validation (V2 error shape).
put
Path Parameters
addressIdstring(uuid)required
ID of the address
Body
application/json
Body
application/json
UpdateAddressRequest
typestringrequired
Type of address
Allowed values:MAILINGBUSINESSPHYSICAL
addressLine1stringrequired
First line of the street address.
Example:123 Main St
addressLine2string | null
Second line of the street address (suite, unit, etc.).
Example:Apt 4B
citystringrequired
City.
Example:Denver
statestringrequired
Two-letter US state code.
Example:CO
zipstringrequired
ZIP code in 5-digit or ZIP+4 format.
Match pattern:^\d{5}(-\d{4})?$
Example:80202
countystring | null
County name.
Example:Denver
countrystringrequired
Country code (ISO alpha-2).
Example:US
moveInDatestring | null(date)
Date the person moved to this address (YYYY-MM-DD).
Example:2020-01-15
preferredboolean | null
Whether this should be the preferred address. When true, any other preferred address for the same person or firm is automatically unset. Omitting or null is treated as false.
Default:false
Example:false
Response
application/json
Response
application/json
Address updated successfully.
AddressV2
idstring(uuid)requiredread-only
Address identifier.
Example:550e8400-e29b-41d4-a716-446655440000
typestringrequired
Type of address
Allowed values:MAILINGBUSINESSPHYSICAL
addressLine1stringrequired
First line of the street address.
Example:123 Main St
addressLine2string | null
Second line of the street address (suite, unit, etc.).
Example:Apt 4B
citystringrequired
City.
Example:Denver
statestringrequired
Two-letter US state code.
>= 2 characters<= 2 characters
Example:CO
zipstring | nullrequired
ZIP code in 5-digit or ZIP+4 format.
Match pattern:^\d{5}(-\d{4})?$
Example:80202
countystring | null
County name.
Example:Denver
countrystring | nullrequired
Country code (ISO alpha-2).
>= 2 characters<= 2 characters
Example:US
moveInDatestring | null(date)
Date the person moved to this address (YYYY-MM-DD).
Example:2020-01-15
preferredbooleanrequired
Whether this is the person’s preferred address.
Example:true
createdAtstring(date-time)requiredread-only
RFC3339 UTC timestamp when the address was created.
Example:2024-01-15T10:30:00Z
updatedAtstring | null(date-time)read-only
RFC3339 UTC timestamp when the address was last updated.
Example:2024-01-15T14:45:00Z
put/v2/addresses/{addressId}
Authentication
Path Parameters
Body
{
"type": "MAILING",
"addressLine1": "123 Main St",
"city": "Denver",
"state": "CO",
"zip": "80202",
"country": "US"
}
application/json
Get an address by ID
Returns a single address by its ID, scoped to the authenticated customer.
Returns 404 if the address 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
addressIdstring(uuid)required
ID of the address
Response
application/json
Response
application/json
Address retrieved successfully.
AddressV2
idstring(uuid)requiredread-only
Address identifier.
Example:550e8400-e29b-41d4-a716-446655440000
typestringrequired
Type of address
Allowed values:MAILINGBUSINESSPHYSICAL
addressLine1stringrequired
First line of the street address.
Example:123 Main St
addressLine2string | null
Second line of the street address (suite, unit, etc.).
Example:Apt 4B
citystringrequired
City.
Example:Denver
statestringrequired
Two-letter US state code.
>= 2 characters<= 2 characters
Example:CO
zipstring | nullrequired
ZIP code in 5-digit or ZIP+4 format.
Match pattern:^\d{5}(-\d{4})?$
Example:80202
countystring | null
County name.
Example:Denver
countrystring | nullrequired
Country code (ISO alpha-2).
>= 2 characters<= 2 characters
Example:US
moveInDatestring | null(date)
Date the person moved to this address (YYYY-MM-DD).
Example:2020-01-15
preferredbooleanrequired
Whether this is the person’s preferred address.
Example:true
createdAtstring(date-time)requiredread-only
RFC3339 UTC timestamp when the address was created.
Example:2024-01-15T10:30:00Z
updatedAtstring | null(date-time)read-only
RFC3339 UTC timestamp when the address was last updated.
Example:2024-01-15T14:45:00Z
get/v2/addresses/{addressId}
Authentication
Path Parameters
application/json