PingOne Platform APIs

Verify Identity Record Matching

With the Verify Identity Record Matching service, you can submit any of name, given name, family name, birth date, or address from an unverified source and corresponding values from one or more verified sources. The identityRecordMatching endpoint, /v1/environments/{{envID}}/users/{{userID}}/identityRecordMatching, compares the unverified biographic data to the verified biographic data, and returns a raw score and confidence level of the match.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Verify identity record matching request data model

Property Type Required Mutable Description

probe

Object

Required

Mutable

Object containing the data submitted from the document to match. At least one property is required.

probe.address

String

Required/Optional

Mutable

Address of the identity submitted from the document to match

probe.birth_date

String

Required/Optional

Mutable

Birth date name of the identity submitted from the document to match

probe.family_name

String

Required/Optional

Mutable

Family name of the identity submitted from the document to match

probe.given_name

String

Required/Optional

Mutable

Given name of the identity submitted from the document to match

probe.name

String

Required/Optional

Mutable

Name of the identity submitted from the document to match

gallery

Object

Required

Mutable

Object containing the data submitted from source records to match. A property is required for each probe property submitted.

gallery.address

String

Required/Optional

Mutable

Address of the identity submitted from the document to match

gallery.address.expression

String

Required/Optional

Mutable

PingOne Expression Language (PEL) expression to retrieve the address value, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, refer to PingOne expression language.

gallery.address.options

String[]

Required/Optional

Mutable

Array of literal address values to match.

gallery.address.value

String

Required/Optional

Mutable

Literal address value to match.

gallery.birth_date

String

Required/Optional

Mutable

Birth date name of the identity submitted from the document to match

gallery.birth_date.expression

String

Required/Optional

Mutable

PingOne Expression Language (PEL) expression to retrieve the birth_date value, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, refer to PingOne expression language.

gallery.birth_date.options

String[]

Required/Optional

Mutable

Array of literal birth_date values to match.

gallery.birth_date.value

String

Required/Optional

Mutable

Literal birth_date value to match.

gallery.family_name

String

Required/Optional

Mutable

Family name of the identity submitted from the document to match

gallery.family_name.expression

String

Required/Optional

Mutable

PingOne Expression Language (PEL) expression to retrieve the family_name value, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, refer to PingOne expression language.

gallery.family_name.options

String[]

Required/Optional

Mutable

Array of literal family_name values to match.

gallery.family_name.value

String

Required/Optional

Mutable

Literal family_name value to match.

gallery.given_name

String

Required/Optional

Mutable

Given name of the identity submitted from the document to match

gallery.given_name.expression

String

Required/Optional

Mutable

PingOne Expression Language (PEL) expression to retrieve the given_name value, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, refer to PingOne expression language.

gallery.given_name.options

String[]

Required/Optional

Mutable

Array of literal given_name values to match.

gallery.given_name.value

String

Required/Optional

Mutable

Literal given_name value to match.

gallery.name

String

Required/Optional

Mutable

Name of the identity submitted from the document to match.

gallery.name.expression

String

Required/Optional

Mutable

PingOne Expression Language (PEL) expression to retrieve the name value to match, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, refer to PingOne expression language.

gallery.name.options

String[]

Required/Optional

Mutable

Array of literal name values to match.

gallery.name.value

String

Required/Optional

Mutable

Literal name value to match.

Verify identity record matching response data model

Property Type Required Mutable Description

detailedResults.address

String

N/A

Read-only

Address of the identity.

detailedResults.address.
confidence

String

N/A

Read-only

Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.

detailedResults.address.
probeValue

String

N/A

Read-only

Value of address found on the government ID of the identity.

detailedResults.address.
rawScore

String

N/A

Read-only

Raw numeric score returned by the service. Ranges from 0 to 1.

detailedResults.address.
galleryValue

String

N/A

Read-only

Value of address on reference records provided by the requester.

detailedResults.birth_date

String

N/A

Read-only

Birth date of the identity in ISO 8601 YYYY-MM-DD format.

detailedResults.birth_date.
confidence

String

N/A

Read-only

Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.

detailedResults.birth_date.
probeValue

String

N/A

Read-only

Value of birth date found on the government ID of the identity.

detailedResults.birth_date.
rawScore

String

N/A

Read-only

Raw numeric score returned by the service. Ranges from 0 to 1.

