# 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="../../api-processing-errors/error-returns" %}
[error-returns](https://api.veratad.com/api-processing-errors/error-returns)
{% endcontent-ref %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://api.veratad.com/phone-verification-and-validation/verification-and-validation/phone-validation.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.