Skip to content
Linq

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.

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
ReputationDriverKey = "low_engagement" or "overall_conversation_health" or "volume_spike" or 4 more

Stable driver-category identifier — what is dragging the line, or one of its conversations, down.

  • low_engagement — The conversation is one-sided: several messages sent, few or no replies back. Pause or rework outreach where recipients are not replying, and lead with messages that invite a response. Conversation-level: it appears on evidence.unhealthy_chats[].driver_keys, never in drivers.
  • overall_conversation_health — A large share of this line’s active conversations are trending unhealthy. Fix the unhealthy conversations first — review their content and timing, and whether recipients are engaging.
  • volume_spike — This line’s daily sending volume jumped far above its own normal level while few recipients were replying, or exceeded the recommended daily volume for a single line. Ramp volume gradually instead of spiking, prioritize people who have already engaged with you, and spread sustained high volume across additional lines.
  • new_conversation_rate — This line is starting too many brand-new conversations in a single day. Spread new conversations out over time instead of starting many at once.
  • opt_out_handling — Recipients asked this line to stop. Continuing to message someone after they ask you to stop is a serious deliverability and trust risk. Honor every stop request immediately: send nothing further to that recipient unless they opt back in. Every send to them is rejected with 403 (error code 2024), including a final courtesy message — to send one telling them they can reply to resume, set override_optout: true on that single request.
  • flagged — This line has a delivery problem. Our team can help move your conversations to a working line. On a line with no recent conversations: This line has a delivery problem. It has no recent conversations, so nothing needs to move. Our team can help you get a working line.
  • other — Fallback for a signal without dedicated partner copy.
One of the following:
"low_engagement"
"overall_conversation_health"
"volume_spike"
"new_conversation_rate"
"opt_out_handling"
"flagged"
"other"
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, reason_codes, state, 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
reason_codes: array of ReputationDriverKey

What is behind state, in a stable order. Empty when nothing is. Same vocabulary as the reputation report’s drivers.

One of the following:
"low_engagement"
"overall_conversation_health"
"volume_spike"
"new_conversation_rate"
"opt_out_handling"
"flagged"
"other"
state: "HEALTHY" or "WATCH" or "NEEDS_ATTENTION" or "DELIVERY_LIMITED"

Current state of this phone line.

  • HEALTHY — This line is in good standing.
  • WATCH — A recent change in activity that usually settles on its own.
  • NEEDS_ATTENTION — A sustained pattern that needs a change in how this line is used.
  • DELIVERY_LIMITED — Outbound messages from this line are not being delivered.

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

One of the following:
"HEALTHY"
"WATCH"
"NEEDS_ATTENTION"
"DELIVERY_LIMITED"
status: "HEALTHY" or "AT_RISK" or "CRITICAL"

Legacy. Use state. Derived from state: HEALTHY and WATCH report HEALTHY, NEEDS_ATTENTION reports AT_RISK, and DELIVERY_LIMITED reports CRITICAL. It stays available for a long notice period before removal.

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"