> ## 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.

# Search Calling Numbers

> Find available US Voice numbers and receive short-lived selection tokens.

Searches available US Voice numbers for purchase. Each result includes a `selectionToken` that belongs to your account and expires after 10 minutes. The search can finish with no available selections. Requires `voice_calls.write`, the **Voice Calls** product entitlement, and an API key created by a current account owner.

The search is a durable operation. Reuse the same `requestId` with the same body when retrying; a changed body for that ID returns `409 idempotency_conflict`. A provider error can leave the operation in `outcome_unknown`. Repeat this `POST` with the same `requestId` and body to read or recover the search; the public operation-status `GET` supports acquisitions only.

## Body Parameters

**requestId** `string` *required*

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

**npa** `integer`

US area code from `200` to `999`.

**limit** `integer` (default: 20)

Maximum candidates, from `1` to `20`.

## Response Fields

**id** `string`

The durable search operation ID.

**status** `string`

The operation status. `complete` means `result.selections` is ready.

**errorCode** `string | null`

A failure code, when present.

**result.selections** `array`

Available numbers when the search completes. Each entry has `selectionToken`, `e164`, and `expiresAt`.

## Example

```bash cURL theme={null}
curl -X POST https://api.tracklysms.com/api/v1/voice/calling-numbers/search \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"number-search-123","npa":415,"limit":5}'
```

```json 200 OK theme={null}
{
  "id": "665f1e2a9c4b1a0012ab34cd",
  "action": "number_search",
  "resourceId": "number-search-123",
  "status": "complete",
  "errorCode": null,
  "result": {
    "selections": [
      {
        "selectionToken": "665f1e2a9c4b1a0012ab99ff",
        "e164": "+14155551234",
        "expiresAt": "2026-10-30T18:10:00Z"
      }
    ]
  },
  "createdAt": "2026-10-30T18:00:00Z",
  "submittedAt": "2026-10-30T18:00:00Z",
  "completedAt": "2026-10-30T18:00:00Z"
}
```

## Error Codes

| Status | Code | Meaning |
| - | - | - |
| 403 | `owner_required` | The key's creator is not a current account owner. |
| 409 | `idempotency_conflict` | The request ID belongs to different input. |
| 422 | `invalid_request_id`, `invalid_search` | Correct the retry identity, area code, or limit. |
| 429 | `rate_limited` | The account or key creator reached the setup request limit. |
| 503 | `rate_limit_unavailable`, `setup_indexes_required` | Admission is temporarily unavailable. Retry with the same `requestId`. |


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