Rent Hero SMS numbers

POST

/providers/herosms/rent

const url = 'https://api.clearance.rest/numbers/providers/herosms/rent';
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'},
  body: '{"service":"tg","country":6}'
};

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

curl --request POST \
  --url https://api.clearance.rest/numbers/providers/herosms/rent \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "service": "tg", "country": 6 }'

Opens one or more activations: gets a temporary number from Hero SMS and attaches it to your project. The rental lasts about 20 minutes. After that the number can no longer receive SMS and becomes RELEASED, though SMS it already received stay readable through GET /sms/wait.

Send quantity to rent several (1 to 20); the response is then always a numbers array with one result per activation, and one failing does not stop the others. Without quantity you get a single number.

Leave max_price out unless you need a hard budget cap. Without it, the service retries with a growing price ceiling until stock is found. Sending it disables those retries and tries exactly once.

Authorizations

ApiKey

Request Body^required

application/json

object

service

required

Service code, from GET /providers/herosms/services.

string

country

required

Hero SMS numeric country id.

integer

quantity

How many numbers to rent. Changes the response to numbers[].

integer

>= 1 <= 20

max_price

Hard upper price per activation. Disables automatic price escalation.

number

operator

Restrict to one operator, from GET /providers/herosms/operators.

string

phone_exception

Comma-separated number prefixes to exclude (at most 20).

string

Example

{
  "service": "tg",
  "country": 6
}

Responses

200

Rented. The shape depends on whether quantity was sent.

application/json

Any of:

object
object

object

success

required

boolean

number

required

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

object

success

required

boolean

numbers

required

Array<object>

object

success

required

boolean

number

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

error

string

Examples

{
  "success": true,
  "number": {
    "sid": "c1aaeac1-ec52-44e2-b00a-d1350fb6bee6",
    "providerSid": "1234567890",
    "provider": "herosms",
    "phoneNumber": "+6281234567890",
    "friendlyName": "my-project",
    "smsUrl": null,
    "voiceUrl": null,
    "capabilities": {
      "voice": false,
      "sms": true,
      "mms": false,
      "fax": false
    },
    "status": "ACTIVE",
    "statusReason": null,
    "expiresAt": 1785108360000,
    "serviceCode": "tg",
    "operator": "telkomsel",
    "cost": 0.2,
    "currency": "840"
  }
}

{
  "success": true,
  "numbers": [
    {
      "success": true,
      "number": {
        "sid": "c1aaeac1-ec52-44e2-b00a-d1350fb6bee6",
        "providerSid": "1234567890",
        "provider": "herosms",
        "phoneNumber": "+6281234567890",
        "status": "ACTIVE"
      }
    },
    {
      "success": false,
      "error": "hero-sms NO_NUMBERS"
    }
  ]
}

400

service or country is missing.

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": "invalid json body"
}

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ı"
}

502

Renting a single number (no quantity) failed. With quantity, failures are reported per activation inside a 200.

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": "invalid json body"
}

Rent Hero SMS numbers

Authorizations

Request Bodyrequired

Example

Responses

200

Examples

400

Example

401

Example

502

Example

Request Body^required