telecoms.ddi.check function

Home > telephony > nts > function-reference > func.telecoms.ddi.check

function telecoms.ddi.check

This function can be used to check whether a phone number is actually in service. It does this by making a very brief test call to that number.

Note: In many cases the call is ended before the remote phone actually rings, but sometimes the user may receive a missed call alert.

Arguments:

arg	required?	syntax	info
`ddi`	Y	TelNum	the phone number to be checked
`custID`	N	posint	the customer account that will be charged for the test call (default is the account of the current API user)
`use_cache`	N	boolean	whether to use previously cached results for the number being checked, if available (default=1 (true))

Return Values

ddi_valid - indicates whether the number is valid; if you don't want to go into more detail then you can simply look at this value.
- a value of 1 indicates that the number is valid
- a value of 0 indicates that the number is not valid
- a value of null indicates that it was not possible to tell whether the number is valid due to a temporary failure on the telephony network (eg destination out of order, call rejected)

Other return values for additional information

is_range - indicates whether the number is in a valid number range (1=yes, 0=no)
length_error - indicates whether the number is the correct length (ie correct number of digits):
- a value of 0 means that the length is correct
- a value less than 0 means that more digits are required (eg, a value of -2 indicates that two more digits are required)
- a value greater than 0 means that too many digits have been supplied (eg, a value of 1 indicates that one too many digits has been supplied)

Note that unless is_range=0 and length_error=0 then no actual test call will be made as it is already known that the number is not valid. Therefore the below values will be null. If however the range and length look valid, then the number will be called in order to gather more detail. The below values will therefore also be set:

progress_detected - whether a progress signal was received during the test call (similar to, but not necessarily the same as, ringing)
ringing_detected - whether a ringing signal was received during the test call
answered - whether the test call was actually answered
clearcause - the Q.850/Q.931 clear cause (ie how the call ended); see Q.931 Causes on Wikipedia
clearcause_desc - a brief textual description of the clear cause
ttl - time to live - the number of seconds for which we will cache the results; we suggest you consider the result valid for this length of time after the check

Example 1

Check phone number 01174960000.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.ddi.check",
   "args" : {
     "ddi" : "01174960000"
   }
}

JSON example response:

{
   "success" : 1,
   "results" : {
      "ddi_valid" : 1,
      "is_range" : 1,
      "length_error" : 0,
      "progress_detected" : 1,
      "ringing_detected" : 1,
      "answered" : 0,
      "clearcause" : 16,
      "clearcause_desc" : "Normal call clearing",
      "ttl" : 10367850
   }
}

In the above response, success = 1 which tells us that the API call completed successfully.

Within the results section, we can see:

ddi_valid = 1 - this tells us that the number is valid; we need not look any further if that's all we wanted to know
is_range = 1 - tells us that the number fits into a valid number range, which will always be the case if the number is valid
length_error = 0 - tells us that the number is of the correct lenght, which will always be the case if the number is valid
progress_detected = 1 - our system detected progress indication during the test call
ringing_detected = 1 - our system recevied ringing indication during the test call
answered = 0 - the call was not answered (our system ended the call before it was picked up)
clearcause = 16 - this is normal for a successful call
clearcause_desc = "Normal call clearing" - textual description of the meaning of the clearcause
ttl = 10367850 - how long (in seconds) that we recommend that you remember this answer for

Example 2

Check phone number 0117496000.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.ddi.check",
   "args" : {
     "ddi" : "01174960000"
   }
}

JSON example response:

{
   "success" : 1,
   "results" : {
      "ddi_valid" : 0,
      "is_range" : 1,
      "length_error" : -1,
      "progress_detected" : null,
      "ringing_detected" : null,
      "answered" : null,
      "clearcause" : null,
      "clearcause_desc" : null,
      "ddi_allowed" : null
   }
}

In the above response, success = 1 which tells us that the API call completed successfully.

Within the results section, we can see:

ddi_valid = 0 - a value of zero means that this is not a valid phone number; you will need to look at some of the other values to see why
is_range = 1 - tells us that the number is within a valid number range (or in this case, would do if another digit was supplied)
length_error = -1 - a negative value here means that we have not supplied enough digits; a value of -1 tells us that the number is 1 digit short

