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 or listing chats, use one of your assigned phone numbers in the from field.

Ineligible numbers. A number can temporarily lose the ability to deliver messages. While it is in that state, requests that would produce new activity on it — sending a message, creating a chat, reacting, typing, group actions — are rejected with 403 (error code 2027) before anything is created. Reads keep working, so your existing chats, messages, and history stay available. Omit from on POST /v3/messages and we pick an eligible number for you, skipping ineligible ones; if none of your assigned numbers are eligible, you get 409 (no from number was ever chosen, so there’s no specific number to blame with a 403).

Published vs unpublished. A published number is available for your account to use. Only published numbers appear in GET /v3/phone_numbers.

Unpublished numbers allow GET requests. POST, PUT, PATCH, and DELETE requests that change a chat return 403 with error code 2033 (Phone number is unpublished).

A number’s existing data is preserved when its status changes to unpublished. Unpublished status alone does not block reads, blocked-handle management, or deletion of your data. Existing authorization, retention, and endpoint rules still apply.

Webhook events are suppressed for affected numbers when their publication status is known to be unpublished.

List phone numbers

GET/v3/phone_numbers

ModelsExpand Collapse

PhoneNumberListResponse object { phone_numbers }

phone_numbers: array of object { id, line_status, phone_number, 3 more }

List of phone numbers assigned to the partner

id: string

Unique identifier for the phone number

formatuuid

line_status: "ACTIVE" or "FLAGGED"

Operational status of the line (distinct from reputation).

ACTIVE — The line is not flagged and can be used normally.
FLAGGED — The line has been flagged and may have limited functionality.

One of the following:

"ACTIVE"

"FLAGGED"

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.

line_type: optional "iMessage" or "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:

"iMessage"

"RCS"