Get a Number

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 - pick a number and connect it in a few clicks.
From the API - list the pool, attach a number and check it’s ready, all in code.

From the dashboard

Using the Telephony APIs (Quick Start)? Attach the number from the API with attach_type="human_call". The steps below connect it to a SIP trunk or an agent.

Open Telephony → Numbers and click +

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

Unpod Telephony page with the + button highlighted — Telephony → Numbers - the + button opens the number pool

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 — Available Numbers - select one, then Save

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 — A new number starts Not Linked - Connect to opens the options

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 — Outbound Trunk Details - ready as soon as you choose SIP Trunk

For the trunk values and the inbound setup, see the full dashboard walkthrough.

From the API

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

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

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:

{"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

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)

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.

Check status

The overview lists your org’s numbers with their connection_state (see Number states). Check it before you use a number as from.

from unpod import Client

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

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.

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)

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 - GET /telephony/numbers/
Telephony Overview - GET /telephony/overview/
Incoming Calls - answer calls on your number

Getting Started

Telephony APIs

SIP Trunking

Integrations

From the dashboard

From the API

List numbers

Attach a number

Check status

Detach a number

Number states

Reference

​From the dashboard

​From the API

​List numbers

​Attach a number

​Check status

​Detach a number

​Number states

​Reference

From the dashboard

From the API

List numbers

Attach a number

Check status

Detach a number

Number states

Reference