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"
}
}'
{
"id": "<string>",
"status": "<string>",
"result": {},
"errorCode": {}
}Voice Calls (v1)
Acquire a Calling Number
Authorize purchase of one selected US Voice number.
POST
/
v1
/
voice
/
number-acquisitions
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"
}
}'
{
"id": "<string>",
"status": "<string>",
"result": {},
"errorCode": {}
}Purchases one available US Voice number. First search available numbers and quote a number. 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. 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
Exactly
quoteId and consentVersion from a priced quote. Obtain the account owner’s consent to that quote before sending this request.Response Fields
Example
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. |