detailedResults.birth_date.
galleryValue

String

N/A

Read-only

Value of birth date on reference records provided by the requester.

detailedResults.family_name

String

N/A

Read-only

Family name of the identity.

detailedResults.family_name.
confidence

String

N/A

Read-only

Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.

detailedResults.family_name.
probeValue

String

N/A

Read-only

Value of family name found on the government ID of the identity.

detailedResults.family_name.
rawScore

String

N/A

Read-only

Raw numeric score returned by the service. Ranges from 0 to 1.

detailedResults.family_name.
galleryValue

String

N/A

Read-only

Value of family name on reference records provided by the requester.

detailedResults.given_name

String

N/A

Read-only

Given name of the identity. Can optionally include middle name.

detailedResults.given_name.
confidence

String

N/A

Read-only

Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.

detailedResults.given_name.
probeValue

String

N/A

Read-only

Value of given name found on the government ID of the identity.

detailedResults.given_name.
rawScore

String

N/A

Read-only

Raw numeric score returned by the service. Ranges from 0 to 1.

detailedResults.given_name.
galleryValue

String

N/A

Read-only

Value of given name on reference records provided by the requester.

detailedResults.name

String

N/A

Read-only

Full name of the identity.

detailedResults.name.
confidence

String

N/A

Read-only

Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.

detailedResults.name.
probeValue

String

N/A

Read-only

Value of name found on the government ID of the identity.

detailedResults.name.
rawScore

String

N/A

Read-only

Raw numeric score returned by the service. Ranges from 0 to 1.

detailedResults.name.
galleryValue

String

N/A

Read-only

Value of name on reference records provided by the requester.

overallWeightedResult

String

N/A

Read-only

Weighted result of all reviewed fields. Can be HIGH, MEDIUM, LOW, or NONE. The lowest confidence value of non-zero rawScore results.

overallWeightedScore

Decimal

N/A

Read-only

Weighted score of all reviewed fields. A decimal number between 0 and 1. The average of all non-zero rawScore results.

A confidence of NONE occurs when rawScore is very low or when a governmentIdValue value is missing but its corresponding requirementsValue is valued.

Verify identity record matching errors

In addition to the general error codes, identity record matching operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST /environments/{envID}/users/{userID}/identityRecordMatching request omits or empties probe or gallery, supplies different property sets in probe and gallery, supplies an unsupported property name, omits a probe value, or supplies a birth_date that is not a valid YYYY-MM-DD date in probe or gallery

Details: cannot be null or empty for an omitted or empty probe or gallery with target probe or gallery, must have the same number of entries when the maps differ in size with target probe and gallery, must have the same entries when a probe property has no matching gallery property with target probe and gallery, not a valid entry for an unsupported probe property name with target probe.<property>, cannot be null for a null probe value with target probe.<property>, value cannot be null or empty for a blank probe value with target probe.<property>, cannot be null for a null gallery entry with target gallery[<property>], or value must be a valid date in YYYY-MM-DD format for a malformed birth_date in probe or gallery with target probe.birth_date or gallery.birth_date, for example Validation Error : [probe cannot be null or empty]

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A gallery entry violates the requirement value rules, or a gallery.expression cannot be resolved against the user

Details: For a gallery entry, value must be non-empty or null for a blank value, options must be non-empty or null for an empty options array, option entries must not be null or empty for a null or blank option, options cannot contain duplicates for duplicate options, must set either value, options, or expression when none is set, cannot set more than one of value, options, or expression when two or more are set, or expression must be non-empty or null for a blank expression, all with target gallery.<property>. For an unresolvable expression, unable to evaluate expression <expression>, expression resolved to empty string <expression>, or expression failed to resolve to a valid date in YYYY-MM-DD format <expression>, all with target gallery.<property>

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The environment does not have the identity record matching feature flag enabled, or the environment is not licensed for Verify

Details: environment does not have identityRecordMatching enabled with no target, or You are not licensed to make this request. with target license

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the idverifications:create:identityRecordMatching permission, or the actor is authorized for the environment but not for the target user, the user’s population, or a group containing the user

Details: None

404

NOT_FOUND

None

Message: environment could not be found or user could not be found

When and details

When: The envID path parameter references an environment that does not exist, or the userID path parameter references a user that does not exist

Details: None

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The matching provider returns no usable result for the request

Details: None