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

## List your phone numbers

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

- [cURL](#tab-panel-104)
- [TypeScript](#tab-panel-105)
- [Python](#tab-panel-106)
- [Go](#tab-panel-107)

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

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

- **`health_status`** — line-level prediction of where the line is heading based on the patterns in its conversations *and* its overall messaging activity. See the [Phone Health guide](/guides/phone-numbers/phone-health/index.md) for the `HEALTHY` / `AT_RISK` / `CRITICAL` values and how to react.

The [`phone_number.status_updated`](/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_health_status` / `new_health_status`), so a single subscription covers both signals.

```
{
  "phone_number": "+12025551234",
  "previous_status": "ACTIVE",
  "new_status": "FLAGGED",
  "previous_health_status": "AT_RISK",
  "new_health_status": "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 `health_status` transitions to `AT_RISK` or `CRITICAL`, follow the playbook in the [Phone Health guide](/guides/phone-numbers/phone-health/index.md) — typically slow the line’s pace before the line ends up `FLAGGED`.

## Related

- [Key Concepts: Phone Numbers](/getting-started/key-concepts#phone-numbers/index.md)
- [Phone Health](/guides/phone-numbers/phone-health/index.md) — line-level health scoring
- [Webhooks: Phone number events](/guides/webhooks/events#phone-number-events/index.md)
- [API Reference: Phone Numbers](/api/resources/phone_numbers/index.md)