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

# Acquire a Calling Number

> Authorize purchase of one selected US Voice number.

Purchases one available US Voice number. First [search available numbers](https://docs.tracklysms.com/api-reference/voice/numbers/search-calling-numbers.md) and [quote a number](https://docs.tracklysms.com/api-reference/voice/numbers/quote-calling-number.md). Requires `voice_calls.write`, the **Voice Calls** product entitlement, and an API key created by a current account owner. Your account must also pass the existing reseller and billing checks.

The `202` response acknowledges a durable acquisition attempt, not completed ownership. Follow its `Location` header to [read the operation](https://docs.tracklysms.com/api-reference/voice/numbers/get-number-acquisition.md). If the response is lost or the outcome is uncertain, retry with the same `requestId` and identical body; do not use a new request ID for the same intended purchase.

## Body Parameters

**requestId** `string` *required*

Stable purchase identity: 1–128 printable ASCII characters without spaces.

**selectionToken** `string` *required*

An unused, unexpired token from your account's available-number search.

**billingAuthorization** `object` *required*

Exactly `quoteId` and `consentVersion` from a priced quote. Obtain the account owner's consent to that quote before sending this request.

## Response Fields

**id** `string`

The acquisition operation ID.

**status** `string`

The durable status; `complete` confirms acquisition, while `outcome_unknown` requires recovery.

**result** `object`

The acquisition result when complete.

**errorCode** `string | null`

A failure code, when present.

## Example

```bash cURL theme={null}
curl -X POST https://api.tracklysms.com/api/v1/voice/number-acquisitions \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "number-order-123",
    "selectionToken": "665f1e2a9c4b1a0012ab99ff",
    "billingAuthorization": {
      "quoteId": "pvquote_your_current_quote",
      "consentVersion": "your_current_consent_version"
    }
  }'
```

## Error Codes

| Status | Code | Meaning |
| - | - | - |
| 403 | `owner_required` | The key's creator is not a current account owner. |
| 404 | `selection_not_found` | The selection does not belong to this account. |
| 409 | `selection_expired`, `selection_consumed` | Search again before authorizing a new purchase. |
| 409 | `idempotency_conflict` | The request ID belongs to different input. |
| 422 | `invalid_billing_authorization`, `invalid_selection` | Correct the selection or quote consent fields. |
| 429 | `rate_limited` | The account or key creator reached the paid setup limit. |
| 503 | `rate_limit_unavailable`, `setup_indexes_required` | Purchase admission is temporarily unavailable. Retry with the same `requestId`. |


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