Version 2 Numbers

Introduction

This section provides functionality relating to phone numbers.

Search For Available Numbers

Search for available numbers using filters.

Request:

GET /config/v2/numbers/available

GET Params

Filter Types

Response:

{"phoneId":"1234","phoneNumber":"08444488488","state":"available","bandName":"gold","typeId":"43","typeName":"infinity0844","typeTitle":"0844 Bronze"}
{"phoneId":"1235","phoneNumber":"08444488489","state":"available","bandName":"bronze","typeId":"43","typeName":"infinity0844","typeTitle":"0844 Bronze"}

Search For Number Types

Search for number types using filters.

Request:

GET /config/v2/numbers/inboundNumberTypes

GET Params

Filter Types

Response:

{"countryPrefix":"1","prefix":"925","typeName":"California","callRateGroupTitle":"USA Geographic"}
{"countryPrefix":"44","prefix":"01244","typeName":"Chester","callRateGroupTitle":"UK Geographic"}
{"countryPrefix":"44","prefix":"0161","typeName":"Manchester","callRateGroupTitle":"UK Geographic"}

List Numbers in a DGRP

Gets a list of phone numbers for a given DGRP.

Request:

GET /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers (shows all numbers)
GET /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers/fixed (filters by fixed numbers)

URL Path Params

GET Params

Filter Types

Response:

List of numbers for the given IGRP and DGRP.

{"phoneId":"1234567","typeId":"5","state":"","phoneNumber":"0844488488","destinationNumber":"01734123456","dgrp":"2","updateDatetime":"0000-00-00 00:00:00","usageType":"pool","ch":"0","usageFilter":"ict2~pub~Test Publisher~cmp~Test Campaign~kw~Test Keyword","phoneNumberAlias":"","typeName":"local0844","bandName":"gold","typeTitle":"Lo-call Rate 0844","dgrpName":"My DGRP","igrp":"1","holdUntil":"0000-00-00 00:00:00","startDate":"2017-04-24","numberStartDate":"2017-04-24","lastDialledDatetime":"0000-00-00 00:00:00","callCount30Days":"0","publisher":"Test Publisher,"campaign":"Test Campaign","keyword":"Test Keyword","network":"","adGroup":""}
{"phoneId":"1234568","typeId":"5","state":"","phoneNumber":"0844488489","destinationNumber":"01734123456","dgrp":"2","updateDatetime":"0000-00-00 00:00:00","usageType":"pool","ch":"0","usageFilter":"ict2~net~Test Network~ag~Test adGroup","phoneNumberAlias":"","typeName":"local0844","bandName":"bronzr","typeTitle":"Lo-call Rate 0844","dgrpName":"My DGRP","igrp":"1","holdUntil":"0000-00-00 00:00:00","startDate":"2017-04-24","numberStartDate":"2017-04-24","lastDialledDatetime":"0000-00-00 00:00:00","callCount30Days":"0","publisher":"","campaign":"","keyword":"","network":"Test Network","adGroup":"Test adGroup"}

Read Number Config

Gets config for a particular number.

Request:

GET /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers/{phoneId}

URL Path Params

Response:

Details of the requested phone number specified by the IGRP, DGRP and Phone Number ID

{"phoneId":"1234567","typeId":"5","state":"","phoneNumber":"0844488488","destinationNumber":"01734123456","dgrp":"2","updateDatetime":"0000-00-00 00:00:00","usageType":"pool","ch":"0","usageFilter":"ict2~pub~Test Publisher~cmp~Test Campaign~kw~Test Keyword","phoneNumberAlias":"","typeName":"local0844","bandName":"gold","typeTitle":"Lo-call Rate 0844","dgrpName":"My DGRP","igrp":"1","holdUntil":"0000-00-00 00:00:00","startDate":"2017-04-24","numberStartDate":"2017-04-24","lastDialledDatetime":"0000-00-00 00:00:00","callCount30Days":"0","publisher":"Test Publisher,"campaign":"Test Campaign","keyword":"Test Keyword","network":"","adGroup":""}

Provision Fixed Numbers

Allocates fixed numbers to the dgrps/channels. Numbers take up to 2 minutes to activate on our voice switches.

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers/fixed

Fixed number allocation requests can be submitted to the Config API individually or as a bulk job containing several individual number allocation requests.

URL Path Params

GET Params

Filter Types

POST Params

Usage:

Request location

The request location for provisioning fixed numbers is

POST https://api.infinitycloud.com/config/v2/igrps/{igrp ID}/dgrps/{dgrp ID}/numbers/fixed

There is an additional ‘filter’ parameter that should be appended to the URL above to indicate what number type you want to provision.

E.g. To provision a standard 033 number we would append two filters to the URL

//Filter bandName equals standard

filter[]=bandName-eq-value-standard

//Filter phoneNumber starts with 033

filter[]=phoneNumber-begins-value-033
POST https://api.infinitycloud.com/config/v2/igrps/{igrp ID}/dgrps/{dgrp ID}/numbers/fixed?filter[]=bandName-eq-value-standard&filter[]=phoneNumber-begins-value-033

Request Data

The request data contains options for configuring the numbers, the commonly used options are listed below. These properties should be sent in the request body, not in the URL

destinationNumber => +441737123456
ch => 123
usageFilter => Brochure number

== PHP & cURL example ==

//Set credentials string

$credentials = 'username:password';

//Setup location

$url = 'https://api.infinitycloud.com/config/v2/igrps/{IGRPID}/dgrps/{DGRPID}/numbers/fixed';

//Append filters

$url .= '?filter[]=bandName-eq-value-standard&filter[]=phoneNumber-begins-value-033';

//Define POST params

$postParams = [
    'destinationNumber' => '+441737123456',
    'ch'                => '123',
    'usageFilter'       => 'Brochure number',
];

$postData = http_build_query($postParams);

//Setup cURL

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, count($postParams));
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_USERPWD, $credentials);

