phoneIdstring(uuid)required
Phone identifier.
Example:550e8400-e29b-41d4-a716-446655440000
Phones
Operations for managing phone numbers
Retrieve a phone
Returns a single phone by its identifier.
A 404 is returned when the phone does not exist or is not visible to the authenticated customer — the two cases are intentionally indistinguishable so that resource existence is never leaked across customers. A 403 is returned only when the access token is missing the required scope.
get
Path Parameters
Response
application/json
Response
application/json
The requested phone.
PhoneV2
A phone record returned by V2 phone endpoints.
idstring(uuid)requiredread-only
Phone identifier.
Example:550e8400-e29b-41d4-a716-446655440000
typestringrequired
The type of phone
Allowed values:CELLBUSINESSRESIDENTFAX
Example:CELL
numberstringrequired
10-digit phone number.
Example:3035551234
extensionstring | null
Optional phone extension.
Example:1234
preferredbooleanrequired
Whether this is the preferred phone number.
Example:true
createdAtstring(date-time)requiredread-only
RFC3339 UTC timestamp when the phone was created.
Example:2024-01-15T10:30:00Z
updatedAtstring | null(date-time)read-only
RFC3339 UTC timestamp when the phone was last updated.
Example:2024-01-15T14:45:00Z
get/v2/phones/{phoneId}
Authentication
Path Parameters
application/json
Update a phone
Updates a single phone by its identifier, scoped to the authenticated customer. Setting preferred: true unprefers all other phones for the owning person.
A 404 is returned when the phone does not exist or is not visible to the authenticated customer — the two cases are intentionally indistinguishable so that resource existence is never leaked across customers. A 403 is returned only when the access token is missing the required scope.
put
Path Parameters
phoneIdstring(uuid)required
Phone identifier.
Example:550e8400-e29b-41d4-a716-446655440000
Body
application/json
Body
application/json
UpdatePhoneRequest
typestringrequired
The type of phone
Allowed values:CELLBUSINESSRESIDENTFAX
Example:CELL
numberstringrequired
Phone number (exactly 10 digits)
Match pattern:^[0-9]{10}$
Example:3035551234
extensionstring
Optional phone extension (max 6 characters)
<= 6 characters
Example:1234
preferredbooleanrequired
Whether this is the preferred phone number
Example:true
Response
application/json
Response
application/json
The updated phone.
PhoneV2
A phone record returned by V2 phone endpoints.
idstring(uuid)requiredread-only
Phone identifier.
Example:550e8400-e29b-41d4-a716-446655440000
typestringrequired
The type of phone
Allowed values:CELLBUSINESSRESIDENTFAX
Example:CELL
numberstringrequired
10-digit phone number.
Example:3035551234
extensionstring | null
Optional phone extension.
Example:1234
preferredbooleanrequired
Whether this is the preferred phone number.
Example:true
createdAtstring(date-time)requiredread-only
RFC3339 UTC timestamp when the phone was created.
Example:2024-01-15T10:30:00Z
updatedAtstring | null(date-time)read-only
RFC3339 UTC timestamp when the phone was last updated.
Example:2024-01-15T14:45:00Z
put/v2/phones/{phoneId}
Authentication
Path Parameters
Body
{
"type": "CELL",
"number": "3035551234",
"preferred": true
}
application/json
Delete phone
Permanently deletes a phone by ID, scoped to the authenticated customer. Returns 404 (never 403) when the phone does not exist or belongs to a different customer. The two cases are intentionally indistinguishable — the endpoint does not return an idempotent 204 for unknown IDs — so that resource existence is not leaked across customers.
delete
Path Parameters
phoneIdstring(uuid)required
Phone identifier.
Example:550e8400-e29b-41d4-a716-446655440000
Response
Response
Phone deleted successfully.
delete/v2/phones/{phoneId}
Authentication
Path Parameters
Create a phone for a person
Creates a new phone and associates it with the specified person. The first phone added is automatically marked preferred. Sending preferred: true on a subsequent phone unprefers all existing phones for that person. A person may have at most 5 phones.
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
CreatePhoneRequest
typestringrequired
The type of phone
Allowed values:CELLBUSINESSRESIDENTFAX
Example:CELL
numberstringrequired
Phone number (exactly 10 digits)
Match pattern:^[0-9]{10}$
Example:3035551234
extensionstring
Optional phone extension (max 6 characters)
<= 6 characters
Example:1234
preferredbooleanrequired
Whether this is the preferred phone number
Example:true
Response
application/json
Response
application/json
Phone created successfully.
PhoneV2
A phone record returned by V2 phone endpoints.
idstring(uuid)requiredread-only
Phone identifier.
Example:550e8400-e29b-41d4-a716-446655440000
typestringrequired
The type of phone
Allowed values:CELLBUSINESSRESIDENTFAX
Example:CELL
numberstringrequired
10-digit phone number.
Example:3035551234
extensionstring | null
Optional phone extension.
Example:1234
preferredbooleanrequired
Whether this is the preferred phone number.
Example:true
createdAtstring(date-time)requiredread-only
RFC3339 UTC timestamp when the phone was created.
Example:2024-01-15T10:30:00Z
updatedAtstring | null(date-time)read-only
RFC3339 UTC timestamp when the phone was last updated.
Example:2024-01-15T14:45:00Z
post/v2/persons/{personId}/phones
Authentication
Path Parameters
Headers
Body
{
"type": "CELL",
"number": "3035551234",
"preferred": true
}
application/json