Eligibility Resource

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.

Expand image

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.

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.

The following table provides all the properties that may be returned by the resource.

The following example responses are provided for your reference.

The following table enumerates and describes all the possible error codes within the response body of an HTTP 400: Bad Request.

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.

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.

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.

The following table enumerates and describes all the possible error codes within the response body of an HTTP 400: Bad Request.

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.

The following table provides all the properties that may be returned by the resource.

The following example responses are provided for your reference.