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

# Phone Numbers API

> Manage number inventory lifecycle from discovery and purchase to activation, webhook config, and number-health remediation.

# Number lifecycle directly affects delivery and reputation.

The Phone Numbers API covers discovery, ownership sync, assignment, and operational state changes.

## Lifecycle stages

1. Discover available inventory (`available`, `pricing`, `countries`).
2. Acquire numbers (`purchase` or `import_owned`).
3. Activate and assign to campaigns/agents.
4. Monitor health and run periodic `sync`/`resync`.
5. Release numbers when no longer needed.

## Inventory and acquisition

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.callaro.ai/api/v1/phone_numbers?page=1&per_page=20" -H "X-Api-Key: $CALLARO_API_KEY"
  curl "https://api.callaro.ai/api/v1/phone_numbers/available?country=IN" -H "X-Api-Key: $CALLARO_API_KEY"
  curl "https://api.callaro.ai/api/v1/phone_numbers/pricing?country=IN" -H "X-Api-Key: $CALLARO_API_KEY"
  curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/purchase" -H "X-Api-Key: $CALLARO_API_KEY" -H "Content-Type: application/json" -d '{"country":"IN","quantity":2,"telephony_connection_id":9}'
  curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/import_owned" -H "X-Api-Key: $CALLARO_API_KEY" -H "Content-Type: application/json" -d '{"numbers":[{"e164":"+14155550100","label":"US Outbound Pool A"}],"telephony_connection_id":9}'
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api.callaro.ai/api/v1/phone_numbers?page=1&per_page=20', { headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } });
  await fetch('https://api.callaro.ai/api/v1/phone_numbers/available?country=IN', { headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } });
  await fetch('https://api.callaro.ai/api/v1/phone_numbers/purchase', {
    method: 'POST',
    headers: { 'X-Api-Key': process.env.CALLARO_API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ country: 'IN', quantity: 2, telephony_connection_id: 9 })
  });
  ```
</CodeGroup>

## Activation, sync, and release

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.callaro.ai/api/v1/phone_numbers/101" -H "X-Api-Key: $CALLARO_API_KEY"
  curl -X PATCH "https://api.callaro.ai/api/v1/phone_numbers/101" -H "X-Api-Key: $CALLARO_API_KEY" -H "Content-Type: application/json" -d '{"label":"India Pool B"}'
  curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/101/activate" -H "X-Api-Key: $CALLARO_API_KEY"
  curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/sync" -H "X-Api-Key: $CALLARO_API_KEY"
  curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/101/resync" -H "X-Api-Key: $CALLARO_API_KEY"
  curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/101/configure_webhooks" -H "X-Api-Key: $CALLARO_API_KEY" -H "Content-Type: application/json" -d '{"status_callback_url":"https://example.com/provider/status"}'
  curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/101/release" -H "X-Api-Key: $CALLARO_API_KEY"
  ```

  ```javascript Node.js theme={null}
  await Promise.all([
    fetch('https://api.callaro.ai/api/v1/phone_numbers/101', { headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } }),
    fetch('https://api.callaro.ai/api/v1/phone_numbers/101', { method: 'PATCH', headers: { 'X-Api-Key': process.env.CALLARO_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ label: 'India Pool B' }) }),
    fetch('https://api.callaro.ai/api/v1/phone_numbers/101/activate', { method: 'POST', headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } }),
    fetch('https://api.callaro.ai/api/v1/phone_numbers/sync', { method: 'POST', headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } })
  ]);
  ```
</CodeGroup>

## Number-health operating rules

* Keep rotating pools per campaign to reduce repeated-caller fatigue.
* Monitor spam-flag indicators and remove affected numbers quickly.
* Use region/timezone-aligned numbers for better answer rates.
* Reconcile provider inventory with periodic `sync`.

## Failure modes

| Symptom                              | Likely cause                                    | Action                                                     |
| ------------------------------------ | ----------------------------------------------- | ---------------------------------------------------------- |
| Purchase fails with validation error | Unsupported region/quantity/connection          | Re-check `countries` and `pricing` constraints             |
| Activation fails                     | Number not correctly bound to connection/tenant | Inspect number detail and connection status                |
| Delivery degrades after launch       | Spam flag or reputation issue                   | Pause high-risk campaigns and rotate numbers               |
| Sync mismatch                        | Provider-side drift                             | Run `resync` on affected numbers and review webhook config |