Facial identification (1:N Identification) - Rest PKI Core

• Searches a database of enrollments for the captured face, to find out whom it belongs to.
• Unlike authentication, it does not start from a known user.

note

Facial identification is a computationally expensive process, also known as a 1:N search. As a result, this feature may not be enabled on the instance you are integrating with. If you are interested in enabling it, contact us at suporte@lacunasoftware.com to request a demonstration.

Creating the session

To create an identification session, use the StartIdentificationSessionAsync method of the client libs, passing a StartBioIdentificationSessionRequest.

This method makes a POST request to /api/bio/sessions/identification (Swagger).

Parameters (StartBioIdentificationSessionRequest)

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)
FaceCaptureProvider	No	Enum	Sets the biometric provider. (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": "Identification",
  "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 an identification session, use the CompleteIdentificationSessionAsync method of the client libs, passing a CompleteBioSessionRequest.

This method makes a POST request to /api/bio/sessions/identification/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

{
  "identifiedSubjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "identifiedSubjectIdentifier": "string",
  "failure": "CaptureFailed",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "success": true,
  "resultDataAvailable": true
}

Field details

• identifiedSubjectId: on success, the Id of the enrollment of the person identified.
• identifiedSubjectIdentifier: on success, the SubjectIdentifier of the person identified.
• failure: tells whether a failure occurred during the session; see the list of failures below.
• sessionId: Id of the Rest PKI Core session.
• success: whether the identification session succeeded.
• resultDataAvailable: if true, you can fetch the photos collected in the session.

Failures

Enum	Description
CaptureFailed	The image capture could not be finished. It usually happens when the user interrupts it.
LivenessFailed	The user did not pass the liveness check: the number of attempts exceeded the limit.
NoMatch	The biometric collected did not reach the minimum match with any biometric enrolled in the database.
BadImage	The captured image does not have enough quality to be processed. It may be caused by poor lighting or blur.

Checking the 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 GetIdentificationSessionStatusAsync 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 CompleteIdentificationSessionAsync.