List your numbers

GET

/list

const url = 'https://api.clearance.rest/numbers/list?sync=false';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.clearance.rest/numbers/list?sync=false' \
  --header 'X-API-Key: <X-API-Key>'

Lists every number attached to your project from all three providers, not only the usable ones. A number that left your project stays in the list and its status says why (see the NumberStatus values below). A usable number is one whose status is ACTIVE, so filter on that.

Each number carries a provider field. Mobile numbers add a mobile object and Hero SMS numbers a herosms object. status, statusReason, assignedAt and endedAt are always top-level.

A plain GET never writes anything. With sync=true the service first reconciles your Twilio account and Hero SMS activations, then lists, and adds a sync summary to the response. If the sync fails, the list is still returned and sync.error holds the reason.

Authorizations

ApiKey

Parameters

Query Parameters

sync

boolean

When true, reconcile with the providers before listing. This touches provider accounts, so leave it off unless you need it.

Responses

200

Your numbers.

application/json

object

success

required

boolean

numbers

required

Array<object>

object

sid

required

The number’s id. Use it with POST /release.

string format: uuid

providerSid

The provider’s own id: Twilio’s PN… SID, or Hero SMS’s activation id. Not present on mobile numbers.

string

provider

required

string

Allowed values: twilio mobile herosms

phoneNumber

required

E.164 format.

string

friendlyName

Your project’s id.

string

smsUrl

string | null

voiceUrl

string | null

capabilities

One of:

object
null

What the number can do. Twilio returns these keys lower-case; mobile and Hero SMS numbers report the same keys.

object

voice

boolean

sms

boolean

mms

boolean

fax

boolean

status

required

Where a number stands for your project.

Value	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.
`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.

string

Allowed values: ACTIVE OFFLINE SIM_REMOVED MOVED RELEASED EXPIRED UNASSIGNED

statusReason

Human-readable reason for a non-ACTIVE status.

string | null

assignedAt

When the number was attached to your project, in milliseconds since the Unix epoch.

integer | null

endedAt

When it stopped being attached, in milliseconds since the Unix epoch.

integer | null

expiresAt

Hero SMS only, on the rent response. When the rental ends.

integer

serviceCode

Hero SMS only, on the rent response.

string

operator

Hero SMS only, on the rent response.

string

cost

Hero SMS only, on the rent response.

number

currency

Hero SMS only, on the rent response.

string

mobile

Present on mobile numbers.

object

numberId

string

carrierName

string | null

status

Where a number stands for your project.

Value	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.
`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.

string

Allowed values: ACTIVE OFFLINE SIM_REMOVED MOVED RELEASED EXPIRED UNASSIGNED

statusReason

string | null

present

Whether the SIM is in the phone.

boolean

verifiedAt

integer | null

assignedAt

integer | null

lastSeenAt

Last signal from the phone, in milliseconds since the Unix epoch.

integer | null

online

boolean

herosms

Present on Hero SMS numbers in GET /list.

object

activationId

string

serviceCode

string

operator

string | null

cost

number

currency

string

expiresAt

integer | null

firstSmsAt

integer | null

sync

Only present when sync=true.

object

checked

integer

fixed

Array<string>

imported

integer

released

integer

error

Present when the sync itself failed.

string

Examples

A Twilio number

{
  "success": true,
  "numbers": [
    {
      "sid": "c1aaeac1-ec52-44e2-b00a-d1350fb6bee6",
      "providerSid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "provider": "twilio",
      "phoneNumber": "+14155550100",
      "friendlyName": "my-project",
      "smsUrl": "https://api.clearance.rest/numbers/callbacks/twilio/sms",
      "voiceUrl": null,
      "capabilities": {
        "voice": true,
        "sms": true,
        "mms": true,
        "fax": false
      },
      "status": "ACTIVE",
      "statusReason": null,
      "assignedAt": 1785107162000,
      "endedAt": null
    }
  ]
}

A mobile number that later moved to another project

{
  "success": true,
  "numbers": [
    {
      "sid": "9e2f0c1a-6a3d-4b6f-8c1e-2d7b9a1f0e55",
      "provider": "mobile",
      "phoneNumber": "+905321119999",
      "friendlyName": "my-project",
      "smsUrl": null,
      "voiceUrl": null,
      "capabilities": {
        "voice": false,
        "sms": true,
        "mms": false,
        "fax": false
      },
      "status": "MOVED",
      "statusReason": "başka bir projeye atandı",
      "assignedAt": 1785000000000,
      "endedAt": 1785100000000,
      "mobile": {
        "numberId": "9e2f0c1a-6a3d-4b6f-8c1e-2d7b9a1f0e55",
        "carrierName": "Turkcell",
        "status": "MOVED",
        "statusReason": "başka bir projeye atandı",
        "present": true,
        "verifiedAt": 1785000000000,
        "assignedAt": 1785000000000,
        "lastSeenAt": 1785100000000,
        "online": false
      }
    }
  ]
}

401

The X-API-Key header is missing or invalid.

application/json

Error envelope returned with a non-2xx status.

object

success

required

boolean

error

required

Human-readable error message.

string

Example

{
  "success": false,
  "error": "geçersiz API anahtarı"
}