Document capture (IdentificationDocumentCapture) - Rest PKI Core

• Captures the image of an identification document, including the front, the back and a crop of the face picture.

tip

A document can also be captured in the same session as a liveness check or a biometric enrollment, using the CaptureIdentificationDocument parameter. In those cases, the photo of the person on the document is also compared with the face biometric captured.

Creating the session

To create a document capture session, use the StartIdentificationDocumentCaptureSessionAsync method of the client libs, passing a StartIdentificationDocumentCaptureSessionRequest.

This method makes a POST request to /api/bio/sessions/id-capture (Swagger).

Parameters (StartIdentificationDocumentCaptureSessionRequest)

Parameter	Required?	Type	Description
ReturnUrl	Conditional*	String	URL to redirect the user to after the biometric check. (see details)
TrustedOrigin	Conditional*	String	URL of your site where the widget is embedded. (see details)
PlatformPreference	No	Enum	Sets the platform preference and the QR code behavior. (see details)
SubjectIdentifier	No	String	External identifier of the user. (see details)

tip

*You must pass at least one of the two parameters (see the difference between ReturnUrl and TrustedOrigin):

• ReturnUrl (for the redirect flow)
• TrustedOrigin (for the widget)

Optional parameters can be left blank (null) and are filled in automatically with the system defaults.

Response example

{
  "sessionType": "IdentificationDocumentCapture",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sessionUrl": "string"
}

Frontend integration

Once your backend has obtained the sessionUrl from the API, forward it to your frontend. From there, the flow follows the interface you chose:

• Embedded flow (widget): your application passes the URL to the JavaScript component, which starts the capture inside your page.

• Redirect flow: your application sends the user to the URL received, where the capture takes place.

tip

If you are unsure how to implement each model, see Frontend flows.

---

Completing the session

To complete a document capture session, use the CompleteIdentificationDocumentCaptureSessionAsync method of the client libs, passing a CompleteBioSessionRequest.

This method makes a POST request to /api/bio/sessions/id-capture/completion (Swagger).

This method is the final step. The ticket can be used only once.

tip

Call the completion only at the end of the process, sending the ticket you received to validate the result and close the session.

Response example

{
  "subjectIdentifier": "string",
  "idCaptureStatus": {
    "success": true,
    "matchedFace": true,
    "matchedFaceLevel": 0
  },
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "success": true,
  "resultDataAvailable": true
}

Field details

• subjectIdentifier: external identifier of the user. (see details)
• idCaptureStatus:
  • success: whether the document capture succeeded.
  • matchedFace: whether the person's face matched the photo on the document.
  • matchedFaceLevel: similarity level between the face and the document (MatchLevel).
• sessionId: unique identifier of the session.
• success: overall result of the session.
• resultDataAvailable: if true, you can fetch the photos collected in the session.

---

Checking the session status

You can check the current state of a session at any time using its sessionId. This is useful to monitor whether the user has started the session, or whether it has expired, even before it is completed.

tip

Use GetIdentificationDocumentCaptureSessionStatusAsync to follow the progress of an active session by its sessionId.

The response of this endpoint is exactly the same as the response example of CompleteIdentificationDocumentCaptureSessionAsync.