# Phone Numbers

## List phone numbers

**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.

### Returns

- `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

  - `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.

    - `"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](/channel/imessage/guides/phone-numbers/phone-reputation) 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.

    - `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.

      - `"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.

      - `"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.

      - `"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.

    - `"iMessage"`

    - `"RCS"`

### Example

```http
curl https://api.linqapp.com/api/partner/v3/phone_numbers \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY"
```

#### Response

```json
{
  "phone_numbers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+12025550101",
      "forwarding_number": "+12025550103",
      "line_type": "iMessage",
      "reputation": {
        "state": "HEALTHY",
        "reason_codes": [],
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/channel/imessage/guides/phone-numbers/phone-reputation#healthy"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "phone_number": "+12025550102",
      "forwarding_number": null,
      "line_type": "RCS",
      "reputation": {
        "state": "NEEDS_ATTENTION",
        "reason_codes": [
          "new_conversation_rate"
        ],
        "status": "AT_RISK",
        "doc_url": "https://docs.linqapp.com/channel/imessage/guides/phone-numbers/phone-reputation#at-risk"
      }
    }
  ]
}
```

## Domain Types

### Reputation Driver Key

- `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.

  - `"low_engagement"`

  - `"overall_conversation_health"`

  - `"volume_spike"`

  - `"new_conversation_rate"`

  - `"opt_out_handling"`

  - `"flagged"`

  - `"other"`

### Phone Number List Response

- `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

    - `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.

      - `"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](/channel/imessage/guides/phone-numbers/phone-reputation) 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.

      - `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.

        - `"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.

        - `"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.

        - `"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.

      - `"iMessage"`

      - `"RCS"`
