AVANSER stocks are managed on a per demand basis, this means AVANSER will order a specific amount of numbers in specific areas based on the demand.

Of course, it is possible to request specific numbers from AVANSER support when needed, but if you are planning to automate a provisioning system you may want to look at two private stock options that may better suit your needs.

Private Stock Model

Having a private stock allows you to manage your private number selection based on your business requirements forecast.

Private stock is not a restrictive option, rather you can choose to have private stock for a specific number class (Eg. Australia, Mobile) but use AVANSER public stock for all other Countries/Number Classes. 

Private stock can be configured with two options; Private and Strict Private. 

If your demand for numbers is considerably high, AVANSER suggests switching to Private stock.

Please note, private stock has a different pricing model; get in contact with your  AVANSER Account Manager for more details.

Using the Telco API

AVANSER’s Telco API is designed to ease interaction with your stock and provide a flexible JSON API.

The API provides access to a request based number provisioning model; each request change is reported using a HTTP GET callback mechanism as well as a per-call event model that allows call reporting, making it easier to automate actions on your side.

Each request carries the initial configuration for the number. If a number matching the provided criteria is found in the client’s stock or the public stock, the number is immediately activated and ready to be used within minutes. The request list and request status is available with the API, providing real time request monitoring.

The AVANSER Telco API unifies several technologies already available to the AVANSER support team such as target number changes, email notification updates, per-call HTTP callbacks (if supported by the number) and SMS HTTP GET forwards to desired addresses.

You can configure your numbers and how they interact with you or your customers. You also have three different ways to report your calls back to you or your customers -  sms, email and HTTP callback.

The Telco API gives you access to an HTML templating system that allows you to customise your customer's experience.

Changes to your services can be performed in complete autonomy.

The Telco API can help you manage your customers’ numbers in a more clear manner. Using an account based system, your clients can simply sign up and AVANSER will do all the work while you directly manage your customers’ numbers, making the Telco API an essential tool to optimise your workflow and let you focus only on your customers.

The contents of this document are intended for explame purposes only, for a extensive and updated documentation please refer to to the online documentation available at: http://docs.avansertapi.apiary.io

Road Map and future changes

AVANSER’s Telco API is under active development, the current road map includes (but is not limited to):

Development tools

When interacting with an API it is important to use the right tools. To that end we have ensured our API documentation is available in API Blueprint format in conjunction with PostMan, allowing you to have documentation and a test environment on your desktop.

PostMan supports Windows, Linux and MacOS and offers multiple “code convert” options to ease integration of the API with your prefered technology. 

AVANSER offers a sandbox environment to help you through your first steps with the Telco API. The sandbox environment address is available in the documentation. Apiary offers the same advanced features of PostMan, minus the local storage to cache the requests and replies.

We suggest you create your own Telco API collection for PostMan. Download the blueprint from apiary and we will keep you informed about changes.

We can also provide a PostMan collection if needed. Please submit us a request.

References

1. Telco API, blueprint

2. API Blueprint outline

3. PostMan

4. Apiary - Postman converter tool

Workflow examples

These examples are designed to give you a quick look into the potential of the Telco API.

The examples use the cURL command line interface but you can use your desired tools.

Please note, the “dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm” authentication token is a sample one. To know more about how to generate a http basic authorisation token, you can read the Wikipedia article here.

Search your inventory stock

Perform a search request to your inventory, the response depends on number availability and the numbers currently in stock.

Note: all cURL commands are single lines.

Request available numbers for Sydney

curl -X GET 'https://tapi.avanser.com/v1/numbers?country=AU&szu=sydney'  - H 'authorization: Basic dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm’

Response Reply

{

    "@transaction": {

        "id": "9b9ee53663816df8eb66d694383f3ef9e2ee8ddf",

        "account-id": "7xxx",

        "request": {

            "api-version": "v1",

            "method": "GET",

            "path": "/v1/numbers?country=AU&szu=sydney",

            "time": "2017-06-14T10:19:24+10:00",

            "ms": "0.711"

        }

    },

    "response": {

        "61280740802": {

            "country": "AU", "region": "NSW: Sydney", "type": "GEO",

            "national": "0280740802", "calling_code": "+61", "pool": "private"

        },

        "61280740805": {

            "country": "AU","region": "NSW: Sydney","type": "GEO",

            "national": "0280740805","calling_code": "+61","pool": "private"

        }

    }

}

Request a new service

When creating a new service there are many options available. The following examples show how to create a service with the Call Recording feature enabled.

When creating or updating a Service Number you can pick from your available numbers using the following criteria:

• by Location

• by Coordinates

• by Matching prefix

• by Number Type

• by SZU (Australia Only)

When creating or updating a Service Number you can also configure:

• Missed Call Notification

• Upon call completion a Mail and/or SMS will be sent to the desired recipients.

• Call-URI Notifications

• Upon call completion selected URI will be called with all call data information.

• SMSForward-URI

• (Mobile only) Upon SMS received selected URI will be called with all SMS information.

• Customise

• Call Greeting

• Call Whisper

• VoiceMail greeting

Request a new number from the inventory

Submit Request

