PingOne Platform APIs

Verify Documents

For each verification transaction, you can read documents (such as the images of documents and images of the user, "selfies") submitted to the transaction for a short time. The documents endpoint, /v1/environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/documents, receives all requests for documents associated with the verification transaction. This endpoint returns the data regardless of whether the transaction is ever submitted for verification.

Only those with an Identity Data Admin role are permitted to use the documents endpoint.

Documents are retained for 30 minutes after creating or updating the document (submitted with the requests Create Verification Document or Update Verification Document or collected by the end user in the Universal Capture frontend) or until manually deleted with Delete Verification Document. Until removed, any number of GET or PUT requests to the documents endpoint can be successfully performed.

The document types accepted by a verify transaction is determined by the verify transaction’s requirements object and the verify policy identified by the verify transaction’s verifyPolicy.id. If a document is unacceptable, an error is returned that is similar to:

{
    "id": "05f2cbb8-bd1b-41b1-abf0-d5fc4fc4c875",
    "code": "INVALID_DATA",
    "message": "The request could not be completed. One or more validation errors were in the request.",
    "details": [
        {
            "code": "INVALID_VALUE",
            "target": "type",
            "message": "invalid document type for transaction"
        }
    ]
}

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.

All verify documents data model

When all verify documents for a verification transaction are requested, the verify document for each verification type of the most recent retry appears in a documents array in the response. The verify document data model for each verification type of earlier retries appear in a previousAttempts array in the response.

Property Type Required Mutable Description

_embedded

Object

N/A

Read-only

Container for returned data.

documents

Object[]

N/A

Read-only

Array of verifiedData objects for each verification type for the most recent verification attempt.

previousAttempts

Object[]

N/A

Read-only

Array of verifiedData objects for each verification type for unacceptable verification attempts.

size

Integer

N/A

Read-only

The number of objects returned in documents.

Specific verify document data model

When specific verify document for a verification type within a verification transaction are requested, the verify document data model appears as the response, regardless of which retry attempt it is.

Verify document data model

Property Type Required Mutable Description

environment.id

String

Required

Immutable

PingOne environment identifier (UUID) for user

id

String

N/A

Read-only

Document identifier (UUID)

retry.attempt

Integer

N/A

Read-only

Number of the retry attempt when submitting images.

source.provider

String

Required

Immutable

Provider of the documents. Can be END_USER, AUTHENTICATED_CLIENT.

status

String

N/A

Read-only

Status of the document. Can be COLLECTED or PROCESSED.

type

String

Required

Immutable

Type of document in value. Refer to Document types and values.

user.id

String

Required

Immutable

Identifier (UUID) for the user submitting the verify transaction

value

String

Required

Immutable

Document, for the format of the document refer to Document types and values

verifyTransaction.id

String

Required

Immutable

Identifier (UUID) for the verify transaction

Document types and values

Document Type Value

Credential Verification

W3C Verifiable Credential or ISO 18013 Mobile driving license (mDL) or Mobile document (mDoc)

Document Back

Base64 encoded JPEG

Document Front

Base64 encoded JPEG

Document Portrait

Base64 encoded JPEG

Driver License Back

Base64 encoded JPEG

Driver License Code

decoded text from the PDF417 barcode

Driver License Front

Base64 encoded JPEG

Email

textual email address

Passport Card Back

Base64 encoded JPEG

Passport Card Front

Base64 encoded JPEG

Passport Front

Base64 encoded JPEG

Phone

textual phone number

Selfie

Base64 encoded JPEG

Verify documents errors

In addition to the general error codes, verify documents operations can return the following errors:

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

400

INVALID_DATA

EMPTY_VALUE

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

When and details

When: Submit Create Verification Document or Update Verification Document with a missing or null type or value property

Details: must not be null for an omitted or null type or value, for example Validation Error : [type must not be null]

400

INVALID_DATA

REQUIRED_VALUE

Message: The request is missing a required value.

When and details

When: Submit Create Verification Document as multipart form data without the required file request part

Details: missing required request part. The target is file.

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: Submit Create Verification Document or Update Verification Document with a document the service rejects

Details: INVALID_VALUE with target type and message invalid document type for transaction when the document type is not accepted by the transaction’s policy requirements. The value target carries the document validation message, for example must be a valid JPEG image, must be a base64 encoded string, cannot duplicate document value, value does not match requirement options, or document type conflicts with existing documents

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: Submit Create Verification Document as multipart form data with a file the service cannot read, or with a document type that does not accept files

Details: invalid multipart file when the file cannot be read, or multipart file not supported for document type for a type that does not accept file upload (email, phone, and barcode types)

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: Submit Create Verification Document or Update Verification Document with a malformed JSON request body

Details: INVALID_VALUE where the target is the JSON path of the property that failed to deserialize and the message is Invalid value for attribute.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: Submit Create Verification Document after the end user has started document collection, submit Create Verification Document with a document type that already exists and cannot be recollected, or submit any verify documents operation when the transaction has expired

Details: cannot create documents after end user has started document collection, document type already exists with target type, or transactionTimeout with message The document verification transaction timeout has been exceeded. when the transaction’s expiresAt has passed

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: Submit Create Verification Document, Update Verification Document, Process Verification Documents, or Complete Verification Documents when the transaction status does not allow document changes

Details: CONSTRAINT_VIOLATION with message 140: Validation status not in the Expected STATUS

400

INVALID_DATA

REQUIRED_VALUE

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

When and details

When: Submit Process Verification Documents or Complete Verification Documents without enough collected data

Details: not enough data collected to process any verifications for the Process Verification Documents request, or not enough data collected to complete required verifications for the Complete Verification Documents request

400

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

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

When and details

When: Submit Update Verification Document, Process Verification Documents, or Complete Verification Documents for documents collected by the end user

Details: cannot modify documents collected by end user

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the required idverifications:<verb>:document permission (get for the GET operations, create for POST Create Verification Document, update for PUT Update Verification Document, POST Process Verification Documents, and POST Complete Verification Documents, or delete for the DELETE operations), or the actor is not authorized to access the {{userID}} user resource

Details: None

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: Submit Read One Verification Document, Update Verification Document, or Delete Verification Document with a {{documentID}} that does not exist, submit any verify documents operation with a {{transactionID}} that does not exist, or submit any verify documents operation with an {{envID}} that does not exist

Details: document not found with target document for an unknown {{documentID}}, or verifyTransaction not found with target verifyTransaction for an unknown {{transactionID}}