Phone Numbers

Phone Numbers represent the phone numbers assigned to your partner account.

Use the list phone numbers endpoint to discover which phone numbers are available for sending messages.

When creating chats, listing chats, or sending a voice memo, use one of your assigned phone numbers in the from field.

List phone numbers

GET/v3/phone_numbers

Update a phone number

PUT/v3/phone_numbers/{phoneNumberId}

ModelsExpand Collapse

PhoneNumberListResponse object { phone_numbers }

phone_numbers: array of object { id, phone_number, reputation, forwarding_number }

List of phone numbers assigned to the partner

id: string

Unique identifier for the phone number

formatuuid

phone_number: string

Phone number in E.164 format

reputation: object { doc_url, status }

[BETA] Current reputation for a phone line. Always present — lines start at HEALTHY and may shift based on aggregate engagement and delivery signals across all conversations on the line.

Unlike chat health, line reputation does not include opted_out — opt-out applies to individual recipients, not the whole line.

See the Phone Reputation guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Phone Reputation guide for this status.

formaturi

status: "HEALTHY" or "AT_RISK" or "CRITICAL"

Current reputation of this phone line.

HEALTHY — The line is in good standing. Send normally.
AT_RISK — Warning signs on the line: engagement is low across many of its conversations, or it’s starting too many brand-new conversations in a single day — and a spike in send volume can add to either. Slow the line’s send pace, avoid opening many new conversations at once, and review your messaging patterns.
CRITICAL — Strong signals that messages from this line aren’t landing well. Pause outbound on the line until it recovers.

Defaults to HEALTHY for lines that have not yet been scored.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

forwarding_number: optional string

The forwarding number associated with this phone number, in E.164 format. Null when no forwarding number is configured.

PhoneNumberUpdateResponse object { id, forwarding_number, phone_number }

id: string

Unique identifier for the phone number

formatuuid

forwarding_number: string

The forwarding number after the update. Null when cleared.

phone_number: string

Phone number in E.164 format