Eligibility Resource
Twilio's Eligibility API allows you to determine if the non-Twilio phone numbers already in your possession can be hosted with Twilio. It's often possible to use your existing phone numbers with Twilio's Messaging Services without changing the voice provider by hosting the messaging capability of those numbers with Twilio.
Determining a number's eligibility is the first step of the hosting process. Using the API, you can check the eligibility of a number or group of numbers before starting the hosting process. If a number cannot be hosted by Twilio, the API will provide a reason and suggest potential next steps.
All URLs referenced in the API documentation have the following base:
https://numbers.twilio.com/v1/HostedNumber/Eligibility
The API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
HTTP requests to the API are protected with HTTP Basic authentication. To learn more about how Twilio handles authentication, please refer to our security documentation.
In short, you will use your Twilio Account SID as the username and your Auth Token as the password for HTTP Basic authentication with Twilio.
You can find your Account SID and Auth Token in the Console.
To learn more about authentication and interaction with the Twilio REST API, check out our documentation for requests to the API and Twilio's response.
Resource URL: https://numbers.twilio.com/v1/HostedNumber/Eligibility
To check a single phone number's eligibility, make a POST request to this resource.
See the following code sample for a complete curl request. See the request properties table for all the properties available on this resource.
1curl --location --request POST 'https://numbers.twilio.com/v1/HostedNumber/Eligibility' \2-u "Account_SID:Auth_Token" \3--header 'Content-Type: application/json' \4--data-raw '{5"friendly_name": "My first eligibility check",6"phone_numbers": [7{"phone_number": "+13175787XXX", "hosting_account_sid": "AC264f0af1e323b9a38e513c433828dXXX"}8]9}'10
The resource accepts an array of one object called phone_numbers. The object must contain a phone_number in E.164 format to check for eligibility. A phone_numbers object may also contain a Twilio Account SID (hosting_account_sid) belonging to the Twilio Account where you want to host the phone number. If a SID is not provided, the account used to make the request will be used as the hosting Twilio Account. This resource also accepts an optional friendly_name property, which allows you to assign a human-readable reference to the eligibility request.
| Parameter | Required | Field Type | Validation | Description |
|---|---|---|---|---|
phone_numbers | Yes. | Array | Size must equal 1. | An array of one object containing fields:
|
friendly_name | No. | String | Name of the eligibility check. |
The following table provides all the properties that may be returned by the resource.
| Parameter | Description | Possible return values |
|---|---|---|
phone_number | Phone number that was checked for hosting eligibility. | |
hosting_account_sid | Twilio's Account or Subaccount SID where the number would be hosted. | |
eligibility_status | The number's eligibility to be hosted with Twilio. | |
eligibility_sub_status | Additional information about why a number cannot be hosted with Twilio. | |
ineligibility_reason | The primary reason the number cannot be hosted with Twilio. | |
next_step | Action that customers can take based on the eligibility result. | |
phone_number_type | The phone number's type. | |
iso_country_code | The country to which the number belongs. |
The following example responses are provided for your reference.
1"results": [2{3"phone_number": "+1XXXXXXXXXX",4"next_step": "CREATE_HOSTED_NUMBER_ORDER",5"phone_number_type": "TOLLFREE",6"eligibility_sub_status": "ELIGIBLE",7"eligibility_status": "ELIGIBLE",8"hosting_account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",9"ineligibility_reason": "None",10"iso_country_code": "USA"11}12]
1"results": [2{3"phone_number": "+493333344444544XXX",4"next_step": "EDIT_INELIGIBLE_NUMBER_AND_RUN_ELIGIBILITY_CHECK_AGAIN",5"phone_number_type": "UNKNOWN",6"eligibility_sub_status": "NUMBER_FORMAT_INELIGIBLE",7"eligibility_status": "INELIGIBLE",8"hosting_account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",9"ineligibility_reason": "NUMBER_FORMAT_INELIGIBLE",10"iso_country_code": null11}12]13
1"results": [2{3"phone_number": "+1XXXXXXXXXX",4"next_step": "NUMBER_TYPE_CANNOT_BE_HOSTED",5"phone_number_type": "MOBILE",6"eligibility_sub_status": "NUMBER_TYPE_INELIGIBLE",7"eligibility_status": "INELIGIBLE",8"hosting_account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",9"ineligibility_reason": "NUMBER_TYPE_INELIGIBLE",10"iso_country_code": "US"11}12]13
The following table enumerates and describes all the possible error codes within the response body of an HTTP 400: Bad Request.
| Status Code | Error Message | Description |
|---|---|---|
21470 | Account SID is required | Account SID is missing or invalid |
21470 | Invalid Account SID | Invalid Account SID |
21471 | Account not found | Valid Account SID, but account not found |
22102 | Phone Number is required | The phone_number field is missing |
22102 | Invalid Phone Number | Phone number is invalid |
22116 | Invalid Friendly Name | Friendly name is empty or exceeds 128 characters |
22124 | Phone number(s) are required | The phone_numbers field is missing |
22125 | Phone number(s) cannot exceed the maximum limit allowed | Number of phone numbers cannot exceed one |
Resource URL: https://numbers.twilio.com/v1/HostedNumber/Eligibility/Bulk
To check a set of up to 1,000 phone numbers' eligibility, make a POST request to this resource. After the bulk eligibility check is created, the next step is to get the results for the bulk request.
See the following code sample for a complete curl request. See the request properties table for all the properties available on this resource.
1curl --location --request POST 'https://numbers.twilio.com/v1/HostedNumber/Eligibility/Bulk' \2-u "Account_SID:Auth_Token" \3--header 'Content-Type: application/json' \4--data-raw '{5"friendly_name": "My first eligibility check",6"phone_numbers": [7{8"phone_number": "+13175787XXX",9"hosting_account_sid": "AC264f0af1e323b9a38e513c433828dXXX"10},11{12"phone_number": "+15017122XXX",13"hosting_account_sid": "AC264f0af1e323b9a38e513c433828dXXX"14},15{16"phone_number": "+18003482XXX"17}18]19}'20
The resource accepts an array of objects called phone_numbers. Each object must contain a phone_number in E.164 format to check for eligibility. A phone_numbers object may also contain a Twilio Account SID (hosting_account_sid) belonging to the Twilio Account where you want to host the phone numbers. If a SID is not provided, the account used to make the request will be used as the hosting Twilio Account. This resource also accepts an optional friendly_name property, which allows you to assign a human-readable reference to the eligibility request.
| Parameter | Required | Field Type | Validation | Description |
|---|---|---|---|---|
phone_numbers | Yes. | Array | 1 ≤ size ≤ 1000 | An array of one to 1,000 objects containing fields:
|
friendly_name | Yes. | String | Name of the eligibility check. |
A POST request to the above resource will return a status and request_id, among other properties. Processing a bulk request may require some time depending on the quantity of numbers to be checked. Once the status of your request is "SUCCESSFUL", you can use the request_id to retrieve the eligibility results for the numbers sent in your bulk request as described in the Get results for a bulk request section of this page.
| Name | Type | Description |
|---|---|---|
status | String | This is the status of the bulk eligibility check request. Return values include: SUCCESSFUL, QUEUED, PROCESSING). |
date_completed | date_time<ISO8601> | Date the request was completed. It will be null until the eligibility check is completed. |
url | URL | This is the URL that you can use to GET the results of the request. |
friendly_name | String | This is the string that you assigned as a friendly name for describing the eligibility check request. |
results | Object[] | The result set that contains the eligibility check response for each requested number. It will be empty until the eligibility check is completed. |
request_id | SID<EC> | The SID of the bulk eligibility check. |
date_created | date_time<ISO8601> | Date the request was created. |
1{2"status": "QUEUED",3"date_completed": null,4"url": "https://numbers.twilio.com/v1/HostedNumber/Eligibility/Bulk/Request_ID",5"friendly_name": "friendly_name",6"results": [],7"request_id": "Request_ID",8"date_created": "2024-03-21T22:06:24Z"9}10
The following table enumerates and describes all the possible error codes within the response body of an HTTP 400: Bad Request.
| Status Code | Error Message | Description |
|---|---|---|
21470 | Account SID is required | Account SID is missing or invalid |
21470 | Invalid Account SID | Invalid Account SID |
21471 | Account not found | Valid Account SID, but account not found |
22102 | Phone Number is required | The phone_number field is missing |
22102 | Invalid Phone Number | Phone number is invalid |
22116 | Invalid Friendly Name | Friendly name is empty or exceeds 128 characters |
22124 | Phone number(s) are required | The phone_numbers field is missing |
22125 | Phone number(s) cannot exceed the maximum limit allowed | Number of phone numbers cannot exceed 1000 |
22127 | Friendly Name is required | Friendly name is missing |
Resource URL: https://numbers.twilio.com/v1/HostedNumber/Eligibility/Bulk/{request_id}
To retrieve the eligibility results for the phone numbers passed to the Bulk Eligibility resource, make a GET request to this resource with the request_id returned by your initial POST request to the Bulk Eligibility resource. Once the status of your initial POST request is "SUCCESSFUL", you will see the eligibility status for each phone number in the response from this resource. Descriptions for each eligibility response property are provided in the below response properties table.
1curl --location --request GET 'https://numbers.twilio.com/v1/HostedNumber/Eligibility/Bulk/ECXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \2-u "Account_SID:Auth_Token" \3--header 'Content-Type: application/json' \4
The following table provides all the properties that may be returned by the resource.
| Parameter | Description | Possible return values |
|---|---|---|
phone_number | Phone number that was checked for hosting eligibility. | |
hosting_account_sid | Twilio's Account or Subaccount SID where the number would be hosted. | |
eligibility_status | The number's eligibility to be hosted with Twilio. | |
eligibility_sub_status | Additional information about why a number cannot be hosted with Twilio. | |
ineligibility_reason | The primary reason the number cannot be hosted with Twilio. | |
next_step | Action that customers can take based on the eligibility result. | |
phone_number_type | The phone number's type. | |
iso_country_code | The country to which the number belongs. |
The following example responses are provided for your reference.
1{2"status": "SUCCESSFUL",3"date_completed": "2024-03-21T22:07:20Z",4"url": "https://numbers.twilio.com/v1/HostedNumber/Eligibility/Bulk/Request_ID",5"friendly_name": "friendly_name",6"results": [7{8"phone_number": "+1XXXXXXXXXX",9"next_step": "NUMBER_TYPE_CANNOT_BE_HOSTED",10"phone_number_type": "MOBILE",11"eligibility_sub_status": "NUMBER_TYPE_INELIGIBLE",12"eligibility_status": "INELIGIBLE",13"hosting_account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",14"ineligibility_reason": "NUMBER_TYPE_INELIGIBLE",15"iso_country_code": "US"16},17{18"phone_number": "+493333344444544XXX",19"next_step": "EDIT_INELIGIBLE_NUMBER_AND_RUN_ELIGIBILITY_CHECK_AGAIN",20"phone_number_type": "UNKNOWN",21"eligibility_sub_status": "NUMBER_FORMAT_INELIGIBLE",22"eligibility_status": "INELIGIBLE",23"hosting_account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",24"ineligibility_reason": "NUMBER_FORMAT_INELIGIBLE",25"iso_country_code": null26}27],28"request_id": "Request_ID",29"date_created": "2024-03-21T22:06:24Z"30}
1{2"status": "PROCESSING",3"date_completed": null,4"url": "https://numbers.twilio.com/v1/HostedNumber/Eligibility/Bulk/Request_ID",5"friendly_name": "friendly_name",6"results": [7{8"phone_number": "+1XXXXXXXXXX",9"next_step": "NUMBER_TYPE_CANNOT_BE_HOSTED",10"phone_number_type": "MOBILE",11"eligibility_sub_status": "NUMBER_TYPE_INELIGIBLE",12"eligibility_status": "INELIGIBLE",13"hosting_account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",14"ineligibility_reason": "NUMBER_TYPE_INELIGIBLE",15"iso_country_code": "US"16},17{18"phone_number": "+493333344444544XXX",19"next_step": "EDIT_INELIGIBLE_NUMBER_AND_RUN_ELIGIBILITY_CHECK_AGAIN",20"phone_number_type": "UNKNOWN",21"eligibility_sub_status": "NUMBER_FORMAT_INELIGIBLE",22"eligibility_status": "INELIGIBLE",23"hosting_account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",24"ineligibility_reason": "NUMBER_FORMAT_INELIGIBLE",25"iso_country_code": null26}27],28"request_id": "Request_ID",29"date_created": "2024-03-21T22:06:24Z"30}31