addressIdstring(uuid)required
ID of the address
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
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
Create an address for a person
Creates a new address and associates it with the specified person under the authenticated customer’s scope.
Returns 404 if the person 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).
post
Path Parameters
personIdstring(uuid)required
ID of the person
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
CreateAddressRequest
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
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).
>= 2 characters<= 2 characters
Example:US
moveInDatestring | null(date)
Date the person moved to this address (YYYY-MM-DD).
Example:2020-01-15
preferredboolean
Whether this should be the person’s preferred address. When the person has no existing addresses, the server sets this to true regardless of the supplied value.
Default:false
Example:false
Response
application/json
Response
application/json
Address created 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
post/v2/persons/{personId}/addresses
Authentication
Path Parameters
Headers
Body
{
"type": "MAILING",
"addressLine1": "123 Main St",
"city": "Denver",
"state": "CO",
"zip": "80202",
"country": "US"
}
application/json
List addresses for a person
Returns addresses belonging to the specified person and visible to the authenticated customer, paginated by opaque continuation token. Results are ordered by (modifiedDate ASC, id ASC).
Returns 404 if the person 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
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
Path Parameters
personIdstring(uuid)required
ID of the person
Response
application/json
Response
application/json
A page of addresses belonging to the person.
itemsarray[object]required
Show Child Parameters
pageobjectrequired
Page metadata for a token-based list response.
Show Child Parameters
get/v2/persons/{personId}/addresses
Authentication
Path Parameters
Query Parameters
application/json
Create an address for a firm
Creates a new address and associates it with the specified firm under the authenticated customer’s scope.
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. Returns 400 when the request body fails validation (V2 error shape).
post
Path Parameters
firmIdstring(uuid)required
ID of the firm
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
CreateAddressRequest
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
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).
>= 2 characters<= 2 characters
Example:US
moveInDatestring | null(date)
Date the person moved to this address (YYYY-MM-DD).
Example:2020-01-15
preferredboolean
Whether this should be the person’s preferred address. When the person has no existing addresses, the server sets this to true regardless of the supplied value.
Default:false
Example:false
Response
application/json
Response
application/json
Address created 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
post/v2/firms/{firmId}/addresses
Authentication
Path Parameters
Headers
Body
{
"type": "MAILING",
"addressLine1": "123 Main St",
"city": "Denver",
"state": "CO",
"zip": "80202",
"country": "US"
}
application/json