Phone Validation

Validate a phone number and receive phone details on return.

PhoneMatch5.0.Validate

POST 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 Body

NameTypeDescription

user

string

Your account's API username

pass

string

Your Account's API password

service

string

The service name (PhoneMatch5.0.Validate)

reference

string

A unique identifier for your customer

target

object

The individual being sent for verification

phone

string

The target's phone number (see formats below)

invalid_phonelinetypes

array

Set which line types should FAIL the check (see below for input values)

{
    "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": "user@company.com"
    },
    "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

Last updated