Phone Numbers

To support incoming phone calls for your applications, Sift allows you to purchase phone numbers. When calls are placed to these numbers, the Incoming Connection Callback endpoint associated with the application will receive an HTTP POST request, allowing you to control the call flow.

For an example on registering a phone number to your application, see this guide.

List available phone numbers

List phone numbers available for purchase.

Request

url:https://api.gridspace.com/v0/availablenumbers/:country_code method:GET

country_code is an ISO 3166-1 alpha-2 format country code.

Response

content-type:application/json

Returns a JSON object representing a paginated list of phone numbers available for purchase. See See Paginated Results for more information.

Property	Type	Description
Required Properties
next	string	URL of the next page of results, or null if this is the last page.
previous	string	URL of the previous page of results, or null if this is the first page.
results	list	A list of available phone numbers in the given country. Each number is represented by an E.164-formatted string starting with a ‘+’ and country code.

Example

{
    "previous": null,
    "next": "https://api.gridspace.com/v0/availablenumbers/US?cursor=cE0yMDE2LTA1LTE5KzAxJTNBNDklM0E1MS4xODQ5NjElMkIwMCUzQTAw",
    "results": [
        "+15551231234", "+15553334242", "+15559876543"
    ]
}

List phone numbers

List the details of all phone numbers associated with your account.

Request

url:https://api.gridspace.com/v0/phonenumbers method:GET

Response

content-type:application/json

Returns a JSON object representing a paginated list of phone numbers. See See Paginated Results for more information.

Property	Type	Description
Required Properties
next	string	URL of the next page of results, or null if this is the last page.
previous	string	URL of the previous page of results, or null if this is the first page.
results	list	A list of phone number objects, described below.

Phone Number Object

Property	Type	Description
Required Properties
application_id	string	The id of the Application currently associated with the number.
number	string	The E.164-formatted phone number. Will contain a “+” and country code.

Example

{
    "previous": null,
    "next": "https://api.gridspace.com/v0/phonenumbers?cursor=cE0yMDE2LTA1LTE5KzAxJTNBNDklM0E1MS4xODQ5NjElMkIwMCUzQTAw",
    "results": [
        {
            "number": "+15551231234",
            "application_id": "ec662c60cf704f7f"
        },
        {
            "number": "+15553334242",
            "application_id": "63d1dd7096e64fef"
        }
        {
            "number": "+15559876543",
            "application_id": "1673257cb8274b58"
        }
    ]
}

Purchase a phone number

Purchase a new phone number to accept incoming calls for a given application. To get a list of phone numbers available for purchase, use the List available phone numbers endpoint.

Request

url:https://api.gridspace.com/v0/phonenumbers method:POST

Property	Type	Description
Required Properties
application_id	string	The id of the application to be associated with the new phone number
phone_number	string	The phone number to purchase, in E.164 format, as returned from the List available phone numbers endpoint

Response

Returns an empty response on success and a JSON structure containing the error on failure