Skip to main content

Purchasing dedicated numbers with Numbers API

  • Updated

By using a dedicated number for your communications with customers, your messages will come from a single number, rather than a rotary pool of numbers. Dedicated numbers can be a powerful tool for two-way messaging, enabling you to segment communications with your customers by department, workflow, or interaction. With the Numbers API, you can build the facility to provision these number right into your software. This will enable you to set up and automate business processes for number provisioning. In this developer guide, we’re going to show you how to segment communications using the Numbers API.

Searching for a number

The first thing we need to do is search for the type of number we want. We can search on location, service type (eg, SMS, MMS or TTS - a number with Text to Speech available) and even for numbers that include a subset of matching numbers. We’re going to search for a number that is an Australian number capable of SMS. Use the Postman collection and put in your credentials using the instructions here. Then for the getNumbers call, update the parameters to include the following:  When we hit send it comes back with a list of numbers:

{
 "data": [
    {
      "id": "06edf0e7-5856-43b7-b1f7-ddd1ba5a7431",
      "phone_number": "+61439742682",
      "country": "AU",
      "type": "MOBILE",
      "classification": "BRONZE",
      "available_after": "2019-08-06T23:56:01.263Z",
      "capabilities": [
        "SMS"
       ]
     },
     {
      "id": "0707e86b-efa2-45f7-a5aa-9ac8cb84eb15",
      "phone_number": "+61438824240",
      "country": "AU",
      "type": "MOBILE",
      "classification": "BRONZE",
      "available_after": "2019-08-06T23:57:15.213Z",
      "capabilities": [
          "SMS"
       ]
      },
      {
        "id": "073fb6bd-f054-4644-aada-8fb204145d77",
        "phone_number": "+61438851616",
        "country": "AU",
        "type": "MOBILE",
        "classification": "BRONZE",
        "available_after": "2019-08-06T23:56:58.186Z",
        "capabilities": [
          "SMS"
          ]
      }
     ],
     "pagination": {
        "page_size": 3,
        "next_token": "074b8bfd-f420-4168-a9f0-530cf1ba2523"
      }
 }

It also shows pagination data. To get the next set of numbers, we take the token from this pagination data and update the parameters like this: In this set of results, we have identified a number that we like and within our price range.

{
 "id": "073fb6bd-f054-4644-aada-8fb204145d77",
 "phone_number": "+61438851616",
 "country": "AU",
 "type": "MOBILE",
 "classification": "BRONZE",
 "available_after": "2019-08-06T23:56:58.186Z",
 "capabilities": [
    "SMS"
  ]
 },

For information on the classification system we use, please see the documentation here. You will also find indicative pricing information on the web portal.

Assigning/purchasing a number

Now that we have the ID of the number to purchase, we can create an assignment. Using the createAssignment endpoint in the Postman collection, we paste the number_id into the path variable: If this works successfully we will get an assignment id and the number_id returned to us like this:

{
 "id": "b06387c0-f4d9-4333-8657-c819bede79c3",
 "number_id": "073fb6bd-f054-4644-aada-8fb204145d77"
 }

We’ve assigned the number, but realised that the assignment has no details about who has been assigned. Ideally, we should have set up labelling and metadata to make life easier for when we are doing reporting and so on. Not to worry, we can do a PATCH request to update this now. Using the updateAssignment endpoint in the collection, we passed the number_id (not the assignment ID) into the parameter, and then update the JSON body like this:

{
 "label": "Representative-Fred",
 "metadata": {
    "State": "Vic",
    "Region": "SE"
  }
 }

Then we get this result back, telling us successfully updated assignment data:

{
 "metadata": {
    "Region": "SE",
    "State": "Vic"
 },
 "label": "HouseElf-Fred",
 "id": "b06387c0-f4d9-4333-8657-c819bede79c3",
 "number_id": "073fb6bd-f054-4644-aada-8fb204145d77"
 }

With the Numbers API, we can also delete assignments, view assignment details and see all assigned numbers for our account. This functionality can be built into any software to automate assignment, but we can also receive messages to that number at any time. Given this, we can now use this to set up webhooks to handle inbound messages and send out all our messages from the correct number to ensure continuity of conversations.

Related articles