PingOne Recognize

PingOne Recognize Agent endpoints

The following endpoints are available for IDV Bridge On-Premise (PingOne Recognize Agent).

GET /health-check

Purpose: Check if the service is running.

Response:

{
  "version": "string",
  "status": "ok"
}

POST /v1/offline-enrollment

Purpose: Generate client and server enrollment states from an image.

The server state is required to register the new user on the PingOne Recognize backend, while client state enables the account recovery flow for ongoing authentication on a camera-enabled device through the Mobile SDK.

Request:

  • Headers:

    • Exif-Transpose (boolean, optional) — whether to rotate the image according to EXIF metadata.

    • Content-Encoding (optional, const="base64") — if the image is base64 encoded.

    • Scenario (required) — "SELFIE" | "TRUSTED_SOURCE" | "DOCUMENT".

  • Body: image/* — binary (JPEG, PNG, BMP, and so on)

Responses:

  • 200: Returns OfflineEnrollment

  • 422: Returns FilterTriggered

  • 429: Too many concurrent enrollments

scenario definitions are available here.

POST /v1/online-enrollment

Purpose: Enroll a user directly from an image (without server state).

Client state enables the account recovery flow for ongoing authentication on a camera-enabled device through the Mobile SDK.

Request: Same headers and body as offline enrollment.

Responses:

  • 200: Returns OnlineEnrollment

  • 409: Not configured for online enrollment

  • 422: Recognition filter error

  • 429: Too many concurrent enrollments

Schemas

OfflineEnrollment

Field Type Description

keylessId

string

Unique user ID

clientState

string

Opaque data for the PingOne Recognize SDK to allow a user to authenticate on a camera-enabled device for the account recovery flow.

serverState

string

Uncommitted server data. Required to register the new user on the PingOne Recognize backend.

OnlineEnrollment

Field Type Description

keylessId

string

Unique user ID

clientState

string

Opaque data for the PingOne Recognize SDK to allow a user to authenticate on a camera-enabled device for the account recovery flow.

FilterTriggered

Field Type Description

title

string

Always "Filter Triggered"

statusCode

integer

Always 422

detail

string

Explanation of why the filters failed

filters

object

See below

Filters

Each property represents a possible filter and has one of the following statuses:

  • TRIGGERED — filter was triggered (failure)

  • NOT_TRIGGERED — filter passed

  • TURNED_OFF — filter not active

  • CANNOT_RUN_ON_FRAME — preprocessing failure

Filter Description

faceIsOccluded

The facial features are partially covered to the extent that a biometric template couldn’t be detected.

faceMissing

No face was detected in the image.

faceMultiple

More than one face was detected.

facePartial

Only a partial face was detected. For example, the selfie might’ve been off-center.

faceTooSmall

A face was detected, but it was too small to allow an accurate biometric template to be generated.

imageBlackAndWhite

The image is black and white.

Example 422 error

{
  "title": "Filter Triggered",
  "statusCode": 422,
  "detail": "Face occluded by object",
  "filters": {
    "faceIsOccluded": "TRIGGERED",
    "faceMissing": "NOT_TRIGGERED",
    "faceMultiple": "NOT_TRIGGERED",
    "facePartial": "NOT_TRIGGERED",
    "faceTooSmall": "NOT_TRIGGERED",
    "imageBlackAndWhite": "NOT_TRIGGERED"
  }
}