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.

Manage API Keys Manage Campaigns Open Playground

Campaign

Endpoint

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.

Email

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/email

Headers

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`	email	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-basic

Headers

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/phone

Headers

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: Runs the detailed HLR route. standard (default): Runs the standard HLR route.
`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.

Endpoint

POST

https://api.provero.io/api/validate/uk-postcode

Headers

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.

Endpoint

POST

https://api.provero.io/api/validate/address

Headers

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-tps

Headers

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 full_name value or a first_name and last_name pair.

Endpoint

POST

https://api.provero.io/api/fraud-check/name

Headers

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/ip

Headers

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 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/breach

Headers

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`	email	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.

Endpoint

POST

https://api.provero.io/api/fraud-check/geoip

Headers

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: Email Validation, Phone Validation, TPS Check, Name Screening, IP Fraud, and GeoIP.

Endpoint

POST

https://api.provero.io/api/validate/multiple

Headers

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.