Monthly numbers

A monthly number is yours until you release it. Use it when the same number must receive SMS over days or weeks, for example an account that sends a code at every login.

Find a number

Monthly numbers are chosen from the numbers that can be rented right now.

curl -G https://api.clearance.rest/numbers/catalog/available \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  --data-urlencode "country=US" --data-urlencode "line_type=local" --data-urlencode "area_code=415"

GET /numbers/catalog/available returns { numbers: [{ phone_number, friendly_name, region, country, capabilities, price }] }. Narrow it with line_type (local, mobile, national or toll_free), area_code, contains (digits the number should contain), and the mms and voice capabilities. Only SMS-capable numbers are listed. GET /numbers/catalog/prices?type=monthly&country=US shows the price for a country and line type.

Rent it

curl

curl -X POST https://api.clearance.rest/numbers/rent \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "type": "monthly", "country": "US", "phone_number": "+14155550100" }'

Node.js

const { item } = await client.numbers.rent({ type: 'monthly', country: 'US', phoneNumber: '+14155550100' });
console.log(item.renews_at);

PHP

$item = $client->numbers->rent(type: 'monthly', country: 'US', phoneNumber: '+14155550100')['item'];

Without phone_number, the first suitable number in the country is rented. line_type defaults to local. The first month is charged immediately and renews_at is one month away. A number that was taken meanwhile fails with 409 number_unavailable; none in stock with 409 no_numbers_available.

Receive SMS

Wait for each SMS with GET /numbers/sms/wait. Every SMS the number receives is charged when it arrives, whether or not anything is waiting for it. To be told as they arrive, subscribe to the opt-in number.sms_received webhook event.

Renewal

The number renews every month on the day it was rented. The renewal is charged from the team balance.

• If the balance is short, the number is released immediately. Its status becomes RELEASED with released_reason: "renewal_failed", and a number.renewal_failed event is sent:

  {
    "type": "number.renewal_failed",
    "data": { "number": { }, "reason": "insufficient_balance", "required": 1.3, "balance": 0.4 }
  }

  reason is insufficient_balance or spend_limit_exceeded. A renewal that a spend limit blocks is retried for up to 3 days before the number is released.

• 3 days before a renewal the balance cannot cover, the team’s owners receive an email.

Keep the balance above the upcoming renewals to avoid losing the number.

Release

POST /numbers/items/{id}/release gives the number up. It stops renewing and cannot be recovered. The month you already paid for is not refunded.