Skip to content
clearance.rest

Rent Twilio numbers

POST
/providers/twilio/rent
curl --request POST \
  --url https://api.clearance.rest/numbers/providers/twilio/rent \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "phone_number": "+14155550100" }'

Buys one or more numbers, points their SMS webhook at the service, and attaches them to your project.

Send phone_number to rent one number, or phone_numbers to rent several. If both are sent, phone_numbers wins and phone_number is ignored. Multiple numbers are rented in parallel and independently: one failing does not stop the others.

The response shape follows the request. phone_number returns a single number; phone_numbers returns a numbers array with one result per number.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
phone_number

One number to rent, in E.164 format.

string
phone_numbers

Several numbers to rent, in E.164 format.

Array<string>
Examples
{
  "phone_number": "+14155550100"
}

Responses

Section titled “Responses”

200

Section titled “200”

Rented. The shape depends on which parameter you sent.

Media typeapplication/json
Any of:
object
success
required
boolean
number
required

A freshly rented Twilio number.

object
sid
required

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

string format: uuid
providerSid
required

Twilio’s own PN… SID.

string
phoneNumber
required
string
friendlyName
string
smsUrl
string | null
voiceUrl
string | null
capabilities

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
Examples
{
  "success": true,
  "number": {
    "sid": "c1aaeac1-ec52-44e2-b00a-d1350fb6bee6",
    "providerSid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "phoneNumber": "+14155550100",
    "friendlyName": "(415) 555-0100",
    "smsUrl": "https://api.clearance.rest/numbers/callbacks/twilio/sms",
    "voiceUrl": null,
    "capabilities": {
      "voice": true,
      "sms": true,
      "mms": true,
      "fax": false
    }
  }
}

400

Section titled “400”

Neither phone_number nor phone_numbers was sent.

Media typeapplication/json

Error envelope returned with a non-2xx status.

object
success
required
boolean
error
required

Human-readable error message.

string
Example
{
  "success": false,
  "error": "phone_number veya phone_numbers zorunludur"
}

401

Section titled “401”

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

Media typeapplication/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

Section titled “502”

Renting a single number (phone_number) failed. With phone_numbers, failures are reported per number inside a 200.

Media typeapplication/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"
}