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

# Phone Numbers

> Provision and manage US phone numbers for your agents.

# Phone Numbers

Each agent can have **one active phone number**. Numbers are **US only** and
cost **\$2.00/month** per number, deducted from your balance.

JavaScript examples call `https://api.agentline.cloud` with `fetch` and a
Bearer `al_live_...` key. The Node package is not on npm.

## Buy a number

<CodeGroup>
  ```python theme={null}
  number = client.numbers.buy(
      agent_id=agent.id,
      country="US",
      number_type="local",
      area_code="415",
  )
  ```

  ```javascript theme={null}
  const number = await fetch("https://api.agentline.cloud/v1/numbers", {
    method: "POST",
    headers: {
      Authorization: "Bearer al_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: agent.id,
      country: "US",
      number_type: "local",
      area_code: "415",
    }),
  }).then((res) => res.json());
  ```
</CodeGroup>

| Field | Notes |
| - | - |
| `agent_id` | Agent to assign the number to (required) |
| `country` | `US` only |
| `number_type` | `local` or `tollfree` |
| `area_code` | Preferred 3-digit US area code (e.g. `212`, `415`, `310`) |

## List and reassign

<CodeGroup>
  ```python theme={null}
  client.numbers.list()
  client.numbers.get(number.id)
  client.numbers.reassign(number.id, agent_id=other_agent.id)
  ```

  ```javascript theme={null}
  const headers = { Authorization: "Bearer al_live_..." };

  await fetch("https://api.agentline.cloud/v1/numbers", { headers });
  await fetch(`https://api.agentline.cloud/v1/numbers/${number.id}`, { headers });
  await fetch(
    `https://api.agentline.cloud/v1/numbers/${number.id}/reassign?agent_id=${otherAgent.id}`,
    { method: "PATCH", headers },
  );
  ```
</CodeGroup>

<Note>
  Reassigning moves the number to another agent. The target agent must not
  already have an active number. Deleting an agent detaches (but does not
  release) its number.
</Note>

## Release a number

`POST /v1/numbers/{number_id}/release`

<Warning>
  Destructive. This unrents the number from the carrier. It cannot be
  recovered, and calls and texts to it stop. The request is refused while
  a call is in progress or a lease is still active.
</Warning>


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