$result = curl_exec($ch);
curl_close($ch);

Response:

Returns the phone number config for each of the provisioned phone numbers

HTTP 201 - CREATED
{"phoneId":"12345","phoneNumber":"0844488488","bandName":"bronze","typeName":"infinity0844","ch":"1","usageType":"pool","dgrp":"123","igrp":"1","destinationNumber":"123456789","phoneNumberAlias":"MyPhoneNumberAlias"}

Provision Pool Numbers

Allocates pool numbers to the dgrps/channels. Numbers take up to 2 minutes to activate on our voice switches.

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers/pool

Pool number allocation requests are submitted to the Config API individually.

URL Path Params

GET Params

Filter Types

POST Params

Example

Pool number allocation request

Example: Pool number provision request:

<?php
$request = array(
    "quantity"          => 3,
    "destinationNumber" => '017312345679',
    "ch"                => 1,
)
?>

POST /config/v2/igrps/1234/dgrps/5678/numbers/fixed?filter[]=bandName-eq-value-bronze

Response:

Returns the phone number config for each of the provisioned phone numbers

HTTP 201 - CREATED
{"phoneId":"12345","phoneNumber":"0844488488","bandName":"bronze","typeName":"infinity0844","ch":"1","usageType":"pool","dgrp":"123","igrp":"1","destinationNumber":"123456789","phoneNumberAlias":""}

Release Quarantined Numbers

Releases quarantined numbers in a DGRP. Sometimes numbers are pre-provisioned into a DGRP in a quarantined state whilst they going through a cleaning process. This route provides the ability to release a number early from that process and to activate it into its assigned DGRP for use.

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers/unquarantine

URL Path Params

GET Params

Filter Types

Example

Release quarantined number request

Example: Release quarantined number request:

POST /config/v2/igrps/1234/dgrps/5678/numbers/unquarantine?filter[]=phoneNumber-in-value-08002343476,08002343478,08002343491

Response:

Returns the HTTP response code to reflect the request outcome.

HTTP 204 - NO CONTENT

Transfer Numbers between DGRPs

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers/transfer

URL Path Params

POST Params

Response:

Returns the HTTP response code to reflect the request outcome

HTTP 204 - NO CONTENT

Update Single Number Config

Updates config for a single number.

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers/{phoneId}

URL Path Params

POST Params

Response:

Returns the HTTP response code to reflect the request outcome.

HTTP 204 - NO CONTENT

Update Multiple Number Configs

Updates config for multiple numbers.

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers

URL Path Params

GET Params

Filter Types

POST Params

Response:

Returns the HTTP response code to reflect the request outcome.

HTTP 204 - NO CONTENT

Delete Number

Deletes a particular number (it will be de-activated and moved into quarantine).

Request:

DELETE /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers/{phoneId}

URL Path Params

Response:

HTTP 204 - NO CONTENT

Withdraw number

Schedules a number to be withdrawn from a DGRP after a period of time to allow safe removal of pool numbers.

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/dgrps/{DGRP SPECIFIER}/numbers/withdraw

URL Path Params

POST Params

Response

HTTP 204 - NO CONTENT

List Country Prefixes

Gets a list of Country Prefixes by Country Name.

Request:

GET /config/v2/numbers/countryPrefixes

GET Params

Filter Types

Sort Types

The Country Prefixes list may be sorted by any of the returned fields.

Response:

List of Country Prefixes by Country Name.

{"countryName":"US/Canada","countryPrefix":"1"}
{"countryName":"Russia","countryPrefix":"7"}