PingOne Platform APIs

Submit Identity Record Match

 

POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/identityRecordMatching

You can use the /environments/{{envID}}/users/{{userID}}/identityRecordMatching operation to compare unverified name, given name, family name, birth date, or address with corresponding values from one or more verified sources. The service returns a raw score and confidence level of the match.

Request Model

Refer to Verify identity record matching request data model for full property descriptions.

Property Type Required?

probe

Object

Required

probe.name

String

Required/Optional

probe.given_name

String

Required/Optional

probe.family_name

String

Required/Optional

probe.address

String

Required/Optional

probe.birth_date

String

Required/Optional

gallery

Object

Required

gallery.name

String

Required/Optional

gallery.name.value

String

Required/Optional

gallery.name.options

String[]

Required/Optional

gallery.name.expression

String

Required/Optional

gallery.given_name

String

Required/Optional

gallery.given_name.value

String

Required/Optional

gallery.given_name.options

String[]

Required/Optional

gallery.given_name.expression

String

Required/Optional

gallery.family_name

String

Required/Optional

gallery.family_name.value

String

Required/Optional

gallery.family_name.options

String[]

Required/Optional

gallery.family_name.expression

String

Required/Optional

gallery.address

String

Required/Optional

gallery.address.value

String

Required/Optional

gallery.address.options

String[]

Required/Optional

gallery.address.expression

String

Required/Optional

gallery.birth_date

String

Required/Optional

gallery.birth_date.value

String

Required/Optional

gallery.birth_date.options

String[]

Required/Optional

gallery.birth_date.expression

String

Required/Optional

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
    "probe": {
        "name": "a",
        "given_name": "robert",
        "family_name": "woodward",
        "address": "123 street 1",
        "birth_date": "1990-01-01"
    },
    "gallery": {
        "name": {
            "value": "asdfasdf"
        },
        "given_name": {
            "value": "bob"
        },
        "family_name": {
            "value": "woodward"
        },
        "address": {
            "options": [
                "123 street 1",
                "123 street 2"
            ]
        },
        "birth_date": {
            "value": "1990-01-01"
        }
    }
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/environments/{{envID}}/users/{{userID}}/identityRecordMatching' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
    "probe": {
        "name": "a",
        "given_name": "robert",
        "family_name": "woodward",
        "address": "123 street 1",
        "birth_date": "1990-01-01"
    },
    "gallery": {
        "name": {
            "value": "asdfasdf"
        },
        "given_name": {
            "value": "bob"
        },
        "family_name": {
            "value": "woodward"
        },
        "address": {
            "options": [
                "123 street 1",
                "123 street 2"
            ]
        },
        "birth_date": {
            "value": "1990-01-01"
        }
    }
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/users/{{userID}}/identityRecordMatching")
{
  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" +
@"    ""probe"": {" + "\n" +
@"        ""name"": ""a""," + "\n" +
@"        ""given_name"": ""robert""," + "\n" +
@"        ""family_name"": ""woodward""," + "\n" +
@"        ""address"": ""123 street 1""," + "\n" +
@"        ""birth_date"": ""1990-01-01""" + "\n" +
@"    }," + "\n" +
@"    ""gallery"": {" + "\n" +
@"        ""name"": {" + "\n" +
@"            ""value"": ""asdfasdf""" + "\n" +
@"        }," + "\n" +
@"        ""given_name"": {" + "\n" +
@"            ""value"": ""bob""" + "\n" +
@"        }," + "\n" +
@"        ""family_name"": {" + "\n" +
@"            ""value"": ""woodward""" + "\n" +
@"        }," + "\n" +
@"        ""address"": {" + "\n" +
@"            ""options"": [" + "\n" +
@"                ""123 street 1""," + "\n" +
@"                ""123 street 2""" + "\n" +
@"            ]" + "\n" +
@"        }," + "\n" +
@"        ""birth_date"": {" + "\n" +
@"            ""value"": ""1990-01-01""" + "\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}}/identityRecordMatching"
  method := "POST"

  payload := strings.NewReader(`{
    "probe": {
        "name": "a",
        "given_name": "robert",
        "family_name": "woodward",
        "address": "123 street 1",
        "birth_date": "1990-01-01"
    },
    "gallery": {
        "name": {
            "value": "asdfasdf"
        },
        "given_name": {
            "value": "bob"
        },
        "family_name": {
            "value": "woodward"
        },
        "address": {
            "options": [
                "123 street 1",
                "123 street 2"
            ]
        },
        "birth_date": {
            "value": "1990-01-01"
        }
    }
}`)

  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}}/identityRecordMatching HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
    "probe": {
        "name": "a",
        "given_name": "robert",
        "family_name": "woodward",
        "address": "123 street 1",
        "birth_date": "1990-01-01"
    },
    "gallery": {
        "name": {
            "value": "asdfasdf"
        },
        "given_name": {
            "value": "bob"
        },
        "family_name": {
            "value": "woodward"
        },
        "address": {
            "options": [
                "123 street 1",
                "123 street 2"
            ]
        },
        "birth_date": {
            "value": "1990-01-01"
        }
    }
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"probe\": {\n        \"name\": \"a\",\n        \"given_name\": \"robert\",\n        \"family_name\": \"woodward\",\n        \"address\": \"123 street 1\",\n        \"birth_date\": \"1990-01-01\"\n    },\n    \"gallery\": {\n        \"name\": {\n            \"value\": \"asdfasdf\"\n        },\n        \"given_name\": {\n            \"value\": \"bob\"\n        },\n        \"family_name\": {\n            \"value\": \"woodward\"\n        },\n        \"address\": {\n            \"options\": [\n                \"123 street 1\",\n                \"123 street 2\"\n            ]\n        },\n        \"birth_date\": {\n            \"value\": \"1990-01-01\"\n        }\n    }\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/environments/{{envID}}/users/{{userID}}/identityRecordMatching")
  .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}}/identityRecordMatching",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "probe": {
      "name": "a",
      "given_name": "robert",
      "family_name": "woodward",
      "address": "123 street 1",
      "birth_date": "1990-01-01"
    },
    "gallery": {
      "name": {
        "value": "asdfasdf"
      },
      "given_name": {
        "value": "bob"
      },
      "family_name": {
        "value": "woodward"
      },
      "address": {
        "options": [
          "123 street 1",
          "123 street 2"
        ]
      },
      "birth_date": {
        "value": "1990-01-01"
      }
    }
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/environments/{{envID}}/users/{{userID}}/identityRecordMatching',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "probe": {
      "name": "a",
      "given_name": "robert",
      "family_name": "woodward",
      "address": "123 street 1",
      "birth_date": "1990-01-01"
    },
    "gallery": {
      "name": {
        "value": "asdfasdf"
      },
      "given_name": {
        "value": "bob"
      },
      "family_name": {
        "value": "woodward"
      },
      "address": {
        "options": [
          "123 street 1",
          "123 street 2"
        ]
      },
      "birth_date": {
        "value": "1990-01-01"
      }
    }
  })

};
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}}/identityRecordMatching"

