Twilio numbers

Twilio numbers are virtual numbers you rent and keep until you release them, unlike Hero SMS numbers, which last minutes. Each is billed monthly by Twilio.

Renting a number attaches it to your project and points its SMS webhook at clearance.rest, so incoming SMS reach GET /sms/wait with no setup on your side.

Find a number

List the countries where numbers can be rented:

curl https://api.clearance.rest/numbers/providers/twilio/countries \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY"

Then search a country:

curl

curl "https://api.clearance.rest/numbers/providers/twilio/availables?country=US&sms=true&voice=true" \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY"

Node.js

const { numbers } = await clearanceRest.numbers.availables({ country: 'US', sms: true });

PHP

$numbers = $client->numbers->availables(country: 'US', sms: true)['numbers'];

Parameter	Default
country (required)		ISO 3166-1 alpha-2 code, for example US, GB, TR.
sms	true	Only numbers that can receive SMS.
mms	false	Only numbers that can receive MMS.
voice	false	Only numbers that can take voice calls.
type	Local	Local, Mobile, National or TollFree.

Each result has a price, which is the monthly rental price for that country and type. Twilio does not price numbers individually, so it is the same for every number in the list. It is null when Twilio has no price for that combination.

Rent

Pass the phoneNumber from the search. Send phone_number for one number, or phone_numbers for several.

curl

curl -X POST https://api.clearance.rest/numbers/providers/twilio/rent \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "phone_numbers": ["+14155550100", "+14155550101"] }'

Node.js

const result = await clearanceRest.numbers.rent({
  provider: 'twilio',
  phoneNumbers: ['+14155550100', '+14155550101'],
});

PHP

$result = $client->numbers->rent(provider: 'twilio', phoneNumbers: ['+14155550100', '+14155550101']);

The response shape follows the request:

• phone_number returns { "success": true, "number": { … } }, or a 502 error if the rental failed.
• phone_numbers returns { "success": true, "numbers": [ … ] } with one entry per number. Numbers are rented in parallel and independently, so one failing does not stop the others. Check each entry’s success.

If you send both, phone_numbers wins and phone_number is ignored.

The returned sid is the id you use to release the number. Twilio’s own PN… SID is in providerSid.

Note

capabilities uses lower-case keys (voice, sms, mms, fax) for Twilio numbers, as Twilio returns them.

Release

POST /numbers/release deletes the number from the Twilio account. See Managing numbers.