Pular para o conteúdo principal

Biometric enrollment (Enrollment) - Rest PKI Core

  • Registers the user's biometric in the system through a face capture with a liveness check.
  • The face image is processed and stored encrypted, to be used later in authentication or identification operations.

Creating the session​

To create an enrollment session, use the StartEnrollmentSessionAsync method of the client libs, passing a StartBioEnrollmentSessionRequest.

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

Parameters (StartBioEnrollmentSessionRequest)​

ParameterRequired?TypeDescription
ReturnUrlConditional*StringURL to redirect the user to after the biometric check. (see details)
TrustedOriginConditional*StringURL of your site where the widget is embedded. (see details)
PlatformPreferenceNoEnumSets the platform preference and the QR code behavior. (see details)
SubjectIdentifierYesStringExternal identifier of the user. (see details)
FaceCaptureProviderNoEnumSets the biometric provider. (see details)
CaptureIdentificationDocumentNoBoolIf enabled, the user must capture an ID document right after the liveness check.
DangerousOverrideIfAlreadyEnrolledNoBoolWhether the system allows an existing enrollment to be overwritten.
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)

Response example​

The request to StartEnrollmentSessionAsync returns the following response:

{
  "sessionType": "Enrollment",
  "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 enrollment session, use the CompleteEnrollmentSessionAsync method of the client libs, passing a CompleteBioSessionRequest.

This method makes a POST request to /api/bio/sessions/enrollment/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",
  "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "livenessStatus": {
    "success": true,
    "attemptCount": 2
  },
  "idCaptureStatus": {
    "success": true,
    "matchedFace": true,
    "matchedFaceLevel": 1
  },
  "failure": "FaceNotFoundWithSufficientQuality",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "success": true,
  "resultDataAvailable": true
}
tip

Note that in this example the subjectId was returned because the enrollment was not completed: the failure code tells us that this user is already enrolled.

Field details​

  • subjectIdentifier: a name or Id that identifies the user of the session.
  • subjectId: Id of the enrollment.
  • livenessStatus:
    • success: whether the liveness check succeeded.
    • attemptCount: number of attempts made by the user.
  • 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).
  • failure: tells whether a failure occurred during the session; see the list of failures below.
  • success: whether the enrollment session succeeded.
  • resultDataAvailable: if true, you can fetch the photos collected in the session.
Failures​
EnumDescription
FaceNotFoundWithSufficientQualityThe system could not detect a face sharp enough. It usually happens because of poor lighting, blur or a low-quality camera.
FaceLiveness2dFailedThe 2D liveness analysis detected that the face presented is not real.
FaceCaptureFailedA technical error or interruption happened during the image capture, preventing it from being processed.
DocumentCaptureFailedThe image of the ID document could not be captured or processed.
FaceIdentityVerificationFailedThe external identity verification failed.
DuplicatesFoundDuring an enrollment, the system found that this biometric already belongs to another user registered in the database.
AttemptsLimitReachedThe user exceeded the maximum number of attempts allowed for the biometric capture in the session.
SessionAbortedThe session was ended prematurely, by the user or by the system, before the process was completed.

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 GetEnrollmentSessionStatusAsync 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 CompleteEnrollmentSessionAsync.

View as Markdown