Version 2 Numbers
Introduction
This section provides functionality relating to phone numbers.
- Each Phone Number is assigned a numeric ID that can be used to reference it in the APIs.
- Each Phone Number is assigned to a single DGRP.
- Each Phone Number has a type of either “fixed” or “pool”.
- Each Phone Number can be assigned to a single Channel.
- Each Phone number can be assigned a destination to forward calls to.
- Fixed Phone Numbers can be assigned a particular reference string (usageFilter)
- Phone Numbers can be transferred between DGRPs
Search For Available Numbers
Search for available numbers using filters.
Request:
GET Params
- limit (integer) - Limit response list (1000 max)
- offset (integer) OPTIONAL - Offset value to apply when returning list of available numbers.
- filter (array) OPTIONAL - One or more filters, see Filter Types.
Filter Types
- bandName (string) - Band of number to order (standard, bronze, silver, gold, platinum, diamond)
- phoneNumber (string) - Exact phone number if known.
- typeName (string) - Phone number type by name.
Response:
- phoneId (int) - Phone Number ID.
- phoneNumber (string) - Allocated phone number.
- state (string) - Phone number state.
- bandName (string) - Band of number to order (standard, bronze, silver, gold, platinum, diamond)
- typeId (int) - Phone number type ID.
- typeName (string) - Required phone number type (e.g. local0844, tollfree etc.)
- typeTitle (string) - Friendly phone number type display name.
Search For Number Types
Search for number types using filters.
Request:
GET Params
- limit (integer) OPTIONAL - Limit response list (1000 max)
- offset (integer) OPTIONAL - Offset value to apply when returning list of available number types.
- filter (array) OPTIONAL - One or more filters, see Filter Types.
Filter Types
- countryPrefix (string) - Country prefix.
- prefix (string) - Number prefix.
- typeName (string) - Number type name.
- callRateGroupTitle (string) - Name of the call rate group for the number type.
Response:
- countryPrefix (string) - Country prefix.
- prefix (string) - Number prefix.
- typeName (string) - Number type name.
- callRateGroupTitle (string) - Name of the call rate group for the number.
List Numbers in a DGRP
Gets a list of phone numbers for a given DGRP.
Request:
URL Path Params
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - Dial-In Group (DGRP) ID.
GET Params
- filter (array) OPTIONAL - One or more filters, see Filter Types.
- limit (integer) OPTIONAL - limit on the result set.
- offset (integer) OPTIONAL - offset of the result set.
Filter Types
- phoneId (integer) - ID of the number
- phoneNumber (string) - Phone number (e.g. 0844123456 etc.)
- state (string) - State of number (e.g ready)
- destinationNumber (string) - Destination of the tracking number
- usageType (string) - Type of tracking number (e.g. fixed or pool)
- ch (int) - Channel ID of the number.
- usageFilter (string) - The keyword for this number
- bandName (string) - Band of number to required (standard, bronze, silver, gold, platinum, diamond)
- typeName (string) - Required phone number type (e.g. local0844, tollfree etc.)
- lastDialledDatetime (datetime) - The last dialled datetime of the phone number
Response:
List of numbers for the given IGRP and DGRP.
- igrp (int) - Installation ID.
- dgrp (int) - Dial-In Group (DGRP) unique ID.
- dgrpName (string) - Friendly name of the Dial-In Group (e.g. “Sales Numbers”)
- phoneId (int) - Phone Number ID.
- phoneNumber (string) - Allocated phone number.
- bandName (string) - Band of number to order (standard, bronze, silver, gold, platinum, diamond)
- ch (int) - Channel ID to associate number to.
- usageFilter (string) - The label for this number if usageType is fixed.
- usageType (string) - Usage type for the number (fixed or pool)
- typeId (int) - Phone number type ID.
- typeTitle (string) - Friendly phone number type display name.
- typeName (string) - Required phone number type ( e.g. local0844, tollfree etc.)
- phoneNumberAlias (string) - alternative display number for this number (used for international forwarding)
- destinationNumber (string) - Destination to forward number to.
- state (string) - Phone number state.
- updateDatetime (datetime) - Last update date time
- channelName (string) - The number’s channel (Note: channelName will not be returned if not applicable)
- holdUntil (datetime) - If the number is held in quarantine, it will be held until this date time.
- startDate (date) DEPRECATED - The date this DGRP was created (Date format: yyyy-mm-dd e.g. “2017-04-24”).
- numberStartDate (date) - When the number was added to this DGRP (Date format: yyyy-mm-dd e.g. “2017-04-24”).
- lastDialledDatetime (datetime) - The last time the phone number has been dialled.
- callCount30Days (integer) - Number of times the phone number has been called within last 30 days.
- publisher (string) - Publisher extracted from usageFilter.
- campaign (string) - Campaign extracted from usageFilter.
- keyword (string) - Keyword extracted from usageFilter.
- network (string) - Network extracted from usageFilter.
- adGroup (string) - Ad Group extracted from usageFilter.
Read Number Config
Gets config for a particular number.
Request:
URL Path Params
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - Dial-In Group (DGRP) ID.
- phoneId (int) - Phone Number ID.
Response:
Details of the requested phone number specified by the IGRP, DGRP and Phone Number ID
- igrp (int) - Installation ID.
- dgrp (int) - Dial-In Group (DGRP) unique ID.
- dgrpName (string) - Friendly name of the Dial-In Group (e.g. “Sales Numbers”)
- phoneId (int) - Phone Number ID.
- phoneNumber (string) - Allocated phone number.
- bandName (string) - Band of number to order (standard, bronze, silver, gold, platinum, diamond)
- ch (int) - Channel ID to associate number to.
- usageFilter (string) - The label for this number if usageType is fixed.
- usageType (string) - Usage type for the number (fixed or pool)
- typeId (int) - Phone number type ID.
- typeTitle (string) - Friendly phone number type display name.
- typeName (string) - Required phone number type ( e.g. local0844, tollfree etc.)
- phoneNumberAlias (string) - Alternative display number for this number (used for international forwarding)
- destinationNumber (string) - Destination to forward number to.
- state (string) - Phone number state.
- updateDatetime (datetime) - Last update date time.
- holdUntil (datetime) - If the number is held in quarantine, it will be held until this date time.
- startDate (date) DEPRECATED - The date this DGRP was created (Date format: yyyy-mm-dd e.g. “2017-04-24”).
- numberStartDate (date) - When the number was added to this DGRP (Date format: yyyy-mm-dd e.g. “2017-04-24”).
- lastDialledDatetime (datetime) - The last time the phone number has been dialled.
- callCount30Days (integer) - Number of times the phone number has been called within last 30 days.
- publisher (string) - Publisher extracted from usageFilter.
- campaign (string) - Campaign extracted from usageFilter.
- keyword (string) - Keyword extracted from usageFilter.
- network (string) - Network extracted from usageFilter.
- adGroup (string) - Ad Group extracted from usageFilter.
Provision Fixed Numbers
Allocates fixed numbers to the dgrps/channels. Numbers take up to 2 minutes to activate on our voice switches.
Request:
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
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - Dial-In Group (DGRP).
GET Params
- filter (array) - One or more filters, see Filter Types.
Filter Types
- bandName (string) - Band of number to required (standard, bronze, silver, gold, platinum, diamond)
- typeName (string) - Required phone number type (e.g. local0844, tollfree etc.)
- phoneNumber (string) - Required phone number (e.g. 0844123456 etc.)
POST Params
- quantity (int) OPTIONAL - The amount of numbers to provision, defaults to 1. Will provision the ordered quantity of numbers even if only one destination number is provided.
- destinationNumber (string/array) - Destination to forward number to. Can be a static string or an array of ‘destinationNumber’ values for bulk job.
- ch (int/array) - Channel ID to associate number to. Can be a static integer or an array of ‘ch’ values for bulk job.
- usageFilter (string/array) - The label for the fixed number. Can be a static string or an array of ‘usageFilter’ values for bulk job. Defaults to empty.
- phoneNumberAlias (string/array) OPTIONAL - Alternative display number for this number (used for international forwarding). Can be a static string or an array of ‘phoneNumberAlias’ values for bulk job. Defaults to empty.
Usage:
Request location
The request location for provisioning fixed numbers is
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
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 - The destination number for these numbers
- ch - The channel to provision the numbers into
- usageFilter - A description for the number
== PHP & cURL example ==
Response:
- phoneId (int) - Phone Number ID.
- phoneNumber (string) - Allocated phone number.
- ch (int) - Channel ID to associate number to.
- bandName (string) - Band of number to order (standard, bronze, silver, gold, platinum, diamond)
- usageType (string) - Phone number usage type. (fixed or pool).
- typeName (string) - Required phone number type (e.g. local0844, tollfree etc.)
- phoneNumberAlias (string) - Alternative display number for this number (used for international forwarding).
- destinationNumber (string) - Destination to forward number to.
Returns the phone number config for each of the provisioned phone numbers
Provision Pool Numbers
Allocates pool numbers to the dgrps/channels. Numbers take up to 2 minutes to activate on our voice switches.
Request:
Pool number allocation requests are submitted to the Config API individually.
URL Path Params
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - Dial-In Group (DGRP) ID.
GET Params
- filter (array) - One or more filters, see Filter Types.
Filter Types
- bandName (string) - Band of number to required (standard, bronze, silver, gold, platinum, diamond)
- typeName (string) - Required phone number type (e.g. local0844, tollfree etc.)
- phoneNumber (string) - Required phone number (e.g. 0844123456 etc.)
POST Params
- quantity (int) OPTIONAL - The amount of numbers to provision, defaults to 1. Will provision the ordered quantity of numbers even if only one destination number is provided.
- destinationNumber (string) - Destination to forward number to.
- ch (int) OPTIONAL - Channel ID to associate number to. Defaults to 0
Example
Pool number allocation request
- Provide the {IGRP SPECIFIER}, {DGRP SPECIFIER} & the required {filter} for the request.
- Define the Number option fields as static values within the request.
Response:
- phoneId (int) - Phone Number ID.
- phoneNumber (string) - Allocated phone number.
- ch (int) - Channel ID to associate number to.
- bandName (string) - Band of number to order (standard, bronze, silver, gold, platinum, diamond)
- usageType (string) - Phone number usage type. (fixed or pool).
- typeName (string) - Required phone number type (e.g. local0844, tollfree etc.)
- phoneNumberAlias (string) - Blank - not applicable for pool number requests
- destinationNumber (string) - Destination to forward number to.
Returns the phone number config for each of the provisioned phone numbers
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:
URL Path Params
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - DGRP ID.
GET Params
- filter (array) - One or more filters, see Filter Types.
Filter Types
- phoneNumber (string) - Required phone number (e.g. 0844123456 etc.)
Example
Release quarantined number request
- Provide the {IGRP SPECIFIER}, {DGRP SPECIFIER} & the required {filter} for the request.
Response:
Returns the HTTP response code to reflect the request outcome.
Transfer Numbers between DGRPs
Request:
URL Path Params
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - DGRP ID.
POST Params
- dgrp (int) - Destination DGRP ID.
- phoneIds (string/array) - Phone IDs to transfer. Can be static string, a list of phone IDs separated by a comma or an array of phone IDs.
- igrp (int) OPTIONAL - Destination IGRP ID. If transferring to a DGRP in a different IGRP, this field is required.
- ch (int) OPTIONAL - Destination Channel ID. If destination IGRP is set, this field is required.
Response:
Returns the HTTP response code to reflect the request outcome
Update Single Number Config
Updates config for a single number.
Request:
URL Path Params
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - Dial-In Group (DGRP) ID.
- phoneId (int) - Phone Number ID
POST Params
- destinationNumber (string) OPTIONAL - Destination to forward number to.
- ch (int) OPTIONAL - Channel ID to associate number to.
- phoneNumberAlias (string) OPTIONAL - Alternative display number for this number (used for international forwarding).
- usageFilter (string) OPTIONAL - The label for the fixed number.
- usageType (string) OPTIONAL - The usage type of number (e.g. fixed or pool).
- dgrp (int) OPTIONAL - The DGRP ID to move phone number into.
Response:
Returns the HTTP response code to reflect the request outcome.
Update Multiple Number Configs
Updates config for multiple numbers.
Request:
URL Path Params
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - Dial-In Group (DGRP) ID.
GET Params
- filter (array) - One or more filters, see Filter Types.
Filter Types
- phoneId (integer) - ID of the number
- phoneNumber (string) - Phone number (e.g. 0844123456 etc.)
- state (string) - State of number (e.g ready)
- destinationNumber (string) - Destination of the tracking number
- usageType (string) - Type of tracking number (e.g. fixed or pool)
- ch (int) - Channel ID of the number.
- usageFilter (string) - The keyword for this number
- bandName (string) - Band of number to required (standard, bronze, silver, gold, platinum, diamond)
- typeName (string) - Required phone number type (e.g. local0844, tollfree etc.)
POST Params
- destinationNumber (string) OPTIONAL - Destination to forward number to.
- ch (int) OPTIONAL - Channel ID to associate number to.
- phoneNumberAlias (string) OPTIONAL - Alternative display number for this number (used for international forwarding).
- usageFilter (string) OPTIONAL - The label for the fixed number.
- usageType (string) OPTIONAL - The usage type of number (e.g. fixed or pool).
- dgrp (int) OPTIONAL - The DGRP ID to move phone number into.
Response:
Returns the HTTP response code to reflect the request outcome.
Delete Number
Deletes a particular number (it will be de-activated and moved into quarantine).
Request:
URL Path Params
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - Dial-In Group (DGRP) ID.
- phoneId (int) - Phone Number ID
Response:
Withdraw number
Schedules a number to be withdrawn from a DGRP after a period of time to allow safe removal of pool numbers.
Request:
URL Path Params
- IGRP SPECIFIER (int) - Installation ID.
- DGRP SPECIFIER (int) - DGRP ID.
POST Params
- phoneId (int/array) - Phone Number ID. Can be supplied as an array to withdraw multiple numbers.
Response
List Country Prefixes
Gets a list of Country Prefixes by Country Name.
Request:
GET Params
- filter (array) OPTIONAL - One or more filters, see Filter Types.
- sort (array) OPTIONAL - One or more sorting params.
- limit (int) OPTIONAL - limit on the result set.
- offset (int) OPTIONAL - offset of the result set.
Filter Types
- countryName (string) - Country Name.
- countryPrefix (int) - Country Prefix.
Sort Types
The Country Prefixes list may be sorted by any of the returned fields.
Response:
List of Country Prefixes by Country Name.
- countryName (string) - Country Name.
- countryPrefix (int) - Country Prefix.