Phone Validation

Validate a phone number and receive phone details on return.

post
PhoneMatch5.0.Validate
https://production.idresponse.com/process/comprehensive/gateway
Make an HTTPS POST request with the following body parameters to find out if the target has provided a valid number and other details about the number. You will receive a synchronous response in 2-3 seconds with a result object that includes an action, detail and issues object.
Request
Response
Request
Body Parameters
user
required
string
Your account's API username
pass
required
string
Your Account's API password
service
required
string
The service name (PhoneMatch5.0.Validate)
reference
optional
string
A unique identifier for your customer
target
required
object
The individual being sent for verification
phone
required
string
The target's phone number (see formats below)
invalid_phonelinetypes
optional
array
Set which line types should FAIL the check (see below for input values)
Response
200: OK
Transaction processed and result returned
{
    "output": {
        "data": {
            "PhoneNumber": [
                {
                    "countrycode": "US",
                    "countrycallingcode": "1",
                    "country": "United States",
                    "phonelinetype": "Mobile",
                    "carrier": "Verizon Wireless",
                    "phonenumber": "2015106000"
                }
            ]
        }
    },
    "meta": {
        "confirmation": 71785534,
        "reference": null,
        "service": "PhoneMatch5.0.Validate",
        "timestamp": "2019-10-25 14:09:12",
        "company": "Company, LLC",
        "user": "[email protected]"
    },
    "result": {
        "action": "PASS",
        "detail": "ALL CHECKS PASSED",
        "issues": []
    }
}
Sample Request Body
{
    "user": "USERNAME",
    "pass": "PASSWORD",
    "service": "PhoneMatch5.0.Validate",
    "reference": "12345",
    "target": {
       "phone": "2015106000",
       "invalid_phonelinetypes": ["voip"]
    }
}
How should the number be formatted? 
The number should be a string with the country code followed by the number. 
US Example
12015106000
International Example
442015412653
If you send the number with any characters that is fine. They will be stripped out. So, 1 (201) 510-6000 is also valid. 
Invalid Phone Number Types
On input you can set which line types should return a FAIL - PHONE TYPE CHECK FAILED. For example, the above would fail if the number was detected as voip. Use any of the line types described below in the output data section. 
Action and Detail Responses
The following are all values that will be returned in the result object of the response.
Action
Detail
Description
FAIL
PHONE CHECK FAILED
The phone number is not valid
FAIL
PHONE TYPE CHECK FAILED
The phone number type is in the exclusion list
PASS
ALL CHECKS PASSED
The phone number is valid and the type is not excluded
Output Data
 The phone validation returns information to your application about the number. Below are the return values. 
Parameter
Description
countrycode
The ISO-3166 alpha-2 country code of the address.
countrycallingcode
The country code of the phone number.
country
The country name of the location associated to the phone number.
phonelinetype
The line type of the phone number. 
​
Landline - Traditional wired phone line.
VOIP - VOIP-based fixed and nonfixed line phones.
Mobile - Wireless phone line.
Voicemail - Voicemail-only service.
TollFree - Callee pays for call.
Premium - Caller pays a premium for the call–e.g. 976 area code.
Other - Anything that does not match the previous categories.
carrier
The company that provides voice and/or data services for the phone number. Carriers are returned at the MVNO level.
phonenumber
The phone number in E.164 or local format. The default country calling code is +1 (USA).
Rules
PhoneMatch+Validate will process with the default base ruleset. Here are the rules:
The base ruleset will return a PASS when:
The phone number is valid
The phone number type is not on the exclusion list
The base ruleset will return a FAIL when:
The phone number is not valid
The phone number type is on the exclusion list
API Processing Error Returns
Error Returns
/api-processing-errors/error-returns

Phone Verification

Next - phonematch

One Time Passwords

Last updated 1 year ago

Action	Detail	Description
FAIL	PHONE CHECK FAILED	The phone number is not valid
FAIL	PHONE TYPE CHECK FAILED	The phone number type is in the exclusion list
PASS	ALL CHECKS PASSED	The phone number is valid and the type is not excluded

Parameter	Description
countrycode	The ISO-3166 alpha-2 country code of the address.
countrycallingcode	The country code of the phone number.
country	The country name of the location associated to the phone number.
phonelinetype	The line type of the phone number. `Landline` - Traditional wired phone line. `VOIP` - VOIP-based fixed and nonfixed line phones. `Mobile` - Wireless phone line. `Voicemail` - Voicemail-only service. `TollFree` - Callee pays for call. `Premium` - Caller pays a premium for the call–e.g. 976 area code. `Other` - Anything that does not match the previous categories.
carrier	The company that provides voice and/or data services for the phone number. Carriers are returned at the MVNO level.
phonenumber	The phone number in E.164 or local format. The default country calling code is +1 (USA).

Phone Validation

postPhoneMatch5.0.Validate

Sample Request Body

How should the number be formatted?

US Example

International Example

Invalid Phone Number Types

Action and Detail Responses

Output Data

Rules

API Processing Error Returns

post
PhoneMatch5.0.Validate