Phone numbers
Rent private numbers that receive SMS, read their messages, and renew or cancel them.
A number is rented for a fixed time. While the rental is active it receives SMS, and every message is available in the dashboard, from the API and on your webhook.
Products
Every number is any_service: it receives SMS from any sender. There is nothing else to choose.
Only United States numbers are on offer for now; see
GET /v1/numbers/options for the countries your
account can order.
Durations
12h, 1d, 7d, 30d, 180d and 365d. Not every provider offers every duration in
every country; GET /v1/numbers/options lists what your account can order.
See prices
curl "https://resellerhq.com/api/v1/numbers/offers?country=US&product=any_service" \
-H "Authorization: Bearer $RHQ_API_KEY"The price you see is the price you pay. It does not change with the provider that fills the order.
Order
An order is a sale to a customer, so customerId is required; see
Buying for a customer for how to create one.
curl -X POST https://resellerhq.com/api/v1/numbers/orders \
-H "Authorization: Bearer $RHQ_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"country":"US","duration":"30d","quantity":1,"autoRenew":false,"customerId":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"}'An order is tried with the cheapest provider first and falls through to the next if that one
cannot fill it. Its status ends as one of:
| Status | Meaning |
|---|---|
completed | Every number was delivered and charged. |
failed | Nothing was delivered and nothing was charged. failure says why. |
provisioning | Paid for, and the provider is still assigning the number. It completes on its own. |
needs_reconciliation | A provider gave no clear answer. The money stays reserved until it is settled, usually within minutes. |
If only part of a multi-number order can be delivered, you are charged for the part that was.
We choose the carrier a number is ordered on; it cannot be asked for. An order that sends
carrier is refused with 400 carrier_not_accepted, and nothing is charged.
Read messages
curl https://resellerhq.com/api/v1/numbers/NUMBER_ID/messages \
-H "Authorization: Bearer $RHQ_API_KEY"For anything time-sensitive, subscribe to number.message.received on a
webhook instead of polling.
Renew
POST /v1/numbers/{id}/renew adds time to the end of the rental and charges your wallet. Set
autoRenew with PATCH /v1/numbers/{id} to have it extended shortly before it ends. If the
wallet cannot cover an automatic renewal you receive number.rental.renewal_failed, and the
number expires on time.
An order records the number as a sale to the customer named on it, at their price. See Buying for a customer.
Cancel
POST /v1/numbers/{id}/cancel refunds a number in full, but only while it has received no
messages and the provider allows it. Otherwise it answers 409 not_cancellable.