payload = json.dumps({
  "probe": {
    "name": "a",
    "given_name": "robert",
    "family_name": "woodward",
    "address": "123 street 1",
    "birth_date": "1990-01-01"
  },
  "gallery": {
    "name": {
      "value": "asdfasdf"
    },
    "given_name": {
      "value": "bob"
    },
    "family_name": {
      "value": "woodward"
    },
    "address": {
      "options": [
        "123 street 1",
        "123 street 2"
      ]
    },
    "birth_date": {
      "value": "1990-01-01"
    }
  }
})
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}}/identityRecordMatching');
$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    "probe": {\n        "name": "a",\n        "given_name": "robert",\n        "family_name": "woodward",\n        "address": "123 street 1",\n        "birth_date": "1990-01-01"\n    },\n    "gallery": {\n        "name": {\n            "value": "asdfasdf"\n        },\n        "given_name": {\n            "value": "bob"\n        },\n        "family_name": {\n            "value": "woodward"\n        },\n        "address": {\n            "options": [\n                "123 street 1",\n                "123 street 2"\n            ]\n        },\n        "birth_date": {\n            "value": "1990-01-01"\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}}/identityRecordMatching")

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({
  "probe": {
    "name": "a",
    "given_name": "robert",
    "family_name": "woodward",
    "address": "123 street 1",
    "birth_date": "1990-01-01"
  },
  "gallery": {
    "name": {
      "value": "asdfasdf"
    },
    "given_name": {
      "value": "bob"
    },
    "family_name": {
      "value": "woodward"
    },
    "address": {
      "options": [
        "123 street 1",
        "123 street 2"
      ]
    },
    "birth_date": {
      "value": "1990-01-01"
    }
  }
})

response = http.request(request)
puts response.read_body
let parameters = "{\n    \"probe\": {\n        \"name\": \"a\",\n        \"given_name\": \"robert\",\n        \"family_name\": \"woodward\",\n        \"address\": \"123 street 1\",\n        \"birth_date\": \"1990-01-01\"\n    },\n    \"gallery\": {\n        \"name\": {\n            \"value\": \"asdfasdf\"\n        },\n        \"given_name\": {\n            \"value\": \"bob\"\n        },\n        \"family_name\": {\n            \"value\": \"woodward\"\n        },\n        \"address\": {\n            \"options\": [\n                \"123 street 1\",\n                \"123 street 2\"\n            ]\n        },\n        \"birth_date\": {\n            \"value\": \"1990-01-01\"\n        }\n    }\n}"
let postData = parameters.data(using: .utf8)

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

{
    "detailedResults": {
        "address": {
            "probeValue": "123 street 1",
            "galleryValue": "123 street 1",
            "rawScore": 1,
            "confidence": "HIGH"
        },
        "birth_date": {
            "probeValue": "1990-01-01",
            "galleryValue": "1990-01-01",
            "rawScore": 1,
            "confidence": "HIGH"
        },
        "name": {
            "probeValue": "a",
            "galleryValue": "asdfasdf",
            "rawScore": 0.7396754,
            "confidence": "MEDIUM"
        },
        "given_name": {
            "probeValue": "robert",
            "galleryValue": "bob",
            "rawScore": 0.87234503,
            "confidence": "MEDIUM"
        },
        "family_name": {
            "probeValue": "woodward",
            "galleryValue": "woodward",
            "rawScore": 1,
            "confidence": "HIGH"
        }
    },
    "overallWeightedScore": 0.9224040865898132,
    "overallConfidenceScore": "MEDIUM"
}