API Documentation
Provero provides real-time data verification APIs for email, phone, address validation, compliance screening, and fraud detection. Find the endpoint you need and start integrating in minutes.
What do you want to do?
Verify an email
Check if an email address is valid and deliverable
Verify a phone number
Validate phone numbers with HLR/MNP checks
Check TPS status
Screen numbers against the TPS register
Detect IP fraud
Identify suspicious or fraudulent IP addresses
Run multiple checks
Combine multiple validations in one request
Continue to authorisation
Start with API authentication before exploring endpoint guides
Quick-Start API
Try a live example from the full API catalog
Switch endpoints, copy the cURL request, and jump into the playground when you want to experiment.
Campaigns are not available for this endpoint yet.
No campaigns configured yet.
Set up a campaign
to add one to generated API requests.
New to Provero? Start with authorisation, then set up campaigns if you want request-level reporting by project, customer, or import source.
Authorisation
All endpoints are secured and require authentication via a Bearer token. You must include your API key in the
Authorization header of every request you make. You can create API tokens in your settings page.Headers
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Code Examples
import requests
url = "https://api.provero.io/api/user"
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json"
"Accept": "application/json"
}
response = requests.get(url, headers=headers)
print(response.status_code)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/user",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;const headers = new Headers();
headers.append("Authorization", "Bearer REPLACE_WITH_API_TOKEN");
headers.append("Content-Type", "application/json");
headers.append("Accept", "application/json");
fetch("https://api.provero.io/api/user", {
method: "GET",
headers: headers,
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));curl -X GET https://api.provero.io/api/user \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json"Response Examples
Error – Missing or Invalid Token
{
"error": {
"code": "401",
"message": "Unauthenticated. Please provide a valid API key."
}
}Response Body
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
error.code |
string |
401 | Yes | HTTP status code for the error. |
error.message |
string |
Unauthenticated. Please provide a valid API key. | Yes | A message describing why authentication failed. |
Campaigns
Attach a campaign to any API request that creates a validation log so reports stay grouped by project, customer, import source, or workflow.
Set Up First
Create and manage campaigns in Settings → Campaigns before sending them in API requests.
Supported Endpoints
Campaigns are supported on /api/validate/*, /api/fraud-check/*, and /api/validate/multiple.
What To Send
Send either the campaign slug or UUID. In most integrations, the slug is the easier option to read and maintain.
Multi-Validation
For /api/validate/multiple, keep campaign at the top level of the payload so it applies across the nested checks in that request.
If you omit campaign, the request still runs normally. The resulting validation log just won’t be attached to a named campaign in reporting.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
campaign |
string |
No | Optional campaign identifier. Send either the campaign slug or UUID from Settings → Campaigns. |
Request Body example (JSON)
{
"campaign": "q1-lead-list",
"email": "test@example.com"
}Code Examples
import requests
payload = {
"campaign": "q1-lead-list",
"email": "test@example.com"
}
url = "https://api.provero.io/api/validate/email"
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$payload = [
"campaign" => "q1-lead-list",
"email" => "test@example.com",
];
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/validate/email",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const payload = {
campaign: "q1-lead-list",
email: "test@example.com"
};
fetch("https://api.provero.io/api/validate/email", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify(payload)
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));curl -X POST https://api.provero.io/api/validate/email \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"campaign": "q1-lead-list",
"email": "test@example.com"
}'Response Examples
Error - Campaign Not Found
{
"message": "No query results for model [App\\Models\\Campaign]."
}Response Body
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
No query results for model [App\Models\Campaign]. | Yes | Returned when the supplied campaign slug or UUID does not exist for the authenticated account. |
The Email Validation API allows you to validate email addresses, check their deliverability, and assess the risk associated with them among other detailed information.
Endpoint
POST
https://api.provero.io/api/validate/emailHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
Yes | The email to be validated. |
Request Body example (JSON)
{
"email": "test@example.com"
}Code Examples
import requests
userEmail = "REPLACE_WITH_EMAIL"
url = "https://api.provero.io/api/validate/email"
payload = {"email": userEmail}
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$userEmail = "REPLACE_WITH_EMAIL";
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/validate/email",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode(["email" => $userEmail]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const userEmail = "REPLACE_WITH_EMAIL";
fetch("https://api.provero.io/api/validate/email", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify({ email: userEmail })
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));userEmail="REPLACE_WITH_EMAIL"
curl -X POST https://api.provero.io/api/validate/email \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "{\"email\": \"$userEmail\"}"Response Examples
Success
{
"emailAddress": "user@example.com",
"isSyntaxValid": true,
"isMailboxDeliverable": false,
"isCatchAll": false,
"typoSuggestion": "user@example.com",
"isDisposable": false,
"isRoleBased": false,
"riskLevel": "HIGH",
"failureReason": "missingMX"
}Application Error
{
"requestError": {
"serviceException": {
"messageId": "Error message",
"code": "400"
}
}
}Payment Required - Insufficient Balance
{
"message": "Insufficient balance for validation request.",
"service": "email",
"required_amount": "0.0060000000",
"current_balance": "0.0000000000"
}Validation Error - Email Not Provided
{
"message": "The email field is required.",
"errors": {
"email": [
"The email field is required."
]
}
}Validation Error - Invalid Email Format
{
"message": "The email field must be a valid email address.",
"errors": {
"email": [
"The email field must be a valid email address."
]
}
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
emailAddress |
string |
user@example.com | Yes | The target email address that was looked up. |
isSyntaxValid |
boolean |
1 | Yes | Checks if the email address is formatted correctly and valid. |
isMailboxDeliverable |
boolean |
Yes | Determines if the email address is deliverable. | |
isCatchAll |
boolean |
Yes | Indicates whether the email address domain is configured as catch-all. | |
typoSuggestion |
string |
user@example.com | Yes | Provides a suggested alternate email address that closely resembles the input and may be valid. |
isDisposable |
boolean |
Yes | Checks if the email address is temporary or disposable. | |
isRoleBased |
boolean |
Yes | Checks if the email address is for a team or department. | |
riskLevel |
string |
HIGH | Yes | Indicates the risk status of an email address. HIGH, MEDIUM, LOW, or UNKNOWN. |
failureReason |
string |
missingMX | No | Reason is provided when validMailbox status is unknown. |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
The email field is required. | No | Top-level error message returned on validation failure, insufficient balance, or other request errors. |
errors |
object |
{"email": ["The email field is required."]} | No | Object of validation services with validation failures. |
requestError |
object |
{"serviceException": {"messageId": "Error message", "code": "400"}} | No | Object containing service exceptions for application errors. |
service |
string |
No | Service alias returned with a 402 insufficient-balance response. | |
required_amount |
string |
0.0060000000 | No | Credit amount required to process the validation request. |
current_balance |
string |
0.0000000000 | No | Current available balance at the time the request was rejected. |
Phone - Format
Phone - Format provides a lightweight phone validation check without requiring an HLR lookup. It returns number validity, country details, standard number formats, and assigned network data when available from number range metadata.
Endpoint
POST
https://api.provero.io/api/validate/phone-basicHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
phone |
string |
Yes | The phone number to validate. International format with country code is recommended. |
Request Body example (JSON)
{
"phone": "+447700900123"
}Code Examples
import requests
userPhone = "REPLACE_WITH_PHONE"
url = "https://api.provero.io/api/validate/phone-basic"
payload = {"phone": userPhone}
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$userPhone = "REPLACE_WITH_PHONE";
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/validate/phone-basic",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode(["phone" => $userPhone]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const userPhone = "REPLACE_WITH_PHONE";
fetch("https://api.provero.io/api/validate/phone-basic", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify({ phone: userPhone })
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));userPhone="REPLACE_WITH_PHONE"
curl -X POST https://api.provero.io/api/validate/phone-basic \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "{\"phone\": \"$userPhone\"}"Response Examples
Success
{
"input": "+447700900123",
"valid": true,
"country": {
"code": "GB",
"name": "United Kingdom of Great Britain and Northern Ireland",
"callingCode": "44"
},
"format": {
"e164": "+447700900123",
"international": "+44 7700 900123",
"national": "07700 900123",
"rfc3966": "tel:+44-7700-900123"
},
"assignedNetwork": "Vodafone UK"
}Validation Error - Phone Not Provided
{
"message": "The phone field is required.",
"errors": {
"phone": [
"The phone field is required."
]
}
}Validation Error - Invalid Phone
{
"message": "The phone provided is invalid.",
"errors": {
"phone": [
"The phone provided is invalid."
]
}
}Payment Required - Insufficient Balance
{
"message": "Insufficient balance for validation request.",
"service": "basic_phone",
"required_amount": "0.0060000000",
"current_balance": "0.0000000000"
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
input |
string |
+447700900123 | Yes | The raw phone number submitted by the client. |
valid |
boolean |
1 | Yes | Whether the number is considered valid by the phone verification service. |
country |
object |
{"code":"GB","name":"United Kingdom of Great Britain and Northern Ireland","callingCode":"44"} | Yes | Resolved country details for the phone number when available. |
country.code |
string |
GB | No | ISO 3166-1 alpha-2 country code. |
country.name |
string |
United Kingdom of Great Britain and Northern Ireland | No | Resolved country name. |
country.callingCode |
string |
44 | No | International calling code for the resolved country. |
format |
object |
{"e164":"+447700900123","international":"+44 7700 900123","national":"07700 900123","rfc3966":"tel:+44-7700-900123"} | Yes | Common formatted versions of the submitted number. |
format.e164 |
string |
+447700900123 | No | Canonical E.164 representation. |
format.international |
string |
+44 7700 900123 | No | Human-readable international format. |
format.national |
string |
07700 900123 | No | National display format. |
format.rfc3966 |
string |
tel:+44-7700-900123 | No | RFC3966 telephone URI representation. |
assignedNetwork |
string |
Vodafone UK | No | Carrier/network label from libphonenumber range data when available. |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
The phone field is required. | No | Top-level error message returned on validation failure or insufficient balance. |
errors |
object |
{"phone":["The phone field is required."]} | No | Object of per-field validation errors. |
service |
string |
basic_phone | No | Service alias returned with a 402 insufficient-balance response. |
required_amount |
string |
0.0060000000 | No | Credit amount required to process the validation request. |
current_balance |
string |
0.0000000000 | No | Current available balance at the time the request was rejected. |
Phone - HLR
Phone - HLR returns a simple HLR summary by default: whether the number is live, dead, or out of network, plus the current and original network. Set
detailed=true when you want the full HLR response instead.- HLR: Database checks that validate if a number is active and identify its operator.
- MNP: Process to determine if a number has been ported and confirm the current carrier.
- Delivery: Mechanism for routing messages or calls to the correct destination and confirming their status.
Endpoint
POST
https://api.provero.io/api/validate/phoneHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
phone |
string |
Yes | The phone number to be validated. |
roaming |
boolean |
No | Set to "1" or "true" to include roaming checks. |
msisdn |
boolean |
No | When set to true (default), the MSISDN must be a valid E.164 number. When set to false, non-canonical MSISDN formats may be accepted for routing determination only, including numbers containing a duplicated country code. |
route |
string |
No | Accepted values:
|
detailed |
boolean |
No | Optional flag to return the full HLR payload. Omit it, or send false, to receive the default easy summary response. |
Request Body example (JSON)
{
"phone": "+441302778473",
"roaming": true,
"msisdn": true,
"route": "standard",
"detailed": "true"
}Code Examples
import requests
userPhone = "REPLACE_WITH_PHONE"
roaming = "1"
route = "standard"
url = "https://api.provero.io/api/validate/phone"
payload = {"phone": userPhone, "roaming": roaming, "route": route}
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$userPhone = "REPLACE_WITH_PHONE";
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/validate/phone",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode(["phone" => $userPhone, "roaming" => true]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const userPhone = "REPLACE_WITH_PHONE";
fetch("https://api.provero.io/api/validate/phone", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify({ phone: userPhone, roaming: true })
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));userPhone="REPLACE_WITH_PHONE"
curl -X POST https://api.provero.io/api/validate/phone \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "{\"phone\": \"$userPhone\", \"roaming\": true}"Response Examples
Success
{
"results": [
{
"to": "+1234567890",
"status": "Live",
"live": true,
"dead": false,
"outOfNetwork": false,
"currentNetwork": "Example",
"originalNetwork": "Example"
}
]
}Detailed Success (detailed: true, route: standard)
{
"results": [
{
"to": "+1234567890",
"mccMnc": "123456",
"imsi": "",
"originalNetwork": {
"networkName": "Example",
"networkPrefix": "234",
"countryName": "Example",
"countryPrefix": "1",
"networkId": ""
},
"status": {
"groupId": 3,
"groupName": "DELIVERED",
"id": 5,
"name": "DELIVERED_TO_HANDSET",
"description": "Message delivered to handset"
},
"error": {
"groupId": 0,
"groupName": "Ok",
"id": 0,
"name": "DELIVERED_TO_HANDSET",
"description": "No Error.",
"permanent": false
}
}
]
}Detailed Success (detailed: true, route: detailed) - Roaming Requested
{
"results": [
{
"to": "+1234567890",
"mccMnc": "123456",
"imsi": "",
"originalNetwork": {
"networkName": "Example",
"networkPrefix": "234",
"countryName": "Example",
"countryPrefix": "1",
"networkId": ""
},
"status": {
"groupId": 3,
"groupName": "DELIVERED",
"id": 5,
"name": "DELIVERED_TO_HANDSET",
"description": "Message delivered to handset"
},
"roaming": true,
"roamingNetwork": {
"networkName": "Example",
"networkPrefix": "",
"countryName": "Example",
"countryPrefix": "1",
"networkId": ""
},
"ported": true,
"portedNetwork": {
"networkName": "Example",
"networkPrefix": "234",
"countryName": "Example",
"countryPrefix": "1",
"networkId": ""
},
"error": {
"groupId": 0,
"groupName": "Ok",
"id": 0,
"name": "DELIVERED_TO_HANDSET",
"description": "No Error.",
"permanent": false
}
}
]
}Detailed Success (detailed: true, route: detailed) - Roaming Not Requested
{
"results": [
{
"to": "+1234567890",
"mccMnc": "123456",
"imsi": "",
"originalNetwork": {
"networkName": "Example",
"networkPrefix": "234",
"countryName": "Example",
"countryPrefix": "1",
"networkId": ""
},
"status": {
"groupId": 3,
"groupName": "DELIVERED",
"id": 5,
"name": "DELIVERED_TO_HANDSET",
"description": "Message delivered to handset"
},
"ported": true,
"portedNetwork": {
"networkName": "Example",
"networkPrefix": "234",
"countryName": "Example",
"countryPrefix": "1",
"networkId": ""
},
"error": {
"groupId": 0,
"groupName": "Ok",
"id": 0,
"name": "DELIVERED_TO_HANDSET",
"description": "No Error.",
"permanent": false
}
}
]
}Detailed Success (detailed: true, route: detailed) - Invalid phone number
{
"results": [
{
"to": "+1234567890",
"mccMnc": "123456",
"imsi": "",
"originalNetwork": {
"networkName": "Example",
"networkPrefix": "234",
"countryName": "Example",
"countryPrefix": "1",
"networkId": ""
},
"status": {
"groupId": 1,
"groupName": "Handset errors",
"id": 27,
"name": "UNDELIVERABLE_NOT_DELIVERED",
"description": "Absent Subscriber"
},
"ported": false,
"error": {
"groupId": 1,
"groupName": "Handset errors",
"id": 27,
"name": "UNDELIVERABLE_NOT_DELIVERED",
"description": "Absent Subscriber",
"permanent": false
}
}
]
}Application Error
{
"requestError": {
"serviceException": {
"messageId": "Error message",
"code": "400"
}
}
}Payment Required - Insufficient Balance
{
"message": "Insufficient balance for validation request.",
"service": "phone",
"required_amount": "0.0060000000",
"current_balance": "0.0000000000"
}Validation Error - Phone Not Provided
{
"message": "The phone field is required.",
"errors": {
"phone": [
"The phone field is required."
]
}
}Validation Error - Phone Number Too Long
{
"message": "The phone field must not be greater than 15 characters.",
"errors": {
"phone": [
"The phone field must not be greater than 15 characters."
]
}
}Validation Error - Phone Number Too Short
{
"message": "The phone field must be at least 10 characters.",
"errors": {
"phone": [
"The phone field must be at least 10 characters."
]
}
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
to |
string |
+1234567890 | Yes | The target phone number that was looked up. |
mccMnc |
string |
123456 | Yes | Concatenated Mobile Country + Network Code (MCC + MNC). |
imsi |
string |
123456 | Yes | Same as mccMnc. |
originalNetwork.networkName |
string |
Phone carrier LTD | Yes | Name of the original network operator. |
originalNetwork.networkPrefix |
string |
234 | Yes | Prefix used by the original network. |
originalNetwork.countryName |
string |
Canada | Yes | Name of the country where the original network is based. |
originalNetwork.countryPrefix |
string |
1 | Yes | International dialing prefix. |
originalNetwork.networkId |
string |
Yes | Internal identifier; may be empty. | |
ported |
boolean |
true | Yes | Whether the number has been ported to another network. |
portedNetwork.networkName |
string |
Red phone carrier LTD | No | Name of the ported (current) network. |
portedNetwork.networkPrefix |
string |
234 | No | Prefix used by the ported network. |
portedNetwork.countryName |
string |
Canada | No | Country of the ported network. |
portedNetwork.countryPrefix |
string |
1 | No | Dialing prefix. |
portedNetwork.networkId |
string |
No | Internal ID; may be empty. | |
roaming |
boolean |
true | No | Whether the device is roaming (connected to foreign network). |
roamingNetwork.networkName |
string |
T-Mobile | No | Visited network name. |
roamingNetwork.networkPrefix |
string |
425 | No | Prefix used by roaming network. |
roamingNetwork.countryName |
string |
US | No | Roaming country name. |
roamingNetwork.countryPrefix |
string |
1 | No | Roaming country dialing prefix. |
roamingNetwork.networkId |
string |
No | Roaming network internal ID. | |
status.groupId |
integer |
3 | Yes | ID representing the status group. |
status.groupName |
string |
DELIVERED | Yes | High-level classification (e.g., “DELIVERED”). |
status.id |
integer |
5 | Yes | Specific status ID. |
status.name |
string |
DELIVERED_TO_HANDSET | Yes | Specific status name. |
status.description |
string |
Message delivered to handset | Yes | Human-readable explanation of status. |
error.groupId |
integer |
0 | Yes | Error group ID. |
error.groupName |
string |
Ok | Yes | Error group name. |
error.id |
integer |
0 | Yes | Error code. |
error.name |
string |
NO_ERROR | Yes | Error name if any. |
error.description |
string |
Valid Query | Yes | Explanation of the error. |
error.permanent |
boolean |
false | Yes | True/false if error is permanent. |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
The phone field is required. | No | Top-level error message returned on validation failure, insufficient balance, or other request errors. |
errors |
object |
{"phone": ["The phone field is required."]} | No | Object of validation services with validation failures. |
requestError |
object |
{"serviceException": {"messageId": "Error message", "code": "400"}} | No | Object containing service exceptions for application errors. |
service |
string |
phone | No | Service alias returned with a 402 insufficient-balance response. |
required_amount |
string |
0.0060000000 | No | Credit amount required to process the validation request. |
current_balance |
string |
0.0000000000 | No | Current available balance at the time the request was rejected. |
Service Specific Error Codes
| ID | Error | Group ID | Group Name | Always Present | Description |
|---|---|---|---|---|---|
0 |
NO_ERROR |
0 | Ok | No | Valid Query |
1 |
EC_UNKNOWN_SUBSCRIBER |
1 | Handset errors | Yes | The phone number provided is not linked to a known user profile. |
5 |
NUMBER_MISSING_FROM_NETWORK_REGISTRY |
1 | Handset errors | No | This number is missing from our extended network datasets. |
5 |
UK_NUMBER_TRANSFER_RECORD_NOT_LOCATED |
1 | Handset errors | Yes | No transfer or porting history was found for this UK number. |
5 |
NUMBER_UNLISTED_IN_CURRENT_DATABASE |
1 | Handset errors | No | We could not locate this number in our records. Please verify and retry. |
5 |
EC_UNIDENTIFIED_SUBSCRIBER |
1 | Handset errors | No | The subscriber details are not recognized within our systems. |
6 |
EC_ABSENT_SUBSCRIBER_SM |
1 | Handset errors | No | The device was unreachable. User is not currently available on this network. |
32 |
EC_SM_DELIVERY_FAILURE |
1 | Handset errors | No | An error occurred while attempting to deliver the message. |
34 |
EC_SYSTEM_FAILURE |
1 | Handset errors | No | An internal error was encountered while processing. |
255 |
REJECTED_NETWORK |
1 | Handset errors | Yes | The number is outside the valid network range or is currently unassigned. |
255 |
GENERAL_ROUTING_FAULT |
1 | Handset errors | No | A routing problem occurred while directing the request to its destination. |
256 |
TARGET_CARRIER_OVERLOAD_DETECTED |
1 | Handset errors | No | Carrier is currently handling too many requests. Please try again soon. |
500 |
TARGET_CARRIER_CONNECTIVITY_FAULT |
1 | Handset errors | No | A connectivity problem occurred with the carrier. |
500 |
EC_PROVIDER_GENERAL_ERROR |
1 | Handset errors | No | A system or equipment issue prevented successful completion of this request. |
502 |
EC_NO_RESPONSE |
1 | Handset errors | No | No response received from the destination network in the expected time. |
502 |
EXTERNAL_LOOKUP_FAILED_NETWORK_REPLY_LOGGED |
1 | Handset errors | No | Lookup failed on an external system. A reply was logged. |
502 |
TARGET_CARRIER_MOMENTARILY_INACCESSIBLE |
1 | Handset errors | No | The carrier’s network is not reachable at the moment. Please try again later. |
502 |
EXTERNAL_GATEWAY_RESPONSE_ISSUE |
1 | Handset errors | No | An external network gateway provided an unexpected response. |
1 |
EC_UNKNOWN_SUBSCRIBER |
2 | User errors | Yes | Unknown Subscriber |
5 |
REGISTERED_NAME_DISCREPANCY_DETECTED |
2 | User errors | Yes | Name submitted does not match our records. |
6 |
EC_ABSENT_SUBSCRIBER_SM |
2 | User errors | No | Phone Switched Off. |
9 |
VALIDATION_TOKEN_MISSING |
2 | User errors | Yes | Validation token expired. Please request a new one. |
9 |
UNDELIVERABLE_NOT_DELIVERED |
2 | Undeliverable | Yes | Wrong number length or format. |
9 |
EC_SYSTEM_FAILURE |
2 | User errors | No | Subscriber Error (Temporary). |
9 |
EC_SYSTEM_FAILURE |
2 | User errors | No | Subscriber Error. |
9 |
EC_ILLEGAL_SUBSCRIBER |
2 | User errors | Yes | Subscriber is blocked or restricted from receiving messages. |
9 |
VALIDATION_TOKEN_MISSING |
2 | User errors | Yes | Missing validation token in request. |
9 |
VALIDATION_TOKEN_TIMEOUT |
2 | User errors | No | Validation token does not match this service. |
9 |
VALIDATION_TOKEN_SERVICE_MISMATCH |
2 | User errors | Yes | Name does not align with records for this number. |
9 |
EC_SYSTEM_FAILURE |
2 | User errors | No | Live Status Unavailable. |
31 |
EC_SUBSCRIBER_BUSY_FOR_MT_SMS |
2 | User errors | No | Subscriber is currently busy and cannot receive messages. |
31 |
REGION_PREFIX_UNRECOGNIZED |
2 | User errors | Yes | The region or country code is unrecognized. Check the number format. |
323 |
VERIFICATION_PATHWAY_UNDEFINED |
2 | User errors | Yes | The request could not be completed due to missing or misconfigured service route. |
507 |
REGISTERED_NAME_DISCREPANCY_DETECTED |
2 | User errors | Yes | Name does not exist. Review entered details. |
5 |
DELIVERED_TO_HANDSET |
3 | DELIVERED | No | The message has reached the recipient’s device successfully. |
15 |
NO_NETWORK_RESPONSE |
4 | Expired | No | No network response was received during validation. |
8 |
EC_ROAMING_NOT_ALLOWED |
5 | Rejected | No | Roaming not permitted for this number or country. |
9 |
ACCOUNT_CREDENTIALS_INSUFFICIENT |
5 | Rejected | Yes | This account does not have permission to access this feature. |
11 |
EC_TELESERVICE_NOT_PROVISIONED |
5 | Rejected | No | Telephone service not active for this number. |
11 |
EC_TELESERVICE_NOT_PROVISIONED |
5 | Rejected | Yes | Teleservice Not Provisioned. |
13 |
EC_CALL_BARRED |
5 | Rejected | No | Call Barred. |
21 |
EC_FACILITY_NOT_SUPPORTED |
5 | Rejected | No | Requested service is not supported. |
21 |
EC_FACILITY_NOT_SUPPORTED |
5 | Rejected | No | The requested facility is not supported. |
32 |
TRAFFIC_QUOTA_EXCEEDED |
5 | Rejected | No | Rate limit exceeded. Please try again later. |
323 |
INTERNATIONAL_ROUTE_NOT_SUPPORTED |
5 | Rejected | Yes | International validation not supported for this country. |
Address - UK Postcode
This endpoint verifies UK postcodes and returns structured UK address details from postcode data.
To use this service, you must configure your UK postcode provider account, password, and API key in Settings.
It is not a full global address validation service. A broader Address Verification endpoint will be introduced separately.
To use this service, you must configure your UK postcode provider account, password, and API key in Settings.
It is not a full global address validation service. A broader Address Verification endpoint will be introduced separately.
Endpoint
POST
https://api.provero.io/api/validate/uk-postcodeHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
postcode |
string |
Yes | Postcode to be validated. |
Request Body example (JSON)
{
"postcode": "string"
}Code Examples
import requests
postcode = "LS18 5SB"
url = "https://api.provero.io/api/validate/uk-postcode"
payload = {"postcode": postcode}
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$postcode = "LS18 5SB";
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/validate/uk-postcode",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode([
"postcode" => $postcode
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const postcode = "LS18 5SB";
fetch("https://api.provero.io/api/validate/uk-postcode", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify({ postcode })
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));postcode="LS18 5SB"
curl -X POST https://api.provero.io/api/validate/uk-postcode \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "{\"postcode\": \"$postcode\"}"Response Examples
Success
{
"valid": true,
"postcode": "LS18 5SB",
"address": {
"Address1": "Brownberrie Lane",
"Address2": "Horsforth",
"Address3": "",
"Address4": "",
"Town": "Leeds",
"County": "West Yorkshire",
"Postcode": "LS18 5SB",
"PremiseData": "Old Ball||;||2;||4;||6;||8;||10;||12;||14;||16;||18;||20;||22;||24;||26;||28;||30;||32;||34;||36;||38;||40;||42;||44;||46;||48;||50;||52;||54;"
}
}Application Error
{
"requestError": {
"serviceException": {
"messageId": "Error message",
"code": "400"
}
}
}Payment Required - Insufficient Balance
{
"message": "Insufficient balance for validation request.",
"service": "address",
"required_amount": "0.0060000000",
"current_balance": "0.0000000000"
}Validation Error - Postcode Not Provided
{
"message": "The postcode field is required.",
"errors": {
"postcode": [
"The postcode field is required."
]
}
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
postcode |
string |
LS18 5SB | Yes | The request postcode. |
valid |
boolean |
true | Yes | Indicates whether the postcode is valid |
address |
object |
{"Address1":"Brownberrie Lane","Address2":"Horsforth","Address3":"","Address4":"","Town":"Leeds","County":"West Yorkshire","Postcode": "LS18 5SB","PremiseData": "Old Ball||;||2;||4;||6;||8;||10;||12;||14;||16;||18;||20;||22;||24;||26;||28;||30;||32;||34;||36;||38;||40;||42;||44;||46;||48;||50;||52;||54;"} | Yes | Breakdown of address into structured parts. |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
The postcode field is required. | No | Top-level error message returned on validation failure, insufficient balance, or other request errors. |
errors |
object |
{"postcode": ["The postcode field is required."]} | No | Object containing input validation errors. |
requestError |
object |
{"serviceException": {"messageId": "Error message", "code": "400"}} | No | Returned when an internal service exception occurs. |
service |
string |
address | No | Service alias returned with a 402 insufficient-balance response. |
required_amount |
string |
0.0060000000 | No | Credit amount required to process the validation request. |
current_balance |
string |
0.0000000000 | No | Current available balance at the time the request was rejected. |
Address - Global
COMING SOON!!!
The Address Verification API is reserved for a future global address validation and enrichment service.
This endpoint will be used for broader international address verification beyond UK postcode-only checks, including structured address validation and normalization for global coverage.
For UK postcode verification, please use the dedicated UK Postcode Verification endpoint.
The Address Verification API is reserved for a future global address validation and enrichment service.
This endpoint will be used for broader international address verification beyond UK postcode-only checks, including structured address validation and normalization for global coverage.
For UK postcode verification, please use the dedicated UK Postcode Verification endpoint.
Endpoint
POST
https://api.provero.io/api/validate/addressHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
address |
object |
No | Placeholder request body for the upcoming global address verification API. Final request fields are not yet defined. |
Request Body example (JSON)
{
"address": "London"
}Code Examples
import requests
url = "https://api.provero.io/api/validate/address"
payload = {
"address": {
"line1": "10 Downing Street",
"city": "London",
"postcode": "SW1A 2AA",
"country": "GB"
}
}
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$payload = [
"address" => [
"line1" => "10 Downing Street",
"city" => "London",
"postcode" => "SW1A 2AA",
"country" => "GB"
]
];
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/validate/address",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const payload = {
address: {
line1: "10 Downing Street",
city: "London",
postcode: "SW1A 2AA",
country: "GB"
}
};
fetch("https://api.provero.io/api/validate/address", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify(payload)
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));curl -X POST https://api.provero.io/api/validate/address \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"address": {
"line1": "10 Downing Street",
"city": "London",
"postcode": "SW1A 2AA",
"country": "GB"
}
}'Response Examples
Application Error - Not Implemented Yet
{
"message": "Address verification is not available yet. This endpoint is reserved for an upcoming release.",
"status": "not_implemented"
}Response Body
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
Address verification is not available yet. This endpoint is reserved for an upcoming release. | Yes | Placeholder message returned until the global address verification service is implemented. |
status |
string |
not_implemented | Yes | Placeholder status indicating the endpoint is reserved for a future release. |
TPS/CTPS Check
The TPS (Telephone Preference Service) Validation API checks whether a UK landline or mobile number is listed with either the official TPS or Corporate TPS (CTPS) registers. Use this to avoid calling users who have opted out of unsolicited sales and marketing contact.
Endpoint
POST
https://api.provero.io/api/validate/phone-tpsHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
phone |
string |
Yes | Phone number to check (in E.164 format, e.g. +441234567890) |
Request Body example (JSON)
{
"phone": "+441302778473"
}Code Examples
import requests
userPhone = "REPLACE_WITH_PHONE"
url = "https://api.provero.io/api/validate/phone-tps"
payload = {"phone": userPhone}
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$userPhone = "REPLACE_WITH_PHONE";
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/validate/phone-tps",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode(["phone" => $userPhone]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const userPhone = "REPLACE_WITH_PHONE";
fetch("https://api.provero.io/api/validate/phone-tps", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify({ phone: userPhone })
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));userPhone="REPLACE_WITH_PHONE"
curl -X POST https://api.provero.io/api/validate/phone-tps \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "{\"phone\": \"$userPhone\"}"Response Examples
Success
{
"phone": "tel:+44-1234-567890",
"result": false
}General Error
{
"requestError": {
"serviceException": {
"messageId": "Error message",
"code": "400"
}
}
}Payment Required - Insufficient Balance
{
"message": "Insufficient balance for validation request.",
"service": "tps",
"required_amount": "0.0060000000",
"current_balance": "0.0000000000"
}Error - Wrong Region
{
"message": "The provided phone number is not valid for the GB region.",
"errors": {
"phone": [
"The provided phone number is not valid for the GB region."
]
}
}Validation Error - Phone Not Provided
{
"message": "The phone field is required.",
"errors": {
"phone": [
"The phone field is required."
]
}
}Validation Error - Phone Invalid
{
"message": "The provided phone number is invalid",
"errors": {
"phone": [
"The provided phone number is invalid"
]
}
}Validation Error - Phone Too Short
{
"message": "The string supplied is too short to be a phone number.",
"errors": {
"phone": [
"The string supplied is too short to be a phone number."
]
}
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
result.status |
string |
TPS | Yes | `TPS`, `CTPS`, or `UNLISTED` depending on registry status |
result.type |
string |
mobile | Yes | The type of number detected (e.g. `mobile`, `landline`) |
result.operator |
string |
Vodafone | No | Detected carrier/operator for the number |
result.date |
string |
2024-03-22 | No | Date the number was registered on TPS/CTPS (if applicable) |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
The phone field is required. | No | Top-level error message for validation issues, insufficient balance, or other request errors |
errors |
object |
{"phone": ["The phone field is required."]} | No | Details of validation field errors |
requestError |
object |
{"serviceException": {"messageId": "Error message", "code": "400"}} | No | Object returned for application-level service errors |
service |
string |
tps | No | Service alias returned with a 402 insufficient-balance response |
required_amount |
string |
0.0060000000 | No | Credit amount required to process the validation request |
current_balance |
string |
0.0000000000 | No | Current available balance at the time the request was rejected |
Name Screening
The Name Screening API validates whether a submitted name has a plausible personal-name format and checks the full value plus each individual name part against the active blocked-term database.
Send either a single
Send either a single
full_name value or a first_name and last_name pair.Endpoint
POST
https://api.provero.io/api/fraud-check/nameHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
full_name |
string |
No | The full name to screen, including first, middle, and last names where available. |
first_name |
string |
No | The first name to use when you prefer split-name input. Must be sent together with last_name. |
last_name |
string |
No | The last name to use when you prefer split-name input. Must be sent together with first_name. |
Request Body example (JSON)
{
"full_name": "John Doe",
"first_name": "string",
"last_name": "string"
}Code Examples
import requests
full_name = "John Doe"
url = "https://api.provero.io/api/fraud-check/name"
payload = {"full_name": full_name}
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$fullName = "John Doe";
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/fraud-check/name",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode([
"full_name" => $fullName
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const fullName = "John Doe";
fetch("https://api.provero.io/api/fraud-check/name", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify({ full_name: fullName })
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));full_name="John Doe"
curl -X POST https://api.provero.io/api/fraud-check/name \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "{\"full_name\": \"$full_name\"}"Response Examples
Success
{
"fullName": "John Doe",
"type": "full_name",
"isValid": true,
"isProfane": false,
"riskLevel": "LOW",
"notes": "Name passed heuristic screening."
}Validation Error - Missing Name
{
"message": "The full_name field is required when first_name and last_name are not provided.",
"errors": {
"full_name": [
"The full_name field is required when first_name and last_name are not provided."
]
}
}Payment Required - Insufficient Balance
{
"message": "Insufficient balance for validation request.",
"service": "name",
"required_amount": "0.0060000000",
"current_balance": "0.0000000000"
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
fullName |
string |
John Doe | Yes | The validated full name. |
type |
string |
full_name | Yes | The screening mode used for the submitted name. |
isValid |
boolean |
true | Yes | Whether the name passed format and blocked-term screening. |
isProfane |
boolean |
false | Yes | Indicates whether the name contains any profanity. |
riskLevel |
string |
LOW | Yes | A risk rating of the name (LOW, MEDIUM, HIGH, UNKNOWN). |
notes |
string |
Name passed heuristic screening. | No | Additional metadata or validation observations. |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
The full_name field is required when first_name and last_name are not provided. | No | Top-level error message returned on validation failure or insufficient balance. |
errors |
object |
{"full_name": ["The full_name field is required when first_name and last_name are not provided."]} | No | Object containing input validation errors. |
service |
string |
name | No | Service alias returned with a 402 insufficient-balance response. |
required_amount |
string |
0.0060000000 | No | Credit amount required to process the validation request. |
current_balance |
string |
0.0000000000 | No | Current available balance at the time the request was rejected. |
IP Fraud Detection
This endpoint performs IP fraud detection by evaluating indicators such as proxies, VPNs, bots, TOR nodes, device fingerprints, and other markers. It returns a detailed fraud risk profile.
Endpoint
POST
https://api.provero.io/api/fraud-check/ipHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
ip |
string |
Yes | The IP address to be validated. |
user_agent |
string |
No | User-Agent header string of the client. |
user_language |
string |
No | User language country code (e.g., "en"). |
Request Body example (JSON)
{
"ip": "8.8.8.8",
"user_agent": "Mozilla/5.0",
"user_language": "en"
}Code Examples
import requests
payload = {
"ip": "0.0.0.0", # Replace with users IP address
"user_agent": "REPLACE_WITH_USER_AGENT", # Example: "Mozilla/5.0 (...)"
"user_language": "en" # Language code e.g. "en" for English
}
url = "https://api.provero.io/api/fraud-check/ip"
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$payload = [
"ip" => "0.0.0.0", // Replace with clients IP address
"user_agent" => "REPLACE_WITH_USER_AGENT", // Example: "Mozilla/5.0 (...)"
"user_language" => "en" // Language code e.g. "en" for English
];
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/fraud-check/ip",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const payload = {
ip: "0.0.0.0", // Replace with clients IP address
user_agent: "REPLACE_WITH_USER_AGENT", // Example: "Mozilla/5.0 (...)"
user_language: "en" // Language code e.g. "en" for English
};
fetch("https://api.provero.io/api/fraud-check/ip", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify(payload)
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));curl -X POST https://api.provero.io/api/fraud-check/ip \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"ip": "0.0.0.0", # Replace with clients IP address
"user_agent": "REPLACE_WITH_USER_AGENT", # Example: "Mozilla/5.0 (...)"
"user_language": "en" # Language code e.g. "en" for English
}'Response Examples
Success
{
"message": "IP fraud check passed",
"result": {
"value": "127.0.0.1",
"proxy": true,
"isp": "Reserved",
"organization": "Reserved",
"asn": "3",
"host": "localhost",
"countryCode": "N/A",
"city": "N/A",
"region": "N/A",
"isCrawler": "",
"connectionType": "Premium required.",
"latitude": "0",
"longitude": "0",
"zipCode": "N/A",
"timezone": "",
"vpn": true,
"tor": false,
"activeVpn": false,
"activeTor": false,
"recentAbuse": true,
"abuseVelocity": "Premium required.",
"botStatus": true,
"mobile": false,
"fraudScore": 100,
"highRiskAttacks": null,
"sharedConnection": null,
"dynamicConnection": null,
"securityScanner": null,
"trustedNetwork": null,
"operatingSystem": "Mac 10.15",
"browser": "Chrome 136.0",
"deviceModel": "N/A",
"deviceBrand": "Apple",
"frequentAbuser": null
}
}Application Error
{
"requestError": {
"serviceException": {
"messageId": "Error message",
"code": "400"
}
}
}Payment Required - Insufficient Balance
{
"message": "Insufficient balance for validation request.",
"service": "ip-fraud",
"required_amount": "0.0200000000",
"current_balance": "0.0000000000"
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
IP fraud check passed | Yes | Top-level message returned when the fraud assessment completes successfully. |
result |
object |
{"value":"127.0.0.1","proxy":true,"fraudScore":100} | Yes | Fraud intelligence payload describing the submitted IP address and related risk signals. |
result.value |
string |
127.0.0.1 | Yes | The IP address evaluated by the fraud detection service. |
result.proxy |
boolean |
1 | Yes | Whether the IP is identified as a proxy. |
result.isp |
string |
Reserved | Yes | Internet service provider associated with the IP. |
result.organization |
string |
Reserved | Yes | Organization attributed to the IP address. |
result.asn |
string |
3 | Yes | Autonomous system number associated with the IP. |
result.host |
string |
localhost | No | Reverse-DNS or host label when one is available. |
result.countryCode |
string |
N/A | Yes | Country code resolved for the IP address. |
result.city |
string |
N/A | No | Resolved city for the IP address when available. |
result.region |
string |
N/A | No | Resolved region, county, or state for the IP address when available. |
result.isCrawler |
string |
No | Crawler classification returned by the upstream provider when detected. | |
result.connectionType |
string |
Premium required. | No | Connection classification such as residential, corporate, or mobile when the provider exposes it. |
result.latitude |
string |
0 | No | Latitude associated with the IP address. |
result.longitude |
string |
0 | No | Longitude associated with the IP address. |
result.zipCode |
string |
N/A | No | Postal or ZIP code associated with the IP address when available. |
result.timezone |
string |
No | Timezone associated with the IP address when available. | |
result.vpn |
boolean |
1 | Yes | Whether the IP is associated with VPN usage. |
result.tor |
boolean |
Yes | Whether the IP is associated with the Tor network. | |
result.activeVpn |
boolean |
No | Whether the provider considers the VPN endpoint actively in use. | |
result.activeTor |
boolean |
No | Whether the provider considers the Tor endpoint actively in use. | |
result.recentAbuse |
boolean |
1 | No | Whether the IP has recent abuse reports. |
result.abuseVelocity |
string |
Premium required. | No | Provider-specific abuse intensity or rate indicator when available. |
result.botStatus |
boolean |
1 | No | Whether the IP/user-agent combination appears bot-like. |
result.mobile |
boolean |
No | Whether the IP is associated with a mobile network. | |
result.fraudScore |
integer |
100 | Yes | Provider fraud score indicating the relative level of risk. |
result.highRiskAttacks |
boolean|null |
No | Whether the IP is associated with high-risk attack patterns when the provider exposes that signal. | |
result.sharedConnection |
boolean|null |
No | Whether the IP is shared across many users when the provider exposes that signal. | |
result.dynamicConnection |
boolean|null |
No | Whether the IP is flagged as dynamically assigned when available. | |
result.securityScanner |
boolean|null |
No | Whether the IP is associated with security scanning activity. | |
result.trustedNetwork |
boolean|null |
No | Whether the provider classifies the network as trusted. | |
result.operatingSystem |
string |
Mac 10.15 | No | Operating system inferred from the submitted user agent when available. |
result.browser |
string |
Chrome 136.0 | No | Browser inferred from the submitted user agent when available. |
result.deviceModel |
string |
N/A | No | Device model inferred from the submitted user agent when available. |
result.deviceBrand |
string |
Apple | No | Device brand inferred from the submitted user agent when available. |
result.frequentAbuser |
boolean|null |
No | Whether the IP has been flagged as a frequent abuser when that signal is available. |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
requestError |
object |
{"serviceException": {"messageId": "Error message", "code": "400"}} | No | Returned when an internal application or request error occurs. |
message |
string |
Insufficient balance for validation request. | No | Top-level error message returned when the account does not have enough balance. |
service |
string |
ip-fraud | No | Service alias returned with a 402 insufficient-balance response. |
required_amount |
string |
0.0200000000 | No | Credit amount required to process the validation request. |
current_balance |
string |
0.0000000000 | No | Current available balance at the time the request was rejected. |
Breach Detection
The Breach Detection API checks if an email, username, phone number, domain, or password has been compromised in known data breaches.
It provides information on the breach source and the type of data exposed.
Password lookups: when
It provides information on the breach source and the type of data exposed.
Password lookups: when
type is password, send the full SHA-1 hash of the password as the value. Do not send the plaintext password. The API uses a partial-hash lookup approach so only a small portion of the hash is used for the upstream search, with the full match confirmed server-side.Endpoint
POST
https://api.provero.io/api/fraud-check/breachHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
type |
enum |
Yes | Accepted values: email, username, phone, domain, password. |
value |
string |
Yes | The actual data item you want to check for breach exposure. For type=password, this must be the full 40-character SHA-1 hash of the password, for example 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8. |
Request Body example (JSON)
{
"type": "string",
"value": "string"
}Code Examples
import requests
import hashlib
type = "email" # Replace with "email", "username", "phone", "domain", or "password"
raw_value = "support.provero.io" # Replace with the source value
value = raw_value
if type == "password":
value = hashlib.sha1(raw_value.encode("utf-8")).hexdigest().upper()
url = "https://api.provero.io/api/fraud-check/breach"
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json"
}
response = requests.post(url, headers=headers, json={"type": type, "value": value})
print(response.status_code)
print(response.text)<?php
$type = "email"; // Replace with "email", "username", "phone", "domain", or "password"
$rawValue = "support.provero.io"; // Replace with the source value
$value = $rawValue;
if ($type === "password") {
$value = strtoupper(sha1($rawValue));
}
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/fraud-check/breach",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode(['type' => $type, 'value' => $value]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const type = "email"; // Replace with "email", "username", "phone", "domain", or "password"
const rawValue = "support.provero.io"; // Replace with the source value
const apiToken = "REPLACE_WITH_API_TOKEN";
async function sha1Hex(value) {
if (!window.isSecureContext || !window.crypto || !window.crypto.subtle) {
throw new Error("SHA-1 hashing requires a secure browser context (HTTPS) with Web Crypto support.");
}
const data = new TextEncoder().encode(value);
const hashBuffer = await window.crypto.subtle.digest("SHA-1", data);
return Array.from(new Uint8Array(hashBuffer))
.map((byte) => byte.toString(16).padStart(2, "0"))
.join("")
.toUpperCase();
}
async function breachCheck(type, rawValue, apiToken) {
const value = type === "password" ? await sha1Hex(rawValue) : rawValue;
const response = await fetch("https://api.provero.io/api/fraud-check/breach", {
method: "POST",
headers: {
"Authorization": `Bearer ${apiToken}`,
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify({ type, value })
});
const payload = await response.json();
if (!response.ok) {
throw new Error(payload.message || "Breach detection request failed.");
}
return payload;
}
breachCheck(type, rawValue, apiToken)
.then((result) => {
console.log(result);
})
.catch((error) => {
console.error(error);
});type="email" # Replace with "email", "username", "phone", "domain", or "password"
raw_value="support.provero.io" # Replace with the source value
value="$raw_value"
if [ "$type" = "password" ]; then
value=$(printf '%s' "$raw_value" | shasum -a 1 | awk '{print toupper($1)}')
fi
curl -X POST https://api.provero.io/api/fraud-check/breach \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"type\": \"$type\", \"value\": \"$value\"}"Response Examples
Success
{
"value": "requested_value",
"type": "requested_type",
"leaks": [
{
"name": "Adobe",
"domain": "adobe.com",
"breachDate": "2013-10-04",
"description": "User profile and password hints were exposed."
}
]
}Application Error
{
"requestError": {
"serviceException": {
"messageId": "Error message",
"code": "400"
}
}
}Payment Required - Insufficient Balance
{
"message": "Insufficient balance for validation request.",
"service": "breach-detection",
"required_amount": "0.0060000000",
"current_balance": "0.0000000000"
}Validation Error - Type - Not Provided
{
"message": "Please provide a type.",
"errors": {
"email": [
"Please provide a type."
]
}
}Validation Error - Type - Invalid Value
{
"message": "Type must be one of email, username, phone, domain, password.",
"errors": {
"type": [
"Type must be one of email, username, phone, domain, password."
]
}
}Validation Error - Value - Not Provided
{
"message": "Please provide a value to search.",
"errors": {
"email": [
"Please provide a value to search."
]
}
}Validation Error - Email - Invalid Value
{
"message": "The value field must be a valid email address.",
"errors": {
"type": [
"The value field must be a valid email address."
]
}
}Validation Error - Phone - Invalid Value
{
"message": "The value should be a valid phone number.",
"errors": {
"value": [
"The value should be a valid phone number."
]
}
}Validation Error - Domain - Invalid Value
{
"message": "The value must be a valid domain.",
"errors": {
"type": [
"The value must be a valid domain."
]
}
}Validation Error - Password - Invalid Value
{
"message": "The value must be a valid 40-character SHA-1 hash.",
"errors": {
"value": [
"The value must be a valid 40-character SHA-1 hash."
]
}
}Validation Error - Unsupported Type
{
"message": "Type must be one of email, username, phone, domain, password.",
"errors": {
"type": [
"Type must be one of email, username, phone, domain, password."
]
}
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
type |
enum |
Yes | The type of data checked, matching the requests type parameter. |
|
value |
string |
support.provero.io | Yes | The actual data that was checked for breaches. |
leaks |
array |
[{"name":"Adobe","domain":"adobe.com","breachDate":"2013-10-04","description":"User profile and password hints were exposed."}] | Yes | An array of breach objects. Each object may include name, domain, breachDate, and description. Fields that are not available for a given breach type are returned as null. |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
The value field must be a valid IP address. | No | Top-level error message returned on validation failure, insufficient balance, or other request errors. |
errors |
object |
{"type": ["The value field must be a valid IP address."]} | No | Validation error details. |
requestError |
object |
{"serviceException": {"messageId": "Error message", "code": "400"}} | No | Application-level error response object. |
service |
string |
breach-detection | No | Service alias returned with a 402 insufficient-balance response. |
required_amount |
string |
0.0060000000 | No | Credit amount required to process the validation request. |
current_balance |
string |
0.0000000000 | No | Current available balance at the time the request was rejected. |
IP Geolocation
The IP Geolocation API provides insights about the country and city associated with an IP address, along with optional distance comparison to a user-provided address.
This can be used to flag unexpected or foreign leads without affecting lead acceptance decisions.
This can be used to flag unexpected or foreign leads without affecting lead acceptance decisions.
Endpoint
POST
https://api.provero.io/api/fraud-check/geoipHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
ip |
string |
Yes | The IP address to be validated. |
address |
string |
No | Optional address or postcode to calculate distance from IP location. Required if geoMatch is used. |
geoMatch |
boolean |
No | Enable matching between IP’s geolocation and the supplied address. |
Request Body example (JSON)
{
"ip": "8.8.8.8",
"address": "London",
"geoMatch": true
}Code Examples
import requests
ip = "0.0.0.0" # Replace with clients IP
address = "REPLACE_WITH_AN_ADDRESS" # Optional address for distance calculation
geoMatch = true # Enable geoMatch to compare IP location with address
url = "https://api.provero.io/api/fraud-check/geoip"
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
payload = {"ip": ip, "address": address, "geoMatch": geoMatch}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)<?php
$ip = "0.0.0.0"; // Replace with clients IP
$address = "REPLACE_WITH_AN_ADDRESS"; // Optional address for distance calculation
$geoMatch = true; // Enable geoMatch to compare IP location with address
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/fraud-check/geoip",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode([
"ip" => $ip,
"address" => $address,
"geoMatch" => $geoMatch
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const ip = "0.0.0.0"; // Replace with clients IP
const address = "REPLACE_WITH_AN_ADDRESS"; // Optional address for distance calculation
const geoMatch = true; // Enable geoMatch to compare IP location with address
fetch("https://api.provero.io/api/fraud-check/geoip", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify({ ip, address, geoMatch })
})
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));ip="0.0.0.0" # Replace with clients IP
address="REPLACE_WITH_AN_ADDRESS" # Optional address for distance calculation
geoMatch=true # Enable geoMatch to compare IP location with address
curl -X POST https://api.provero.io/api/fraud-check/geoip \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "{ \"ip\": \"$ip\", \"address\": \"$address\", \"geoMatch\": $geoMatch }"Response Examples
Success
{
"country": "Ireland",
"regionName": "Leinster",
"city": "Dublin",
"zip": "D02",
"lat": "53.3498",
"lon": "-6.26031",
"ip": "46.51.128.144",
"distance": {
"km": 0.0514,
"mi": 0.0319
},
"geoMatch": {
"country": true,
"city": true
}
}Application Error
{
"requestError": {
"serviceException": {
"messageId": "Error message",
"code": "400"
}
}
}Payment Required - Insufficient Balance
{
"message": "Insufficient balance for validation request.",
"service": "geoip",
"required_amount": "0.0060000000",
"current_balance": "0.0000000000"
}Validation Error - IP Not Provided
{
"message": "The ip field is required.",
"errors": {
"ip": [
"The ip field is required."
]
}
}Validation Error - Invalid IP Address
{
"message": "The ip field must be a valid IP address.",
"errors": {
"ip": [
"The ip field must be a valid IP address."
]
}
}Validation Error - Geomatch - Destination Not Valid
{
"message": "Please provide a valid destination to match.",
"errors": {
"address": [
"Please provide a valid destination to match."
]
}
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
country |
string |
Ireland | Yes | Country of the IP's location |
regionName |
string |
Leinster | Yes | Region/province/state |
city |
string |
Dublin | Yes | City of the IP location |
zip |
string |
D02 | Yes | Postcode of the IP |
lat |
string |
53.3498 | Yes | Latitude |
lon |
string |
-6.2603 | Yes | Longitude |
ip |
string |
46.51.128.144 | Yes | IP address submitted |
distance.km |
string |
0.051 | No | Distance to address (km) |
distance.mi |
string |
0.031 | No | Distance to address (miles) |
geoMatch.country |
boolean |
true | No | Country match result |
geoMatch.city |
boolean |
true | No | City match result |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
The ip field is required. | No | Top-level error message returned on validation failure, insufficient balance, or other request errors. |
errors |
object |
{"ip": ["The ip field is required."]} | No | Object of validation services with validation failures. |
requestError |
object |
{"serviceException": {"messageId": "Error message", "code": "400"}} | No | Object containing service exceptions for application errors. |
service |
string |
geoip | No | Service alias returned with a 402 insufficient-balance response. |
required_amount |
string |
0.0060000000 | No | Credit amount required to process the validation request. |
current_balance |
string |
0.0000000000 | No | Current available balance at the time the request was rejected. |
Multi-Validation
Validate multiple inputs in a single call (email, phone, TPS, IP fraud, IP geolocation, and name). Only supplied fields are processed and only corresponding result blocks are returned.
Response mapping: Each nested object in the response mirrors its standalone validator’s response. For full field descriptions and examples, see the corresponding single-validator panes:
Response mapping: Each nested object in the response mirrors its standalone validator’s response. For full field descriptions and examples, see the corresponding single-validator panes:
Email Validation, Phone Validation, TPS Check, Name Screening, IP Fraud, and GeoIP.Endpoint
POST
https://api.provero.io/api/validate/multipleHeaders
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email |
object |
No | Full email validation docs. |
phone |
object |
No | Full phone validation docs. |
address |
object |
No | Full UK postcode verification docs. |
tps |
object |
No | Full TPS validation docs. |
ip |
object |
No | Full IP validation docs. |
breach |
object |
No | Full breach validation docs. |
name |
object |
No | Full name screening docs. |
geoip |
object |
No | Full GEOIP validation docs. |
Request Body example (JSON)
{
"email": {
"email": "test@example.com"
},
"phone": {
"phone": "441234567890",
"roaming": true,
"route": "detailed"
},
"address": {
"postcode": "LS18 5HY"
},
"tps": {
"phone": "441234567890"
},
"ip": {
"ip": "8.8.8.8",
"user_agent": "Mozilla/5.0",
"user_language": "en"
},
"breach": {
"type": "email",
"value": "example@email.com"
},
"name": {
"name": "John Doe"
},
"geoip": {
"ip": "8.8.8.8",
"address": "London",
"geoMatch": true
}
}Code Examples
import requests
payload = {
"email": {
"email": "test@example.com"
},
"phone": {
"phone": "441234567890",
"roaming": true,
"route": "detailed",
},
"address": {
"postcode": "LS18 5HY"
},
"tps": {
"phone": "441234567890"
},
"ip": {
"ip": "8.8.8.8",
"user_agent": "Mozilla/5.0",
"user_language": "en"
},
"breach": {
"type": "email",
"value": "test@example.com"
},
"geoip": {
"ip": "8.8.8.8",
"address": "London",
"geoMatch": true
}
}
url = "https://api.provero.io/api/validate/multiple"
headers = {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())<?php
$payload = [
"email" => [
"email" => "test@example.com"
],
"phone" => [
"phone" => "441234567890",
"roaming" => true,
"route" => "detailed",
],
"address" => [
"postcode" => "LS18 5HY"
],
"tps" => [
"phone" => "441234567890"
],
"ip" => [
"ip" => "8.8.8.8",
"user_agent" => "Mozilla/5.0",
"user_language" => "en"
],
"breach" => [
"type" => "email",
"value" => "test@example.com"
],
"geoip" => [
"ip" => "8.8.8.8",
"address" => "London",
"geoMatch" => true
]
];
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.provero.io/api/validate/multiple",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer REPLACE_WITH_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($curl);
if (curl_errno($curl)) {
echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;const payload = {
"email": {
"email": "test@example.com"
},
"phone": {
"phone": "441234567890",
"roaming": true,
"route": "detailed",
},
"address": {
"postcode": "LS18 5HY"
},
"tps": {
"phone": "441234567890"
},
"ip": {
"ip": "8.8.8.8",
"user_agent": "Mozilla/5.0",
"user_language": "en"
},
"breach": {
"type": "email",
"value": "test@example.com"
},
"geoip": {
"ip": "8.8.8.8",
"address": "London",
"geoMatch": true
}
};
fetch("https://api.provero.io/api/validate/multiple", {
method: "POST",
headers: {
"Authorization": "Bearer REPLACE_WITH_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
},
body: JSON.stringify(payload)
})
.then(r => r.json())
.then(console.log)
.catch(console.error);curl -X POST https://api.provero.io/api/validate/multiple \
-H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"email": {
"email": "test@example.com"
},
"phone": {
"phone": "441234567890",
"roaming": true,
"route": "detailed",
},
"address": {
"postcode": "LS18 5HY"
},
"tps": {
"phone": "441234567890"
},
"ip": {
"ip": "8.8.8.8",
"user_agent": "Mozilla/5.0",
"user_language": "en"
},
"breach": {
"type": "email",
"value": "test@example.com"
},
"geoip": {
"ip": "8.8.8.8",
"address": "London",
"geoMatch": true
}
}'Response Examples
Success
{
"email": {
"emailAddress": "test@example.com",
"isSyntaxValid": true,
"isMailboxDeliverable": false,
"isCatchAll": false,
"typoSuggestion": false,
"isDisposable": false,
"isRoleBased": false,
"riskLevel": "HIGH",
"failureReason": "missing_mx"
},
"phone": {
"results": [
{
"to": "+441234567890",
"mccMnc": "23420",
"imsi": "23420",
"originalNetwork": {
"networkName": "Telefonica UK",
"networkPrefix": "1234",
"countryName": "United Kingdom of Great Britain and Northern Ireland",
"countryPrefix": "44",
"networkId": ""
},
"status": {
"groupId": 3,
"groupName": "DELIVERED",
"id": 5,
"name": "DELIVERED_TO_HANDSET",
"description": "The message has reached the recipient\u2019s device successfully."
},
"roaming": false,
"ported": true,
"portedNetwork": {
"networkName": "Hutchison 3G UK (20)",
"networkPrefix": "1234",
"countryName": "United Kingdom of Great Britain and Northern Ireland",
"countryPrefix": "44",
"networkId": ""
},
"error": {
"groupId": 0,
"groupName": "Ok",
"id": 0,
"name": "NO_ERROR",
"description": "The request was processed without any issues.",
"permanent": false
}
}
]
},
"address": {
"valid": true,
"postcode": "LS18 5HY",
"address": {
"Address1": "Otley Old Road",
"Address2": "Horsforth",
"Address3": "",
"Address4": "",
"Town": "Leeds",
"County": "West Yorkshire",
"Postcode": "LS18 5HY",
"PremiseData": "Greengates Cattery|Greengates Stables|;The S Cayton Motor Co|The Barn/Greengates Farm|;|Greengates Farm|;"
}
},
"tps": {
"phone": "441234567890",
"result": false
},
"ip": {
"value": "8.8.8.8",
"proxy": false,
"isp": "Google",
"organization": "Google DNS",
"asn": "15169",
"host": "dns.google",
"countryCode": "US",
"city": "Mountain View",
"region": "California",
"isCrawler": false,
"connectionType": "none",
"latitude": "37.38999939",
"longitude": "-122.06999969",
"zipCode": "N/A",
"timezone": "America/Los_Angeles",
"vpn": false,
"tor": false,
"activeVpn": false,
"activeTor": false,
"recentAbuse": false,
"abuseVelocity": "none",
"botStatus": false,
"mobile": false,
"fraudScore": 0,
"highRiskAttacks": null,
"sharedConnection": null,
"dynamicConnection": null,
"securityScanner": null,
"trustedNetwork": null,
"operatingSystem": "UNK UNK",
"browser": "UNK UNK",
"deviceModel": "N/A",
"deviceBrand": "N/A",
"frequentAbuser": null
},
"breach": {
"value": "test@email.com",
"type": "email",
"leaks": [
{
"name": "Adobe",
"domain": "adobe.com",
"breachDate": "2013-10-04",
"description": "User profile and password hints were exposed."
}
]
},
"geoip": {
"country": "United States",
"regionName": "Virginia",
"city": "Ashburn",
"zip": "20149",
"lat": 39.03,
"lon": -77.5,
"ip": "8.8.8.8",
"distance": {
"km": 3598.695068406005,
"mi": 2236.1247533505075
},
"geoMatch": {
"country": false,
"city": false
}
}
}Validation Error - Invalid Email
{
"message": "The email field must be a valid email address.",
"errors": {
"email.email": [
"The email field must be a valid email address."
]
}
}Validation Error - Invalid Phone
{
"message": "The string supplied did not seem to be a phone number.",
"errors": {
"phone.phone": [
"The string supplied did not seem to be a phone number."
],
"phone.ported": [
"The phone.ported field must be true or false."
],
"phone.roaming": [
"The phone.roaming field must be true or false."
],
"phone.route": [
"The route value must be one of: standard, detailed, playground"
]
}
}Validation Error - Invalid Address
{
"message": "The address.postcode field must not be greater than 255 characters.",
"errors": {
"address.postcode": [
"The address.postcode field must not be greater than 255 characters."
]
}
}Validation Error - TPS Number Invalid
{
"message": "The string supplied did not seem to be a phone number.",
"errors": {
"tps.phone": [
"The string supplied did not seem to be a phone number."
]
}
}Validation Error - Fraud detection Invalid
{
"message": "The ip.ip field must be a valid IP address.",
"errors": {
"ip.ip": [
"The ip.ip field must be a valid IP address."
]
}
}Validation Error - geoip Invalid
{
"message": "The ip field is required when geoip is true.",
"errors": {
"geoip.ip": [
"The geoip.ip field must be a valid IP address."
],
"geoip.geoMatch": [
"The geoip.geo match field must be true or false."
]
}
}Application Error
{
"requestError": {
"serviceException": {
"messageId": "Error message",
"code": "400"
}
}
}Response Body
Success structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
email |
object |
{"emailAddress":"test@example.com","isSyntaxValid":true} | No | Email validation result. See the Email Validation pane for full field list. |
phone |
object |
{"results":[{"status":{"name":"REJECTED_NETWORK"}}]} | No | Phone validation result. See the Phone Validation pane. |
tps |
object |
{"phone":"tel:+44-1302-778473","result":false} | No | TPS check result. See the TPS pane. |
ip |
object |
{"proxy":false,"fraudScore":0} | No | Fraud detection result. See the IP Fraud pane. |
geoip |
object |
{"country":"United States","city":"Ashburn","distance":{"km":3597.32}} | No | Geolocation (and optional distance/match). See the GeoIP pane. |
name |
object |
{"fullName":"John Doe","isValid":true,"isProfane":false,"riskLevel":"LOW"} | No | Name fraud/identity check result. |
Error structure
| Field Name | Type | Example | Always Present | Description |
|---|---|---|---|---|
message |
string |
The email field must be a valid email address. | No | Top-level validation message. |
errors |
object |
{"email":["The email field must be a valid email address."]} | No | Per-field validation errors. |
requestError |
object |
{"serviceException":{"messageId":"Error message","code":"400"}} | No | Application/service errors container. |