The remaining values are null because no test call was attempted. This is because we already know that the number is not valid because it is 1 digit short:

progress_detected = null
ringing_detected = null
answered = null
clearcause = null
clearcause_desc = null
ddi_allowed = null

Example 3

Check phone number 011749600000.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.ddi.check",
   "args" : {
     "ddi" : "011749600000"
   }
}

JSON example response:

{
   "success" : 1,
   "results" : {
      "ddi_valid" : 0,
      "is_range" : 1,
      "length_error" : 1,
      "progress_detected" : null,
      "ringing_detected" : null,
      "answered" : null,
      "clearcause" : null,
      "clearcause_desc" : null,
      "ddi_allowed" : null
   }
}

In the above response, success = 1 which tells us that the API call completed successfully.

Within the results section, we can see:

ddi_valid = 0 - a value of zero means that this is not a valid phone number; you will need to look at some of the other values to see why
is_range = 1 - tells us that the number is within a valid number range (or in this case, would do if another digit was supplied)
length_error = 1 - a positivevalue here means that we have supplied too many digits; a value of 1 tells us that the number is 1 digit too long

The remaining values are null because no test call was attempted. This is because we already know that the number is not valid because it is 1 digit too long:

progress_detected = null
ringing_detected = null
answered = null
clearcause = null
clearcause_desc = null
ddi_allowed = null

Example 5

Check phone number 01174960022.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.ddi.check",
   "args" : {
     "ddi" : "01174960022"
   }
}

JSON example response:

{
   "success" : 1,
   "results" : {
      "ddi_valid" : 0,
      "is_range" : 1,
      "length_error" : 0,
      "progress_detected" : 0,
      "ringing_detected" : 0,
      "answered" : 0,
      "clearcause" : 1,
      "clearcause_desc" : "Unallocated number",
      "ttl" : 604800,
      "ddi_allowed" : 1
   }
}

In the above response, success = 1 which tells us that the API call completed successfully.

Within the results section, we can see:

ddi_valid = 0 - a value of zero means that this is not a valid phone number; you will need to look at some of the other values to see why
is_range = 1 - tells us that the number is in an assigned number range
length_error = 0 - a value of zero here tells us that the number is of the correct length.

The remaining values are not null, therefore we know that a test call was made:

progress_detected = 0 - no call progress was detected
ringing_detected = 0 - no ringing was detected
answered = 0 - the test call was not answered
clearcause = 1 - the test call ended with a clearcause of 1 (not 16, which would have been normal for a valid number)
clearcause_desc = "Unallocated number" - this tells us that the number is not allocated to anybody. If you were to call this on an analogue phone, it is likely that you would hear an announcement saying "The number you have dialled has not been recognised."
ttl = 604800 - how long (in seconds) that we recommend that you remember this answer for
ddi_allowed = 1 - a value of 1 here means that your account has the required permissions to call this number

Example 6

Check phone number 09000129292. This is a premium rate number; by default we don't allow customers to dial premium rate numbers.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.ddi.check",
   "args" : {
     "ddi" : "09000129292"
   }
}

JSON example response:

{
   "success" : 1,
   "results" : {
      "is_range" : 1,
      "length_error" : 0,
      "ddi_allowed" : 0,
      "ddi_valid" : null,
      "progress_detected" : null,
      "ringing_detected" : null,
      "answered" : null,
      "clearcause" : null,
      "clearcause_desc" : null
   }
}

In the above response, success = 1 which tells us that the API call completed successfully.

Within the results section, we can see:

is_range = 1 - tells us that the number is in an assigned number range
length_error = 0 - a value of zero here tells us that the number is of the correct length.
ddi_allowed = 0 - a value of 0 here means that your account does not have the required permissions to call this number

Because 09000129292 is not a permitted destination number from this API account, no test call was made, therefore all of the remaining values are null. You do however know from the values in is_range and length_error that the number fits within an assigned number range and is of the correct length.

ddi_valid = null
progress_detected = null
ringing_detected = null
answered = null
clearcause = null
clearcause_desc = null