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.
Calls
Where it is on offer, set receiveCalls when ordering to have incoming calls transcribed
and added to the number's message list, on the same number.message.received webhook as
texts. There are no outgoing calls or texts, and a number cannot be answered or dialled.
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.
A new number can't be cancelled in its first 5 minutes: the provider holds it until then. Until
that time passes, the number's cancellableFrom says when it can be cancelled, and a cancel
answers 409 cancel_too_soon.