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

# Buy Number

> Allocate a phone number from the shared pool

<Info>
  **Setup prerequisite:** Before buying numbers, complete KYC in the 60db app (**Dashboard → Dialer → KYC**). KYC is not available through the API. Submit your PAN/Aadhaar and address proof. Until approved, buying returns **403 DIALER\_KYC\_REQUIRED / DIALER\_KYC\_PENDING / DIALER\_KYC\_REJECTED**.
</Info>

Allocate a phone number from the shared pool. Costs ₹600 (\$6.00) now and ₹600/month recurring. If your wallet is short, the request fails with **402 RECHARGE\_REQUIRED** and nothing is charged.

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key
</ParamField>

<ParamField header="Content-Type" type="string" required>
  application/json
</ParamField>

### Body

<ParamField body="number" type="string">
  Optional. Specific E.164 number to buy (e.g. `+919876543210`). If omitted, the next available number is allocated.
</ParamField>

<ParamField body="assign_for" type="string">
  Optional. `sip` or `indian_number`. Default is the next in rotation.
</ParamField>

## Response

**201 Created:**

```json theme={null}
{
  "success": true,
  "data": {
    "number": "+919876543210",
    "upstream": { "trunk_id": "...", "status": "active" }
  }
}
```

## Errors

| Status | Code                     | Meaning                                                               |
| ------ | ------------------------ | --------------------------------------------------------------------- |
| 402    | `RECHARGE_REQUIRED`      | Wallet balance too low                                                |
| 403    | `DIALER_KYC_REQUIRED`    | Complete KYC in the 60db app                                          |
| 403    | `DIALER_KYC_PENDING`     | KYC pending approval                                                  |
| 403    | `DIALER_KYC_REJECTED`    | KYC rejected; resubmit in app                                         |
| 409    | `DIALER_NOT_PROVISIONED` | Trunk not set up; use `assign_for: "sip"` and set up SIP trunk in app |
| 409    | `POOL_EMPTY`             | No numbers available                                                  |
| 409    | `NUMBER_NOT_AVAILABLE`   | The specific number requested is taken                                |

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.60db.ai/dialer/pool/allocate \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"assign_for": "sip"}'
  ```

  ```javascript JavaScript theme={null}
  const bought = await client.dialer.numbers.buy();
  console.log('Bought:', bought.data.number);
  ```

  ```python Python theme={null}
  bought = client.dialer.numbers.buy()
  print('Bought:', bought['data']['number'])
  ```
</RequestExample>