> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unpod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a Number

> Add an Unpod number from the dashboard or the API

You need an Unpod number to make or receive calls: it's the `from` of the calls you place
and the number people dial to reach you. Add one from the Unpod pool in either of two ways:

* **[From the dashboard](#from-the-dashboard)** - pick a number and connect it in a few
  clicks.
* **[From the API](#from-the-api)** - list the pool, attach a number and check it's ready,
  all in code.

## From the dashboard

> [!TIP]
>
> Using the Telephony APIs ([Quick Start](https://docs.unpod.ai/telephony/apis/quickstart.md))? Attach the number
> [from the API](#from-the-api) with `attach_type="human_call"`. The steps below connect it
> to a SIP trunk or an agent.

**1. Open Telephony → Numbers and click +**

The **+** button next to the **Telephony** heading opens the number pool.

![Unpod Telephony page with the + button highlighted](https://mintcdn.com/unpodai/sT5UEL5itGmgYjlE/images/unpod-numbers/01-add-number.png?fit=max\&auto=format\&n=sT5UEL5itGmgYjlE\&q=85\&s=f78e4759ce65effe6b7389c9b877b4fd)

Telephony → Numbers - the + button opens the number pool

**2. Select a number and click Save**

**Available Numbers** lists every number you can add. Click **Select** on one, then
**Save**.

![Available Numbers panel with one number selected and the Save button highlighted](https://mintcdn.com/unpodai/sT5UEL5itGmgYjlE/images/unpod-numbers/02-select-number.png?fit=max\&auto=format\&n=sT5UEL5itGmgYjlE\&q=85\&s=4d6211425cf214c13e0b2074b6f5d0f6)

Available Numbers - select one, then Save

**3. Click Connect to**

The number starts **Not Linked**. **Connect to** offers **SIP Trunk** (your own SIP
client places and answers calls) and **Agents** (an Unpod AI agent answers).

![Number Configuration showing Not Linked and the Connect to menu with SIP Trunk and Agents](https://mintcdn.com/unpodai/sT5UEL5itGmgYjlE/images/unpod-numbers/03-connect-to.png?fit=max\&auto=format\&n=sT5UEL5itGmgYjlE\&q=85\&s=3ae68fa662bddd63fd6058d7a5e5256e)

A new number starts Not Linked - Connect to opens the options

**4. Ready (SIP Trunk)**

After **Connect to → SIP Trunk**, the number turns **Linked** and shows its outbound
trunk details.

![Linked number showing Outbound Trunk Details: address, port, protocol, username and password](https://mintcdn.com/unpodai/sT5UEL5itGmgYjlE/images/unpod-numbers/04-outbound-ready.png?fit=max\&auto=format\&n=sT5UEL5itGmgYjlE\&q=85\&s=6390846851feb4b2749144146f234072)

Outbound Trunk Details - ready as soon as you choose SIP Trunk

For the trunk values and the inbound setup, see the full
[dashboard walkthrough](https://docs.unpod.ai/telephony/integrations/unpod/dashboard.md).

## From the API

Export your [credentials](https://docs.unpod.ai/telephony/introduction.md#credentials) (`UNPOD_BASE_URL`,
`UNPOD_PLATFORM_TOKEN`, `UNPOD_ORG_HANDLE`) first.

### List numbers

The list holds the free pool plus the numbers your org already has. Pick one whose
`state` is `NOT_ASSIGNED` and whose `active` is `true`. The SDK folds both into
`status`: `not_assigned` means you can attach it.

```python Python theme={null}
from unpod import Client

with Client() as client:
    for n in client.telephony.numbers.list():
        print(n.number, n.status)  # not_assigned, assigned or closed
```

```bash cURL theme={null}
curl -s "https://unpod.ai/api/v2/platform/telephony/numbers/?include_assigned=true" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE"
```

The response:

```json theme={null}
{"status_code": 200, "message": "...", "data": [
  {"id": 12, "number": "+919000000001", "state": "NOT_ASSIGNED", "active": true},
  {"id": 9, "number": "+919000000002", "state": "ASSIGNED", "active": true}
]}
```

| `status` (SDK) | `state` / `active` (API) | Meaning |
| - | - | - |
| `not_assigned` | `NOT_ASSIGNED` / `true` | Free - you can attach it |
| `assigned` | `ASSIGNED` | Already attached to your org |
| `closed` | anything else | Not available |

### Attach a number

```python Python theme={null}
import httpx
from unpod import Client

NUMBER = "+919000000001"  # a not_assigned number from the list

with Client() as client:
    try:
        result = client.telephony.numbers.attach(NUMBER, attach_type="human_call")
    except httpx.HTTPStatusError as e:  # nothing attached: the body says why
        raise SystemExit(e.response.text)
    for r in result.numbers:  # one row per number
        print(r.number, r.ok, r.connection_state, r.error)
```

```bash cURL theme={null}
curl -s -X POST "https://unpod.ai/api/v2/platform/telephony/numbers/attach/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+919000000001"], "attach_type": "human_call"}'
```

Pass one number or a list, in strict E.164 (`+` and the country code). Each number
succeeds or fails on its own: check `ok` and `error` on every row (`data.numbers` in the
cURL response). If no number attaches, the whole request fails: `400`, `402` (no balance)
or `206` (over your plan's channel quota). The SDK raises `httpx.HTTPStatusError` on `400`
and `402`, but not on `206`, so still check `ok`.

| Option | Who handles the calls |
| - | - |
| `attach_type="human_call"` | Your app, with the Telephony APIs. Leave out `agent_id` |
| `agent_id="…"` | An Unpod AI agent (`attach_type="agent"`, the default) |
| `attach_type="pipeline"`, `pipe_id="…"` | An Unpod pipeline. `pipe_id` is required (over HTTP send `supervoice_agent_id`; `pipe_id` is an accepted alias) |

To receive calls on a `human_call` number, point it at your app: see
[Incoming Calls](https://docs.unpod.ai/telephony/apis/incoming-calls.md).

### Check status

The overview lists your org's numbers with their `connection_state` (see
[Number states](#number-states)). Check it before you use a number as `from`.

```python Python theme={null}
from unpod import Client

with Client() as client:
    for o in client.telephony.overview():
        print(o.number, o.connection_state)
```

```bash cURL theme={null}
curl -s "https://unpod.ai/api/v2/platform/telephony/overview/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE"
```

### Detach a number

Detach releases the number back to `NOT_ASSIGNED`; it isn't deleted. A number your org
owns stays yours to attach again. A number you took from the shared pool goes back to the
pool, where another org can take it.

```python Python theme={null}
from unpod import Client

with Client() as client:
    result = client.telephony.numbers.detach("+919000000001")
    for r in result.numbers:
        print(r.number, r.ok, r.error)
```

```bash cURL theme={null}
curl -s -X POST "https://unpod.ai/api/v2/platform/telephony/numbers/detach/" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+919000000001"]}'
```

## Number states

`connection_state` in the overview tells you whether a number is ready:

| `connection_state` | Meaning |
| - | - |
| `NOT_LINKED` | Not routed yet. Rejected as the `from` of a call |
| `PENDING_VERIFY` | Routed, waiting for its first real inbound call. Accepted as `from` |
| `LINKED` | A real inbound call has connected through it |
| `ERROR` | Routing failed; Unpod retries it in the background |

On a call, `400 from_not_owned` means `from` isn't one of your org's numbers at all. A
`403 forbidden: from is not a number available to this organization` means it is yours but
isn't ready: check its `connection_state`.

## Reference

* [List Numbers](https://docs.unpod.ai/telephony/numbers/list-numbers.md) - `GET /telephony/numbers/`
* [Telephony Overview](https://docs.unpod.ai/telephony/calls/overview.md) - `GET /telephony/overview/`
* [Incoming Calls](https://docs.unpod.ai/telephony/apis/incoming-calls.md) - answer calls on your number


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.