Create an order
Charges your wallet and returns the order with its numbers. Send an Idempotency-Key header so a retry can never buy twice. Check status: an order can be failed (nothing charged) or still provisioning when this returns.
apiKeyAuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
Idempotency-Key?stringA value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again.
8 <= length <= 200application/json- body
country*stringISO 3166-1 alpha-2 country code, for example US or GB
^[A-Z]{2}$product?stringany_service receives SMS from anyone; single_service is locked to one sender
"any_service""any_service""single_service"service?stringService id from the offers list; required for single_service
1 <= length <= 40duration*stringLength of the rental
"12h""1d""7d""30d""180d""365d"quantity?integerHow many numbers to buy
1 <= value <= 501autoRenew?booleanExtend each number shortly before it ends
falsereceiveCalls?booleanAsk for numbers that also take calls, where inboundVoice is on offer
customerId*stringRequired: every purchase belongs to one of your customers
Created
application/json- response
Created
id*stringstatus*stringcompleted: all numbers delivered. failed: nothing charged. provisioning: the carrier is still assigning some numbers. needs_reconciliation: being verified with the carrier.
"created""purchasing""provisioning""completed""failed""needs_reconciliation"customerId*|The customer this was bought for, if any
country*stringISO 3166-1 alpha-2 country code, for example US or GB
^[A-Z]{2}$product*stringany_service receives SMS from anyone; single_service is locked to one sender
"any_service""single_service"service*string|nullduration*stringLength of the rental
"12h""1d""7d""30d""180d""365d"quantity*integerfulfilledCount*integerNumbers delivered so far
autoRenew*booleanunitPrice*integerAmount in minor units (US cents)
totalPrice*integerCharged for the numbers delivered, in minor units
currency*"USD""USD"failure*|Why the order failed, when it did
numbers*array<>createdAt*stringISO 8601 timestamp
date-timeupdatedAt*stringISO 8601 timestamp
date-timecurl -X POST "https://example.com/v1/numbers/orders" \ -H "Idempotency-Key: 2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11" \ -H "Content-Type: application/json" \ -d '{ "country": "US", "duration": "30d", "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA" }'{ "id": "ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "status": "completed", "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "country": "US", "product": "any_service", "service": null, "duration": "30d", "quantity": 1, "fulfilledCount": 1, "autoRenew": true, "unitPrice": 1200, "totalPrice": 1200, "currency": "USD", "failure": null, "numbers": [ { "id": "num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "number": "15550100002", "country": "US", "product": "any_service", "service": null, "status": "active", "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "orderId": "ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "nickname": "Support line", "startsAt": "2026-10-07T11:04:31.000Z", "endsAt": "2026-11-06T11:04:31.000Z", "autoRenew": true, "renewDuration": "30d", "unitPrice": 1200, "customerPrice": null, "paidTotal": 1200, "messageCount": 3, "createdAt": "2026-10-07T11:04:31.000Z" } ], "createdAt": "2026-10-07T11:04:31.000Z", "updatedAt": "2026-10-07T11:04:31.000Z"}