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}'
{
"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"
}
Voice Calls (v1)
Search Calling Numbers
Find available US Voice numbers and receive short-lived selection tokens.
POST
/
v1
/
voice
/
calling-numbers
/
search
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}'
{
"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"
}
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
Response Fields
Available numbers when the search completes. Each entry has
selectionToken, e164, and expiresAt.Example
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}'
{
"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. |