List phone numbers

phone_numbers.list() -> PhoneNumberListResponse

GET/v3/phone_numbers

Returns all phone numbers assigned to the authenticated partner. Use this endpoint to discover which phone numbers are available for use as the from field when creating a chat, listing chats, or sending a voice memo.

ReturnsExpand Collapse

class PhoneNumberListResponse: …

phone_numbers: List[PhoneNumber]

List of phone numbers assigned to the partner

id: str

Unique identifier for the phone number

formatuuid

health_status: PhoneNumberHealthStatus

[BETA] Current health 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 health does not include opted_out — opt-out applies to individual recipients, not the whole line.

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

doc_url: str

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

formaturi

status: Literal["HEALTHY", "AT_RISK", "CRITICAL", "FLAGGED"]

Current health of this phone line as assessed by risk-service.

HEALTHY — No elevated risk detected.
AT_RISK — Elevated risk indicators present; consider reducing send volume or reviewing messaging patterns.
CRITICAL — High risk; further sending may result in line flagging or restriction.
FLAGGED — The line is actively dropping iMessages and is in a degraded state. Move traffic off it immediately. Depending on severity it may recover in at least 24 hours.

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

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"FLAGGED"

phone_number: str

Phone number in E.164 format

List phone numbers

import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
phone_numbers = client.phone_numbers.list()
print(phone_numbers.phone_numbers)

{
  "phone_numbers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+12025551234",
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/guides/phone-numbers/phone-health#healthy"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "phone_number": "+12025559876",
      "health_status": {
        "status": "AT_RISK",
        "doc_url": "https://docs.linqapp.com/guides/phone-numbers/phone-health#at-risk"
      }
    }
  ]
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "phone_numbers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+12025551234",
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/guides/phone-numbers/phone-health#healthy"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "phone_number": "+12025559876",
      "health_status": {
        "status": "AT_RISK",
        "doc_url": "https://docs.linqapp.com/guides/phone-numbers/phone-health#at-risk"
      }
    }
  ]
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}