Submit Data Based Identity Verification
POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification
You can use the /environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification operation to compare first name, last name, current addresses, Social Security number, date of birth, and mobile phone number with thousands of commercial databases and hundreds of fraud alerts. The service returns a confidence level of the match, raw data from the vendor, and data from best match source if available.
Request Model
Refer to Verify data based identity verification request data model for full property descriptions.
| Property | Type | Required? |
|---|---|---|
|
Object |
Required |
|
String |
Required |
|
String |
Required |
|
String |
Required/Optional |
|
String |
Required/Optional |
|
String |
Required/Optional |
|
String |
Required/Optional |
|
String |
Required/Optional |
|
String |
Optional |
|
String |
Required/Optional |
|
String |
Optional |
For US-based identities, the service requires at minimum for verification either name (or given_name and family_name) and national_id_number, which is a Social Security Number, or name (or given_name and family_name) and birth_date.
If phone is included in this request, it is not verified using SMS. This differs from the service behavior when DATA_BASED_IDENTITY_VERIFICATION is included in a verify policy.
The example responses show verified data from:
-
TransUnion for US-based identities
-
Data Zoo non-US-based identities.
Body
raw ( application/json )
{
"requirements": {
"given_name": {
"value": "Edith"
},
"family_name": {
"value": "Xylander"
},
"address_street": {
"value": "4471 Sundown Lane"
},
"address_city": {
"value": "Austin"
},
"address_state": {
"value": "TX"
},
"address_zip": {
"value": "78746"
},
"birth_date": {
"value": "1991-09-29"
},
"national_id_number": {
"value": "123456789"
},
"phone": {
"value": "512-992-6419"
}
}
}
Example Request
-
cURL
-
C#
-
Go
-
HTTP
-
Java
-
jQuery
-
NodeJS
-
Python
-
PHP
-
Ruby
-
Swift
curl --location --globoff '{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
"requirements": {
"given_name": {
"value": "Edith"
},
"family_name": {
"value": "Xylander"
},
"address_street": {
"value": "4471 Sundown Lane"
},
"address_city": {
"value": "Austin"
},
"address_state": {
"value": "TX"
},
"address_zip": {
"value": "78746"
},
"birth_date": {
"value": "1991-09-29"
},
"national_id_number": {
"value": "123456789"
},
"phone": {
"value": "512-992-6419"
}
}
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification")
{
MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@" ""requirements"": {" + "\n" +
@" ""given_name"": {" + "\n" +
@" ""value"": ""Edith""" + "\n" +
@" }," + "\n" +
@" ""family_name"": {" + "\n" +
@" ""value"": ""Xylander""" + "\n" +
@" }," + "\n" +
@" ""address_street"": {" + "\n" +
@" ""value"": ""4471 Sundown Lane""" + "\n" +
@" }," + "\n" +
@" ""address_city"": {" + "\n" +
@" ""value"": ""Austin""" + "\n" +
@" }," + "\n" +
@" ""address_state"": {" + "\n" +
@" ""value"": ""TX""" + "\n" +
@" }," + "\n" +
@" ""address_zip"": {" + "\n" +
@" ""value"": ""78746""" + "\n" +
@" }," + "\n" +
@" ""birth_date"": {" + "\n" +
@" ""value"": ""1991-09-29""" + "\n" +
@" }," + "\n" +
@" ""national_id_number"": {" + "\n" +
@" ""value"": ""123456789""" + "\n" +
@" }," + "\n" +
@" ""phone"": {" + "\n" +
@" ""value"": ""512-992-6419""" + "\n" +
@" }" + "\n" +
@" }" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification"
method := "POST"
payload := strings.NewReader(`{
"requirements": {
"given_name": {
"value": "Edith"
},
"family_name": {
"value": "Xylander"
},
"address_street": {
"value": "4471 Sundown Lane"
},
"address_city": {
"value": "Austin"
},
"address_state": {
"value": "TX"
},
"address_zip": {
"value": "78746"
},
"birth_date": {
"value": "1991-09-29"
},
"national_id_number": {
"value": "123456789"
},
"phone": {
"value": "512-992-6419"
}
}
}`)
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Bearer {{accessToken}}")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
POST /environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}
{
"requirements": {
"given_name": {
"value": "Edith"
},
"family_name": {
"value": "Xylander"
},
"address_street": {
"value": "4471 Sundown Lane"
},
"address_city": {
"value": "Austin"
},
"address_state": {
"value": "TX"
},
"address_zip": {
"value": "78746"
},
"birth_date": {
"value": "1991-09-29"
},
"national_id_number": {
"value": "123456789"
},
"phone": {
"value": "512-992-6419"
}
}
}
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"requirements\": {\n \"given_name\": {\n \"value\": \"Edith\"\n },\n \"family_name\": {\n \"value\": \"Xylander\"\n },\n \"address_street\": {\n \"value\": \"4471 Sundown Lane\"\n },\n \"address_city\": {\n \"value\": \"Austin\"\n },\n \"address_state\": {\n \"value\": \"TX\"\n },\n \"address_zip\": {\n \"value\": \"78746\"\n },\n \"birth_date\": {\n \"value\": \"1991-09-29\"\n },\n \"national_id_number\": {\n \"value\": \"123456789\"\n },\n \"phone\": {\n \"value\": \"512-992-6419\"\n }\n }\n}");
Request request = new Request.Builder()
.url("{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {{accessToken}}")
.build();
Response response = client.newCall(request).execute();
var settings = {
"url": "{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer {{accessToken}}"
},
"data": JSON.stringify({
"requirements": {
"given_name": {
"value": "Edith"
},
"family_name": {
"value": "Xylander"
},
"address_street": {
"value": "4471 Sundown Lane"
},
"address_city": {
"value": "Austin"
},
"address_state": {
"value": "TX"
},
"address_zip": {
"value": "78746"
},
"birth_date": {
"value": "1991-09-29"
},
"national_id_number": {
"value": "123456789"
},
"phone": {
"value": "512-992-6419"
}
}
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
var request = require('request');
var options = {
'method': 'POST',
'url': '{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification',
'headers': {
'Content-Type': 'application/json',
'Authorization': 'Bearer {{accessToken}}'
},
body: JSON.stringify({
"requirements": {
"given_name": {
"value": "Edith"
},
"family_name": {
"value": "Xylander"
},
"address_street": {
"value": "4471 Sundown Lane"
},
"address_city": {
"value": "Austin"
},
"address_state": {
"value": "TX"
},
"address_zip": {
"value": "78746"
},
"birth_date": {
"value": "1991-09-29"
},
"national_id_number": {
"value": "123456789"
},
"phone": {
"value": "512-992-6419"
}
}
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification"
payload = json.dumps({
"requirements": {
"given_name": {
"value": "Edith"
},
"family_name": {
"value": "Xylander"
},
"address_street": {
"value": "4471 Sundown Lane"
},
"address_city": {
"value": "Austin"
},
"address_state": {
"value": "TX"
},
"address_zip": {
"value": "78746"
},
"birth_date": {
"value": "1991-09-29"
},
"national_id_number": {
"value": "123456789"
},
"phone": {
"value": "512-992-6419"
}
}
})
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer {{accessToken}}'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n "requirements": {\n "given_name": {\n "value": "Edith"\n },\n "family_name": {\n "value": "Xylander"\n },\n "address_street": {\n "value": "4471 Sundown Lane"\n },\n "address_city": {\n "value": "Austin"\n },\n "address_state": {\n "value": "TX"\n },\n "address_zip": {\n "value": "78746"\n },\n "birth_date": {\n "value": "1991-09-29"\n },\n "national_id_number": {\n "value": "123456789"\n },\n "phone": {\n "value": "512-992-6419"\n }\n }\n}');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}
require "uri"
require "json"
require "net/http"
url = URI("{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
"requirements": {
"given_name": {
"value": "Edith"
},
"family_name": {
"value": "Xylander"
},
"address_street": {
"value": "4471 Sundown Lane"
},
"address_city": {
"value": "Austin"
},
"address_state": {
"value": "TX"
},
"address_zip": {
"value": "78746"
},
"birth_date": {
"value": "1991-09-29"
},
"national_id_number": {
"value": "123456789"
},
"phone": {
"value": "512-992-6419"
}
}
})
response = http.request(request)
puts response.read_body
let parameters = "{\n \"requirements\": {\n \"given_name\": {\n \"value\": \"Edith\"\n },\n \"family_name\": {\n \"value\": \"Xylander\"\n },\n \"address_street\": {\n \"value\": \"4471 Sundown Lane\"\n },\n \"address_city\": {\n \"value\": \"Austin\"\n },\n \"address_state\": {\n \"value\": \"TX\"\n },\n \"address_zip\": {\n \"value\": \"78746\"\n },\n \"birth_date\": {\n \"value\": \"1991-09-29\"\n },\n \"national_id_number\": {\n \"value\": \"123456789\"\n },\n \"phone\": {\n \"value\": \"512-992-6419\"\n }\n }\n}"
let postData = parameters.data(using: .utf8)
var request = URLRequest(url: URL(string: "{{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")
request.httpMethod = "POST"
request.httpBody = postData
let task = URLSession.shared.dataTask(with: request) { data, response, error in
guard let data = data else {
print(String(describing: error))
return
}
print(String(data: data, encoding: .utf8)!)
}
task.resume()
Example Response
200 OK
{
"confidence": "HIGH",
"bestMatch": {
"firstName": "EDITH",
"lastName": "XYLANDER",
"fullName": "EDITH XYLANDER",
"addressQualifier": "personal",
"addressStatus": "current",
"addressStreet": "4471 SUNDOWN LANE",
"addressCity": "AUSTIN",
"addressState": "TX",
"addressZip": "78746-3292",
"birthDate": "1991-09-29",
"nationalIdNumber": "123456789",
"phoneQualifier": "personal",
"phoneType": "cell",
"phone": "512-992-6419",
"source": "file",
"sourceIsBestMatch": "true",
"additionalHistory": {
"address": [
{
"qualifier": "personal",
"status": "previous",
"addressStreet": "3065 ASHTON DR 2165",
"addressCity": "AUSTIN",
"addressState": "TX",
"addressZip": "78741"
}
]
}
},
"creditBureau": {
"document": "response",
"version": "2.8",
"transactionControl": {
"subscriber": {
"industryCode": "P",
"memberCode": "4231552",
"inquirySubscriberPrefixCode": "4404",
"name": {
"unparsed": "PING"
}
},
"options": {
"country": "us",
"language": "en"
},
"tracking": {
"id": "2025-09-19-00.22.25.535823",
"transactionTimeStamp": "2025-09-19T00:22:25.535-05:00"
}
},
"product": {
"code": "06672",
"subject": {
"number": 1,
"subjectRecord": {
"fileNumber": "01",
"fileSummary": {
"fileHitIndicator": "subjectHit",
"creditDataStatus": {
"suppressed": false,
"doNotPromote": {
"indicator": false
},
"freeze": {
"indicator": false
},
"minor": false,
"disputed": false
}
},
"indicative": {
"name": [
{
"source": "input",
"person": {
"first": "XYLANDER",
"last": "EDITH"
}
},
{
"source": "file",
"person": {
"first": "EDITH",
"last": "XYLANDER"
}
},
{
"source": "vendorFile",
"person": {
"first": "EDITH",
"middle": "H",
"last": "XYLANDER",
"generationalSuffix": ""
}
},
{
"source": "vendorFile",
"qualifier": "alsoKnownAs",
"person": {
"first": "EDITH",
"middle": "",
"last": "XYLANDER",
"generationalSuffix": ""
}
}
],
"address": [
{
"source": "file",
"status": "current",
"qualifier": "personal",
"street": {
"number": "4471",
"name": "SUNDOWN",
"type": "LN"
},
"location": {
"city": "AUSTIN",
"state": "TX",
"zipCode": "78746-3292"
},
"dateReported": {
"estimatedDay": false,
"estimatedMonth": false,
"estimatedCentury": false,
"estimatedYear": false,
"value": "2022-01-31"
}
},
{
"source": "file",
"status": "previous",
"qualifier": "personal",
"street": {
"number": "3065",
"name": "ASHTON",
"type": "DR",
"unit": {
"number": "2165"
}
},
"location": {
"city": "AUSTIN",
"state": "TX",
"zipCode": "78741"
},
"dateReported": {
"estimatedDay": false,
"estimatedMonth": false,
"estimatedCentury": false,
"estimatedYear": false,
"value": "2003-05-01"
}
},
{
"source": "vendorFile",
"status": "current",
"classification": {
"usps": "USBasic",
"type": "conventional"
},
"street": {
"number": "4471",
"name": "SUNDOWN",
"type": "LN"
},
"location": {
"city": "AUSTIN",
"state": "TX",
"zipCode": "78746-3292"
},
"dateReported": {
"estimatedDay": false,
"estimatedMonth": false,
"estimatedCentury": false,
"estimatedYear": false,
"value": "2022-01-18"
}
},
{
"source": "vendorFile",
"status": "previous",
"classification": {
"usps": "USBasic",
"type": "conventional"
},
"street": {
"number": "3065",
"name": "ASHTON",
"type": "DR",
"unit": {
"number": "2165"
}
},
"location": {
"city": "AUSTIN",
"state": "TX",
"zipCode": "78741"
},
"dateReported": {
"estimatedDay": false,
"estimatedMonth": false,
"estimatedCentury": false,
"estimatedYear": false,
"value": "2006-08-31"
}
}
],
"socialSecurity": [
{
"source": "input",
"masked": "false",
"number": "123456789",
"identificationIssuance": {
"type": "ssn",
"status": "clear",
"yearRange": {
"startYear": "1976",
"endYear": "1977"
},
"state": "TX",
"ageObtained": {
"rangeStart": "+14",
"rangeEnd": "+16"
}
}
},
{
"source": "file",
"masked": "false",
"number": "123456789"
},
{
"source": "vendorFile",
"masked": "false",
"number": "123456789"
}
],
"dateOfBirth": [
{
"source": "file",
"estimatedDay": false,
"estimatedMonth": false,
"estimatedCentury": false,
"estimatedYear": false,
"value": "1991-09-29"
},
{
"source": "vendorFile",
"estimatedDay": false,
"estimatedMonth": false,
"estimatedCentury": false,
"estimatedYear": false,
"value": "1991-09-29"
}
],
"age": [
{
"source": "vendorFile",
"value": "34"
}
],
"phone": [
{
"source": "file",
"number": {
"qualifier": "personal",
"type": "cell",
"areaCode": "512",
"exchange": "992",
"suffix": "6419"
}
},
{
"source": "vendorFile",
"number": {
"qualifier": "personal",
"type": "mobile",
"areaCode": "512",
"exchange": "992",
"suffix": "6419"
}
}
],
"gender": [
{
"source": "vendorFile",
"value": "female"
}
]
},
"custom": {
"idmanagerVerAnalysisV2": {
"verificationSummary": {
"riskIndicator": "low",
"bestMatch": "file",
"verificationPoint": 10,
"lowerThreshold": 30,
"upperThreshold": 49
},
"fraudAnalysis": {
"location": {},
"employment": {}
},
"verificationAnalysis": [
{
"source": "file",
"verificationStatus": "subjectFound",
"firstNameVerification": "partialMatch",
"middleNameVerification": "matchNotPerformed",
"lastNameVerification": "partialMatch",
"nameSuffixVerification": "matchNotPerformed",
"currentAddressVerification": "inputNotAvailable",
"previousAddressVerification": "inputNotAvailable",
"phoneNumberVerification": "inputNotAvailable",
"ssnVerification": "match",
"dateOfBirthVerification": "inputNotAvailable"
},
{
"source": "vendorFile",
"verificationStatus": "subjectFound",
"firstNameVerification": "partialMatch",
"middleNameVerification": "inputNotAvailable",
"lastNameVerification": "partialMatch",
"nameSuffixVerification": "matchNotPerformed",
"currentAddressVerification": "inputNotAvailable",
"previousAddressVerification": "inputNotAvailable",
"phoneNumberVerification": "inputNotAvailable",
"ssnVerification": "match",
"dateOfBirthVerification": "inputNotAvailable"
}
]
}
},
"addOnProduct": {
"code": "FRDMS",
"status": "delivered",
"idManagerVerification": {
"searchStatus": "clear"
}
}
}
}
}
}
}
Example Response
200 OK
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/9b42e114-8d66-42af-9b18-8958e9572f4a/verifyTransactions/ba059555-a81b-473c-baa0-b016529c9e19/metaData/6d7c97c7-0cd5-4de7-b035-e4b2634eb121"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"user": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/9b42e114-8d66-42af-9b18-8958e9572f4a"
},
"verifyTransaction": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/9b42e114-8d66-42af-9b18-8958e9572f4a/verifyTransactions/ba059555-a81b-473c-baa0-b016529c9e19"
}
},
"id": "6d7c97c7-0cd5-4de7-b035-e4b2634eb121",
"provider": "DATAZOO",
"type": "DATA_BASED_IDENTITY_VERIFICATION",
"status": "SUCCESS",
"data": {
"reportingReference": "DZ-b496d76e-687c-438a-92d7-3adc06fadf75",
"safeHarbour": false,
"matchStatus": "Full Match 1+1 Verification",
"countryCode": "Philippines",
"clientReference": "",
"serviceResponses": {
"Philippines Residential": {
"status": 0,
"sourceStatus": "Successful",
"errorMessage": "",
"identityVerified": true,
"safeHarbourScore": "M1",
"nameMatchScore": "1.000",
"addressMatchScore": "0.950",
"verifications": {
"addressElement1": true,
"addressElement3": true,
"addressElement4": true,
"addressElement5": true,
"city": true,
"province": true,
"region": true,
"street": true,
"dateOfBirth": true,
"firstName": true,
"lastName": true
},
"returnedData": {
"address": "Cebu Region 7, Tangil, Dumanjug, Cebu, 6035",
"category": "consumer",
"source": "dz1"
}
}
},
"searchErrorMessage": "",
"searchStatus": "Successful"
}
}