> For the complete documentation index, see [llms.txt](https://api.veratad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.veratad.com/phone-verification-and-validation/verification-and-validation/phone-validation.md).
# Phone Validation
## 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
| Name | Type | Description |
| ----------------------------------------- | ------ | ----------------------------------------------------------------------- |
| 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) |
{% tabs %}
{% tab title="200 Transaction processed and result returned" %}
```javascript
{
"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": []
}
}
```
{% endtab %}
{% endtabs %}
## Sample Request Body
```javascript
{
"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
```
{% hint style="info" %}
If you send the number with any characters that is fine. They will be stripped out. So, `1 (201) 510-6000` is also valid.
{% endhint %}
## 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
{% hint style="info" %}
The following are all values that will be returned in the result object of the response.
{% endhint %}
| 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
{% hint style="info" %}
The phone validation returns information to your application about the number. Below are the return values.
{% endhint %}
| 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:
{% hint style="success" %}
The base ruleset will return a PASS when:
* The phone number is valid
* The phone number type is not on the exclusion list
{% endhint %}
{% hint style="danger" %}
The base ruleset will return a FAIL when:
* The phone number is not valid
* The phone number type is on the exclusion list
{% endhint %}
## API Processing Error Returns
{% content-ref url="/pages/-LrjFxJ4Wv\_iErI2\_I7V" %}
[Error Returns](/api-processing-errors/error-returns.md)
{% endcontent-ref %}