Inbound Phone Numbers

The /phone_numbers resource represents phone numbers that are either purchased from XBP or ported from a service provider to XBP.

GET /phone_numbers

Parameters

Name Type Description
area_code integer If area_code is passed only numbers with the matching code are returned.
phone_type string Filter number based on their type, possible values are local and toll-free

Example Request

curl "https://api.xbp.io/phone_numbers" \
     -u API_KEY:

Sample Response

{
  "phone_numbers": [
    {
      "url": "/phone_numbers/+18885551234",
      "number": "+18885551234",
      "friendly_name": "1(888) 555-1234",
      "destination": {
        "type": "Person",
        "id": 1
      },
      "capabilities": {
        "sms": true,
        "voice": true,
        "fax": true
      },
      "phone_type": "toll-free",
      "account": {
        "name": "Awesome Account",
        "id": 1
      },
      "location": {
        "name": "Space",
        "id": 361
      },
      "created_at": "2012-06-02T17:20:03Z",
      "updated_at": "2012-06-02T17:20:03Z"
    },...
  ],
  "pagination": {
    "current_page": 1,
    "limit": 50,
    "size": 10,
    "total_pages": 1,
    "total_records": 10
  }
}

The result is an array of phone numbers, for more information about indivisual phone numbers please visit Get Single Phone Number.

GET /phone_numbers/{phone_number}

Example Request

curl "https://api.xbp.io/phone_numbers/+18885551234" \
     -u API_KEY:

Sample Response

{
  "url": "/phone_numbers/+18885551234",
  "number": "+18885551234",
  "friendly_name": "1(888) 555-1234",
  "destination": {
    "type": "Person",
    "id": 1
  },
  "capabilities": {
    "sms": true,
    "voice": true,
    "fax": true
  },
  "phone_type": "toll-free",
  "account": {
    "name": "Awesome Account",
    "id": 1
  },
  "location": {
    "name": "Space",
    "id": 361
  },
  "created_at": "2012-06-02T17:20:03Z",
  "updated_at": "2012-06-02T17:20:03Z"
}

Phone Number Properties

Name Description
url The url of the phone number
number The phone number
friendly_name A human readable descriptive text for this phone number. By default, the friendly_name is a nicely formatted version of the phone number.
destination

A JSON object representing the destination of the phone number.

capabilities

A set of boolean properties indicating capabilities of this number.

sms SMS Capability

voice Voice Capability

fax Fax Capability

phone_type Type of the number: local or toll-free
account A JSON object representing the the account ID and name that the phone belongs to
location A JSON object representing the the location ID and name that the phone belongs to
created_at The date that this resource was created in ISO 8601 format.
updated_at The date that this resource was updated in ISO 8601 format.

POST /phone_numbers

PUT /phone_numbers/{phone_number}

Tries to update the incoming phone number's properties, and returns the updated resource representation if successful. The returned response is identical to that returned above when making a GET request. You can provision new and existing numbers through this resource.

Provisioning Parameters

Name Type Description
number string

When provisioning a new number (purchasing), you must pass number parameter to find and provision your desired phone.

You should obtain numbers from making requests to Available Phone Numbers

destination_type string

The type of destination you want this number to go to. Available destinations are:

  • CustomCallFlow
  • SipAccount
  • Ivr
  • Announcement
  • VmBox
  • Group
  • Conference
  • FaxBox
  • Forwarding
  • CallQueue
  • SipEndpoint
  • BusinessHour
destination_id integer The id of the destination
response_type string

If you have set your destination_type as CustomCallFlow, the response_type indicates whether XBP should try to use the stored XML response or fetch the response from a remote server.

Valid values are stored and remote.

Example 1: Purchase a Phone Number

curl -X POST https://api.xbp.io/phone_numbers \
     -u API_KEY:                                    \
     -d phone_number=14081234567

Example 2: Purchase a Number and Provision to a Person

curl -X POST https://api.xbp.io/phone_numbers \
     -u API_KEY:                                    \
     -d phone_number=14081234567                    \
     -d destination_type=Person                     \
     -d destination_id=1

Example 3: Purchase a number and provision it to a stored CustomCallFlow

# here the response is the encoded value of the following XML response
# <?xml version="1.0" encoding="UTF-8"?>
# <Response>
#   <Play>sound_file://110</Play>
# </Response>

curl -X POST https://api.xbp.io/phone_numbers \
     -u API_KEY:                                    \
     -d phone_number=14081234567                    \
     -d response="-d response="%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%3CResponse%3E%3CPlay%3Esound_file%3A%2F%2F110%3C%2FPlay%3E%3C%2FResponse%3E"

Purchase a number and provision to a remote CustomCallFlow

curl -X POST https://api.xbp.io/phone_numbers            \
     -u API_KEY:                                               \
     -d phone_number=14081234567                               \
     -d response_url="http://example.org/awesome-response.xml" \
     -d response_method=POST

Response

The POST and PUT API responses are same as Phone Number Properties.

DELETE /phone_numbers/{phone_number}

Example Delete a Phone Number

curl -X DELETE https://api.xbp.io/phone_numbers/+14085551234 \
     -u API_KEY:                                                   \