The API accepts phone numbers in UK format as well as E.164 format. If the number begins with a “+" sign then it is assumed to be in E.164 format, otherwise it is assumed to be in UK format.
The API by default returns phone numbers in UK format, but can be instructed either by default or on a per request basis to return them in E.164 format instead.
"UK format" means as you would dial the number from a UK phone, eg starting “0151" for a Liverpool number, starting “118" for a directory enquiries number or “999" for the emergency services. For non-UK numbers, the number would start with “00", so starting “001" for USA numbers and “0049" for German numbers for example.
In E.164 format, a Liverpool number would start “+44151", a USA number would simply start “+1" and a German number would start “+49".
It is not possible to specify country-local numbers in standard E.164 format (eg “118118" for example), but we have extended the schema with an Asterisk character to indicate this, eg “+44*118118" indicating 118118 as a UK specific number. In a SIP URI, you might expect this to be represented with a SIP address like 118118;phone_context=+44@sip.example.com
When used as a destination number (ie when our system routes calls TO that number), then numbers may optionaly have an extension appended.
Within the auth section of the API request, specify an env object, declaring the value of telecoms_num_format_output to e164:
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : YOURUSERNAME,
"password" : YOURPASSWORD,
"env" : {
"telecoms_num_format_output" : "e164"
}
},
"func" : "telecoms.num.list",
"args" : {
"number.starts" : "016"
}
}
JSON example response:
{
"success" : 1,
"results" : {
"numbers" : [
{
"valid_to" : "2038-01-19 03:14:07",
"transport_in" : [
"pstn"
],
"setup_fee" : "0.00",
"date_alloc" : "2010-09-09",
"automated" : 1,
"svcchg_optionID" : 0,
"telco" : "Barritel",
"custID" : 16526,
"routeto_type" : "ivr",
"tnID" : 0,
"numberID" : 821001,
"number" : "+441603315641",
"ivrID" : 3
}
],
"totmatches" : 1
}
}