> For the complete documentation index, see [llms.txt](https://docs.limecall.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limecall.com/developers/phone-numbers.md).

# Phone numbers API

List the numbers you own and change how they are configured.

| Method  | Path                  | Scope                 |
| ------- | --------------------- | --------------------- |
| `GET`   | `/phone-numbers`      | `phone-numbers:read`  |
| `GET`   | `/phone-numbers/{id}` | `phone-numbers:read`  |
| `PATCH` | `/phone-numbers/{id}` | `phone-numbers:write` |

## List your numbers

```bash
curl https://app.limecall.com/api/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_..."
```

Pass `?userId=...` to return only the numbers assigned to one user.

Each number reports its capabilities. **Check these before sending** — not every number can text, and a `from` on a voice-only number fails at send time rather than at configuration time.

## Update a number

Three fields are accepted. Sending none of them returns `400`.

| Field              | Rules                                                                                                                 |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `forwardingNumber` | **E.164 only** — `+` then 7–15 digits, e.g. `+14155550142`. Anything else returns `400`. `null` turns forwarding off. |
| `voicemailEnabled` | Boolean. A non-boolean returns `400`.                                                                                 |
| `friendlyName`     | String, trimmed, truncated to 120 characters. `null` clears it.                                                       |

```bash
curl -X PATCH https://app.limecall.com/api/v1/phone-numbers/77 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"forwardingNumber":"+14155550142","friendlyName":"Google Ads — Leeds"}'
```

Returns the updated number.

### What setting a forwarding number does

Setting `forwardingNumber` routes the line to an external number, and **clears any team or team-member destination** on it. One line cannot hold three contradictory targets, so the other two are removed rather than left stale.

### What clearing it does not do

Sending `"forwardingNumber": null` stops forwarding to that number. It does **not** hand the line to your AI receptionist — that is a much bigger change than the request asked for, and it is deliberately not implied.

If you want the AI to answer the line, set that destination explicitly in the dashboard. See [Call forwarding & routing](/virtual-numbers/call-forwarding-and-routing.md).

### A legacy alias

`callForwarding` is still accepted, as a string, as `{ target, enabled }`, or as `null`, and lands on the same columns. Prefer `forwardingNumber` in new code.

## What this endpoint will not do

**Buying and porting are not in the API.** Both involve payment and, in most countries, regulatory documents, so they are dashboard-only. See [Buy a number](/virtual-numbers/buy-a-number.md) and [Bring your number](/virtual-numbers/bring-your-number.md).

Releasing a number is likewise dashboard-only — it is irreversible and deliberately not one API call away.