PingOne Platform APIs

Submit Device Ownership Verification

POST {{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification

You can use the POST {{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification operation to compare full name or first name and last name, email, and mobile phone number with thousands of commercial databases and hundreds of fraud alerts. The service returns match-level indicators for phone to name, email to name, and email to phone.

Request Model

Refer to Verify device ownership verification request data model for full property descriptions.

Property Type Required

requirements

Object

Required

requirements.given_name.value

String

Required/Optional

requirements.family_name.value

String

Required/Optional

requirements.name.value

String

Required/Optional

requirements.email.value

String

Required/Optional

requirements.phone.value

String

Required/Optional

For US-based identities, the service requires at minimum for verification two or more of name (or given_name and family_name), email, and phone.

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
    "requirements": {
        "name": {
            "value": "Edith Xylander"
        },
        "email": {
            "value": "edith.xylander@example.com"
        },
        "phone": {
            "value": "512-992-6419"
        }
    }
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data-raw '{
    "requirements": {
        "name": {
            "value": "Edith Xylander"
        },
        "email": {
            "value": "edith.xylander@example.com"
        },
        "phone": {
            "value": "512-992-6419"
        }
    }
}'
var options = new RestClientOptions("{{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification")
{
  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" +
@"        ""name"": {" + "\n" +
@"            ""value"": ""Edith Xylander""" + "\n" +
@"        }," + "\n" +
@"        ""email"": {" + "\n" +
@"            ""value"": ""edith.xylander@example.com""" + "\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}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification"
  method := "POST"

  payload := strings.NewReader(`{
    "requirements": {
        "name": {
            "value": "Edith Xylander"
        },
        "email": {
            "value": "edith.xylander@example.com"
        },
        "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 /v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
    "requirements": {
        "name": {
            "value": "Edith Xylander"
        },
        "email": {
            "value": "edith.xylander@example.com"
        },
        "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        \"name\": {\n            \"value\": \"Edith Xylander\"\n        },\n        \"email\": {\n            \"value\": \"edith.xylander@example.com\"\n        },\n        \"phone\": {\n            \"value\": \"512-992-6419\"\n        }\n    }\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "requirements": {
      "name": {
        "value": "Edith Xylander"
      },
      "email": {
        "value": "edith.xylander@example.com"
      },
      "phone": {
        "value": "512-992-6419"
      }
    }
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "requirements": {
      "name": {
        "value": "Edith Xylander"
      },
      "email": {
        "value": "edith.xylander@example.com"
      },
      "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}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification"

payload = json.dumps({
  "requirements": {
    "name": {
      "value": "Edith Xylander"
    },
    "email": {
      "value": "edith.xylander@example.com"
    },
    "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}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification');
$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        "name": {\n            "value": "Edith Xylander"\n        },\n        "email": {\n            "value": "edith.xylander@example.com"\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}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification")

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": {
    "name": {
      "value": "Edith Xylander"
    },
    "email": {
      "value": "edith.xylander@example.com"
    },
    "phone": {
      "value": "512-992-6419"
    }
  }
})

response = http.request(request)
puts response.read_body
let parameters = "{\n    \"requirements\": {\n        \"name\": {\n            \"value\": \"Edith Xylander\"\n        },\n        \"email\": {\n            \"value\": \"edith.xylander@example.com\"\n        },\n        \"phone\": {\n            \"value\": \"512-992-6419\"\n        }\n    }\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification")!,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

{
    "nsr": "dc15-eid-prod-gwy02:092",
    "transid": "1",
    "errorcode": "SUCCESS",
    "identityRisk": {
        "identityVerification": {
            "verifiedComponents": "PHONE_AND_EMAIL_LINKED_TO_NAME",
            "unverifiedComponents": "NO_UNVERIFIED_COMPONENTS",
            "phoneToName": [
                "HIGH_CONFIDENCE_MATCH"
            ],
            "phoneToFirstName": [
                "HIGH_CONFIDENCE_MATCH"
            ],
            "addressToPhone": [
                "INVALID_OR_MISSING_INPUT"
            ],
            "emailToPhone": [
                "LOWER_CONFIDENCE_MATCH"
            ],
            "addressToName": "INVALID_OR_MISSING_INPUT",
            "emailToName": "LOWER_CONFIDENCE_MATCH",
            "emailToAddress": "INVALID_OR_MISSING_INPUT",
            "addressCurrent": "INVALID_ADDRESS"
        },
        "phoneToName": [
            "HIGH_CONFIDENCE_MATCH"
        ],
        "phoneToFirstName": [
            "HIGH_CONFIDENCE_MATCH"
        ],
        "addressToPhone": [
            "INVALID_OR_MISSING_INPUT"
        ],
        "emailToPhone": [
            "LOWER_CONFIDENCE_MATCH"
        ],
        "addressToName": "INVALID_OR_MISSING_INPUT",
        "emailToName": "LOWER_CONFIDENCE_MATCH",
        "emailToAddress": "INVALID_OR_MISSING_INPUT",
        "addressCurrent": "INVALID_ADDRESS",
        "phone": [
            {
                "prepaid": "N",
                "techType": "WIRELESS",
                "phoneType": "UNKNOWN",
                "mvno": "N",
                "carrier": "T-Mobile",
                "spn": 40654,
                "usage": {
                    "serviceTenure": "ACTIVE_FOR_1_MONTH_OR_LESS",
                    "usage2mo": "MINIMAL_USAGE",
                    "usage12mo": "MODERATE_USAGE"
                },
                "nameChange": {
                    "nameChange": "NO_CHANGES_PHONE_NUMBER_FOUND_IN_TRANSUNION_DIRECTORY_BUT_NAME_HAS_NOT_CHANGED",
                    "nameChangeType": "NO_CHANGES_PHONE_NUMBER_FOUND_IN_TRANSUNION_DIRECTORY_BUT_NAME_HAS_NOT_CHANGED",
                    "numNameChange": "NO_CHANGES_DETECTED_WITHIN_60_DAYS",
                    "source": "AUTHORITATIVE_DATA"
                },
                "indicators": {
                    "phoneComp": {
                        "1": {
                            "decision": "LOW_RISK"
                        }
                    }
                }
            }
        ],
        "email": {
            "validation": "INVALID_ACCOUNT",
            "emailFound": "EMAIL_ADDRESS_FOUND_IN_TU_REPOSITORY",
            "firstActive": "NO_ACTIVITY_SEEN_OR_DATE_OF_FIRST_ACTIVITY_IS_UNKNOWN",
            "lastActive": "NO_ACTIVITY_SEEN_OR_DATE_OF_LAST_ACTIVITY_IS_UNKNOWN",
            "activeTenure": "NO_ACTIVITY_SEEN_OR_LONGEST_ACTIVE_STREAK_UNKNOWN"
        },
        "useCase": "PingIdentity Verification",
        "correlationID": "084ade93-525e-4764-bbd0-965a4967cb8a"
    }
}