7. Contact Validation: Phone Number ¶

Contents

7.1. PhoneNumber ¶

The Phone Number validation service returns the connectivity status of the supplied phone number. This service is a multi-step process where the initial response returned may be ‘Status: 100 – Verifying’ indicating that the API is processing the final status of the phone number. If the status code / description in the response message corresponds to ‘Verifying’, the request message should be retried until a final status code is received. Both a status code and Status Description are returned in the response message. In the event that the supplied phone number is a mobile number, the mobile carrier can also be returned.

The details of the status codes can be found in the status code section.

7.1.1. API URL Endpoint and URL Format ¶

https://services.inivio.com.au/validate/phonenumber?query_string

The query string is composed of a series of field-value pairs field1=value1&field2=value2&field3=value3

7.1.2. Authentication ¶

Basic Authentication over HTTPS

7.1.3. Query String Fields and Values ¶

Query String Parameter	Values	Type	Notes
value	phone number	Mandatory	Phone number should be between 9 to 12 digits
carrier	true/false	Optional field	Returns the mobile carrier name for any mobile number. Default is false. See Warning below

Note

API endpoint URLs including the parameters in the query string are not case sensitive.

Warning

Requesting carrier data may incur additional fees. Please check with your account manager or Contact Us before using carrier data.

7.1.4. Response Format ¶

XML , JSON depends on “Accept” field in the HTTP header.

Example – Setting ‘Accept’ field in the HTTP header

httpRequest.setRequestHeader('Accept', 'application/json');
//Or
XMLHttpRequest. setRequestHeader('Accept',"application/json");

7.1.5. Response status codes ¶

Status Codes	Description	Status
100	Verifying...	queued
200	Connected. <Carrier if selected>	connected
300	Disconnected phone number.	disconnected
400	We’re pretty sure this phone number is connected, but can’t be sure.	indeterminate
-1	Check the phone number, and try again	invalid
-1	Country code <input> is not valid	invalid
-1	Phone Number is not valid	invalid
-2	Unable to process your request,please try again later	error
0	Unable to determine the status of this phone number	unknown

7.1.5.1. Response status definitions ¶

Status	Definition
queued	System is checking connectivity of phone number. Re-run the request at a 500 millisecond interval until a connectivity status is received.
connected	Phone Number is connected.
disconnected	Phone Number is disconnected.
indeterminate	Response did not clearly define if the number is connected or disconnected. Typically related to when a handset has been suspended due to non-payment, or, when the phone is out of a signal area when on international roaming.
invalid	Invalid country code or Phone Number.
error	An error occurred during processing.
unknown	Destination not supported or results proved to be inconclusive; most of the time a request did not respond quickly enough.

7.1.6. Example 1A ¶

7.1.6.1. Request ¶

Check the connectivity status of number in the value field

https://services.inivio.com.au/validate/phonenumber?value=02988xxxxx

7.1.6.2. Response ¶

<VerificationResult
        xmlns="http://schemas.datacontract.org/2004/07/ImpCommon.DataContract"
        xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Status>queued</Status>
  <PhoneNumber>612988xxxxx</PhoneNumber>
  <ProcessedDateTimeUTC>2014-02-19T01:08:27</ProcessedDateTimeUTC>
  <StatusCode>100</StatusCode>
  <StatusDescription>Verifying.</StatusDescription>
</VerificationResult>

7.1.7. Example 1B ¶

7.1.7.1. Request ¶

If the response contains Status Code “100” and Status Description “Verifying…”, send the same request again

https://services.inivio.com.au/validate/phonenumber?value=02988xxxxx

7.1.7.2. Response ¶

<VerificationResult
        xmlns="http://schemas.datacontract.org/2004/07/ImpCommon.DataContract"
        xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Status>connected</Status>
  <PhoneNumber>612988xxxxx</PhoneNumber>
  <ProcessedDateTimeUTC>2014-02-19T01:12:18</ProcessedDateTimeUTC>
  <StatusCode>200</StatusCode>
  <StatusDescription>Connected.</StatusDescription>
</VerificationResult>

7.1.8. Example 2A ¶

7.1.8.1. Request ¶

Check the connectivity status of number in the value field, which is a mobile number

https://services.inivio.com.au/validate/phonenumber?value=0408xxxxxx&carrier=true

7.1.8.2. Response ¶

<VerificationResult
        xmlns="http://schemas.datacontract.org/2004/07/ImpCommon.DataContract"
        xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Status>queued</Status>
  <PhoneNumber>61408xxxxxx</PhoneNumber>
  <ProcessedDateTimeUTC>2014-02-19T01:16:25</ProcessedDateTimeUTC>
  <StatusCode>100</StatusCode>
  <StatusDescription>Verifying.</StatusDescription>
</VerificationResult>

7.1.9. Example 2B ¶

7.1.9.1. Request ¶

If the response contains Status Code “100” and Status Description “Verifying…”, send the same request again

https://services.inivio.com.au/validate/phonenumber?value=0408xxxxxx&carrier=true

7.1.9.2. Response ¶

Response for mobile shows the carrier

<VerificationResult
        xmlns="http://schemas.datacontract.org/2004/07/ImpCommon.DataContract"
        xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Status>connected</Status>
  <PhoneNumber>61408xxxxxx</PhoneNumber>
  <Carrier>Telstra</Carrier>
  <ProcessedDateTimeUTC>2014-02-19T01:18:57</ProcessedDateTimeUTC>
  <StatusCode>200</StatusCode>
  <StatusDescription>Connected.</StatusDescription>
</VerificationResult>