---
title: Phone Numbers | API Docs
description: Discover and monitor the phone numbers provisioned on your account.
---

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

“Line” and “phone number” mean the same thing

These guides use **line** in prose (the natural term for a single provisioned number) and **phone number** in API fields (`phone_number`) and feature names (**Phone Reputation**). They refer to the same thing.

## List your phone numbers

See the [List Phone Numbers API reference](/channel/imessage/api/resources/phone_numbers/methods/list/index.md) for the full endpoint specification.

- [cURL](#tab-panel-0-0)
- [TypeScript](#tab-panel-0-1)
- [Python](#tab-panel-0-2)
- [Go](#tab-panel-0-3)

Terminal window

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

```
await client.phoneNumbers.list();
```

```
client.phoneNumbers.list()
```

```
client.PhoneNumbers.List(context.TODO())
```

## Choosing a line

Most of the time you don’t. `POST /v3/messages` takes recipients with no `from` and picks the line itself — reusing the line the recipients’ existing chat is on, opening a new chat on the best available line, or moving them onto a fresh line when the current one can’t send. Adding lines to your account puts them in that rotation with no code change. See [Sending Messages → Let Linq pick the line](/channel/imessage/guides/messaging/sending-messages#let-linq-pick-the-line/index.md) and [Just hit send: introducing managed load balancing](https://linqapp.com/blog/just-hit-send-introducing-managed-load-balancing).

Where you *do* need a specific number is onboarding — showing a new user which line to text first, or giving them a contact card to save. That’s what `GET /v3/available_number` is for.

- [cURL](#tab-panel-1-0)
- [TypeScript](#tab-panel-1-1)
- [Python](#tab-panel-1-2)
- [Go](#tab-panel-1-3)

Terminal window

```
curl https://api.linqapp.com/api/partner/v3/available_number \
  -H "Authorization: Bearer $LINQ_API_KEY"
```

```
await client.availableNumber.retrieve();
```

```
client.availableNumber.retrieve()
```

```
client.AvailableNumber.Retrieve(context.TODO())
```

It returns the selected `phone_number` plus `vcf_url`: a time-limited vCard carrying that line’s contact card, with the selected number as the primary `TEL` and your other available lines as backups — so a recipient who saves it still has a path to you if the primary line goes down. The link expires, so call again for a fresh one.

- Pass `to` to make the choice **sticky** — recipients who already have a chat with you stay on the line they’re already on.
- Pass `exclude_from` to leave lines out of the pick, out of the sticky choice, and out of the vCard’s backup numbers. Entries must be E.164; excluding all of your available lines returns `400`.
- With no `to`, you get the least-recently-used available line, always preferring a healthier [reputation](/channel/imessage/guides/phone-numbers/phone-reputation/index.md). Suggestions and your own sends both count as use, so successive calls cycle through the pool and new users spread evenly across it.

This does **not** reserve the line — pass the returned `phone_number` as `from` when you create the chat if you need that exact line.

Not a per-message call

Calling this before every send, or pinning a fixed `from`, opts you out of the balancing and failover that `POST /v3/messages` does for you. Use it when onboarding a new user, and let the send endpoint route everything after that.

## Update phone number

Set a `forwarding_number` to route inbound calls on a line elsewhere. Pass an empty string (or `null`) to clear it. See the [Update Phone Number API reference](/channel/imessage/api/resources/phone_numbers/methods/update/index.md) for the full endpoint specification.

| Field               | Required | Type     | Description                                                                  |
| ------------------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `forwarding_number` | Yes      | `string` | The forwarding number in E.164 format. Set to null or empty string to clear. |

- [cURL](#tab-panel-2-0)
- [TypeScript](#tab-panel-2-1)
- [Python](#tab-panel-2-2)
- [Go](#tab-panel-2-3)

Terminal window

```
curl -X PUT https://api.linqapp.com/api/partner/v3/phone_numbers/{phoneNumberId} \
  -H "Authorization: Bearer $LINQ_API_KEY"
```

```
await client.phoneNumbers.update({phoneNumberId});
```

```
client.phoneNumbers.update({phone_number_id})
```

```
client.PhoneNumbers.Update(context.TODO(), {phoneNumberId})
```

## Voice calls

The API does not place or answer voice calls directly, but you can route calls around your Linq line:

- **Inbound calls** — Forward your Linq line to a number of your choice by setting a `forwarding_number` via the [Update phone number](#update-phone-number) endpoint above. Pass an empty string to clear the forwarding number.
- **Outbound calls** — If you own another number that supports caller-ID masking (for example, a [Twilio number with Verified Caller ID](https://help.twilio.com/articles/223179848-Using-a-non-Twilio-number-as-the-caller-ID-for-outgoing-calls)), you can mask your Linq number over it so the Linq number displays on outbound calls.
- **AI voice agents** — Use a VOIP number (commonly Twilio) with the inbound/outbound setups above to route calls to and from your agent via the [Twilio API](https://www.twilio.com/docs/usage/api).

See the [FAQ](/channel/imessage/guides/resources/faq#voice-calls/index.md) for more.

## Provisioning

Numbers are provisioned by your Linq representative — there is no self-serve create or delete endpoint on the V3 API. To add or release a line, contact support with the details of the line you want changed.

## Status changes

Numbers carry two independent fields you can react to:

- **`status`** — the line’s current sending state.

  - **`ACTIVE`** — sending and receiving normally.
  - **`FLAGGED`** — a service flag has degraded the number’s ability to send. New messages on a flagged line may fail with delivery errors.

- **`reputation`** — line-level prediction of where the line is heading based on the patterns in its conversations *and* its overall messaging activity. See the [Phone Reputation guide](/channel/imessage/guides/phone-numbers/phone-reputation/index.md) for the `HEALTHY` / `AT_RISK` / `CRITICAL` values, [what drives each one](/channel/imessage/guides/phone-numbers/phone-reputation#what-moves-a-lines-reputation/index.md), and how to react.

The [`phone_number.status_updated`](/channel/imessage/guides/webhooks/events#phone-number-events/index.md) webhook fires when **either** field changes, and every payload carries both pairs (`previous_status` / `new_status` and `previous_reputation` / `new_reputation`), so a single subscription covers both signals.

```
{
  "phone_number": "+12025551234",
  "previous_status": "ACTIVE",
  "new_status": "FLAGGED",
  "previous_reputation": "AT_RISK",
  "new_reputation": "CRITICAL",
  "changed_at": "2026-02-18T18:35:05.000Z"
}
```

You can also enable **Flagged-number Slack notifications** in the [API Tooling](https://dashboard.linqapp.com/api-tooling/phone-numbers) settings to get a Slack message in your linked partner channel whenever a number’s `status` changes.

**Recommended handling:**

- Page on-call when a production line transitions to `FLAGGED`.
- Pause outbound sends on the affected line until it returns to `ACTIVE`.
- Contact your Linq representative for remediation.
- For `reputation` transitions to `AT_RISK` or `CRITICAL`, follow the playbook in the [Phone Reputation guide](/channel/imessage/guides/phone-numbers/phone-reputation/index.md) — typically slow the line’s pace before the line ends up `FLAGGED`.

## Related

- [Key Concepts: Phone Numbers](/channel/imessage/getting-started/key-concepts#phone-numbers/index.md)
- [Phone Reputation](/channel/imessage/guides/phone-numbers/phone-reputation/index.md) — line-level reputation scoring
- [Sending Messages](/channel/imessage/guides/messaging/sending-messages#let-linq-pick-the-line/index.md) — sending without a `from`
- [Webhooks: Phone number events](/channel/imessage/guides/webhooks/events#phone-number-events/index.md)
- [API Reference: Phone Numbers](/channel/imessage/api/resources/phone_numbers/index.md)
- [API Reference: Get an available sending number](/channel/imessage/api/resources/available_number/methods/retrieve/index.md)