Skip to content
clearance.rest

Managing numbers

GET /numbers/list and POST /numbers/release work on every number in your project, whichever provider it came from. There is no provider parameter: the number itself says which one it is.

List

Section titled “List”
curl https://api.clearance.rest/numbers/list \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY"

The response lists every number attached to your project, not only the usable ones. A number that left your project stays in the list and its status says why. Filter on status === "ACTIVE" to get the numbers you can use.

Each number has:

Field
sid The number’s id. Use it with release.
providerSid The provider’s own id: Twilio’s PN… SID, or the Hero SMS activation id. Not present on mobile numbers.
provider twilio, mobile or herosms.
phoneNumber E.164 format.
status, statusReason See below.
assignedAt, endedAt When it was attached to and left your project, in milliseconds since the Unix epoch.
mobile Only on mobile numbers: carrierName, present, lastSeenAt, online, and more.
herosms Only on Hero SMS numbers: serviceCode, operator, cost, expiresAt, and more.

friendlyName is your project’s id, not a label from the provider.

Status

Section titled “Status”
status Meaning
ACTIVE Usable.
OFFLINE Mobile only. No signal from the phone for 30+ minutes, or ever. Does not block delivery.
SIM_REMOVED Mobile only. The SIM is not in the phone.
MOVED The number was attached to another project. The other project is never named.
RELEASED A Twilio number was deleted, or a Hero SMS activation finished or was cancelled.
EXPIRED Hero SMS only. The rental time ran out and the number is about to become RELEASED.
UNASSIGNED Detached from your project, or never attached.

statusReason gives a human-readable explanation for any status other than ACTIVE.

Only ACTIVE numbers (with the SIM present, for mobile) resolve GET /sms/wait.

A number can be ACTIVE in only one project at a time.

Syncing

Section titled “Syncing”

A plain GET /numbers/list only reads. Add sync=true to reconcile with the providers first: it repairs Twilio SMS webhooks, picks up Twilio numbers that are not attached to any project yet, and closes Hero SMS activations that have ended. The response then includes a sync summary. If the sync fails the list is still returned, with sync.error set.

curl "https://api.clearance.rest/numbers/list?sync=true" \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY"

sync=true may attach one unassigned Twilio number to your project, and it touches your provider accounts, so use it deliberately.

Release

Section titled “Release”
curl -X POST https://api.clearance.rest/numbers/release \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "sid": "c1aaeac1-ec52-44e2-b00a-d1350fb6bee6" }'

Send the sid from GET /numbers/list. Twilio’s PN… providerSid is also accepted. What happens depends on the number:

Provider Effect
Twilio The number is deleted from the Twilio account.
Hero SMS The activation is finished if an SMS arrived, or cancelled and refunded if not. Cancellation is refused for about two minutes after renting; retry later.
Mobile Only your project’s attachment is removed. The SIM is not affected.

A number that is not in your project returns 404.