curl -X POST https://tapi.avanser.com/v1/requests - H 'authorization: Basic dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm' \

 -d '{

 "name": "service #1",

 "custom_id": "custom_id #1",

 "custom_group": "custom_group #1",

 "service_number": {

 "country": "AU",

 "search_type": "number",

 "number": "61280740801"

 },

 "service": {

 "type": "transfer",

 "answer_point": "61401603859",

 "answer_point_name": "answerpoint #1",

 "record_call": true

 },

 "call_uri": "http://desired.uri.to/debug.php?call_uri=service1",

 "callback_uri": "http://desired.uri.to/debug.php?callback_uri=service1"

}'

Acknowledgment Reply

{

    "@transaction": {

        "id": "a852650ae8689da0b0632f0c6c276e919d7a7b6e",

        "account-id": "7xxx",

        "request": {

            "api-version": "v1",

            "method": "POST",

            "path": "/v1/requests",

            "time": "2017-06-14T10:29:49+10:00",

            "ms": "0.622"

        }

    },

    "response": {

        "request_id": "a852650ae8689da0b0632f0c6c276e919d7a7b6e",

        "message": "Success",

        "code": 200,

        "service_number": "61280740801"

    }

}

When the process is complete you will receive a HTTP Post with a JSON Body.

Confirmation Callback
Received on specified URI-endpoint
{

  "account_id": "7xxx",

  "request_id": "3b9b2298b519cef79c6c1638f4d54ddae19ba034",

  "custom_id": "custom_id #1",

  "custom_group": "custom_group #1",

  "service_number": "61280740801",

  "answer_point": "61401603859",

  "message": "Request completed successfully",

  "status": "completed"

}

Creating a new number using the automated search

You can use the automated search functionality to perform a search and automatically configure the number as specified upon a successful search.

TIP: “number” search_type allows you to pass your answer point as a number field; this way our system will try to find the closest match to the answer point.
Please note, search is performed according to client's inventory stock options.

Submit Request

curl -X POST https://tapi.avanser.com/v1/requests - H 'authorization: Basic dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm' \

 -d '{

 "name": "service #3",

 "custom_id": "custom_id #3",

 "custom_group": "custom_group #3",

 "service_number": {

  "country": "AU",

  "search_type": "szu",

  "szu": "sydney"

 },

 "service": {

 "type": "transfer",

 "answer_point": "61401603859",

 "answer_point_name": "answerpoint #3",

 "record_call": true

 },

 "call_uri": "http://desired.uri.to/debug.php?call_uri=service1",

 "callback_uri": "http://desired.uri.to/debug.php?callback_uri=service1"

}'

Acknowledgment Reply
{

    "@transaction": {

        "id": "cebaa4ba54ecacb5054e2a4de54842e5a70ec0eb",

        "account-id": "7xxx",

        "request": {

            "api-version": "v1",

            "method": "POST",

            "path": "/v1/requests",

            "time": "2017-06-14T10:37:56+10:00",

            "ms": "0.587"

        }

    },

    "response": {

        "request_id": "cebaa4ba54ecacb5054e2a4de54842e5a70ec0eb",

        "message": "Success",

        "code": 200,

        "service_number": "61280740805"

    }

}

Confirmation Callback
Received on specified URI-endpoint

{

  "account_id": "7xxx",

  "request_id": "cebaa4ba54ecacb5054e2a4de54842e5a70ec0eb",

  "custom_id": "custom_id #3",

  "custom_group": "custom_group #3",

  "service_number": "61280740805",

  "answer_point": "61401603859",

  "message": "Request completed successfully",

  "status": "completed"

}

Submit a service update

The Telco API allows you to modify each service previously created as shown in this example.

Submit Request

curl -X POST https://tapi.avanser.com/v1/services/61280740801 - H 'authorization: Basic dGFwaV9hY2Nlc3M6bzdhaG9XUElURno0Snhm' \

  -d '{

  "service": {

    "answer_point": "61132307"

  },

  "call_uri": "https://desired.uri.to/debug.php?call_uri=service1&new-call-uri=1",

  "callback_uri": "https://desired.uri.to/debug.php?callback_uri=service1&updated=true"

}'

Acknowledgment Reply
{

    "@transaction": {

        "id": "c05977971a1d9fbe8eaa3a410f63d02ea5375c04",

        "account-id": "7xxx",

        "request": {

            "api-version": "v1",

            "method": "POST",

            "path": "/v1/services/61280740801",

            "time": "2017-06-14T10:56:42+10:00",

            "ms": "0.166"

        }

    },

    "response": {

        "request_id": "c05977971a1d9fbe8eaa3a410f63d02ea5375c04",

        "message": "Success",

        "code": 200,

        "service_number": "61280740801"

    }

}

Confirmation Callback
Received on specified URI-endpoint
{

  "account_id": "7xxx",

  "request_id": "43b1fbeec99581407cfe31908930c43fec066d3c",

  "custom_id": "",

  "custom_group": "",

  "service_number": "61280740801",

  "answer_point": "6113008786264",

  "message": "Request completed successfully",

  "status": "completed"

}

Call-URI reports

Upon call completion all information about the call is sent to the selected “Call-URI”. This feature is configured upon service creation and the desired URI can be updated with an “Update” request.

What follows is an example: