In this section, you will find the specifics of creating a process that has Liveness + Identity Verification + Behavior Alert + Risk Score as a capabilities.
In this section, you will find detailed documentation on the operation of the endpoints related to the capabilities Liveness + Identity Verification + Behavior Alert + Risk Score, used together.
This involves two synchronous capabilities (Liveness + Identity Verification) integrated with two asynchronous capabilities (Behavior Alert + Risk Score). That is, to obtain all the responses, it will be necessary to Get the Process Result.
For this integration, it will be necessary to consume two endpoints described in this documentation, which can also be combined with the use of Webhooks.
The capabilities of the Unico IDCloud platform via by Client are managed through API Keys - used as a parameter in the request headers - which define the access scope. As a prerequisite, it is necessary to have an API Key configured with the capabilities Liveness + Identity Verification + Behavior Alert + Risk Score, ensuring dedicated and secure access to the resource.
Talk to your project manager to obtain the API Key with this configuration.
Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error.
You can learn more about generating an access token here.
Endpoints:
Production: https://api.id.unico.app/processes/v1.
Important:
If the response from the Identity Verification capability is unicoId = yes, this return already includes the Liveness (i.e., you will not receive the liveness parameter in the response);
To use the Liveness capability, it is essential to use our SDKs.
It is possible to use the Identity Verification capability without Liveness. In this use case, the liveness return will always be liveness = 1. In this scenario, there is no validation of the Liveness, not even passive validation.
If the responses from the Identity Verification and Behavior Alert capabilities are unicoId = inconclusive + identityFraudsters = inconclusive, there will be orchestration with the Risk Score capability. If any of these responses is conclusive, there will be no orchestration with the Risk Score.
If an error occurs during processing, the process will return a status = 5, as shown in the example below:
Tips:
To implement your business rules, always validate the final statuses of the processes (3, 4, 5). To validate the response from the IDCloud capabilities, only consider the status = 3 for your decision-making.
In the v2 endpoint (/processes/v2/{id}), we also return some additional user information, as shown in the example below:
Attention:
When the GET request is for a process with status = 5 (error), the return status code will be 410 (Gone) instead of 200 (Success);
There may be cases of a drop in orchestration with the Risk Score capability. In this scenario, the process will have the combination: {status = 3, unicoId = inconclusive, liveness = 1, identityFraudsters = inconclusive, and NO score in the API response}. Learn more in the "Response Scenarios" section;
If you query a process that is in status = 2, implement polling until you get a status = 3, or implement Unico’s Webhook to know when to query the result.
Tips:
To implement your business rules, always validate the final statuses of the processes (3, 4, 5). To validate the response from the IDCloud capabilities, only consider status = 3 for your decision-making;
To improve the performance of your operation, you can use our Webhooks and only query the result of processes that are in the finalized statuses;
For more information about the scenarios you may receive in the response, refer to the "Response Scenarios" section;
For more information about possible errors for this endpoint, refer to the "Errors" section.
Still need help?
Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.
Endpoint to get the result of a Liveness + Identity Verification + Behavior Alert + Risk Score process by Client.
Process ID.
Valid access token.
Valid APIKEY with the capabilities Liveness + Identity Verification + Behavior Alert + Risk Score enabled.
Process information successfully retrieved.
Process ID.
"2b034568-dfaf-463f-94fb-18ed93c312e8"Process status. Possible values: '1' - In progress; '2' - Divergence (occurs when the risk score identifies a divergence for this face and is yet to conclude verification); '3' - Completed; '4' - Canceled (e.g., timeout); '5' - Error.
3Identity verification details.
Identity verification result. Possible values: 'yes' - It is the face of the CPF holder; 'no' - It is not the face of the CPF holder; 'inconclusive' - Unable to guarantee with certainty if it is the face of the CPF holder.
"inconclusive"Liveness result. Possible values: '1' - Liveness approved; '2' - Liveness rejected.
1Behavior Alert details.
Behavior Alert result. Possible values: 'yes' - The face has been involved in fraudulent identity transactions; 'inconclusive' - No evidence that the face has been involved in fraudulent identity transactions.
"inconclusive"Risk score result.
50Endpoint to create a new process for Liveness + Identity Verification + Behavior Alert + Risk Score in the by Client.
Valid access token.
Valid APIKEY with the capabilities Liveness + Identity Verification + Behavior Alert + Risk Score enabled.
User information.
User's CPF. Must contain 11 characters and be sent without dots or dashes.
"12345678909"User's name.
"Luke Skywalker"User's email.
"luke@unico.io"User's phone number. Must contain 13 characters and be sent without dots or dashes, in the format DDI + DDD + phone number.
"551972557070"Use case of the operation.
"Onboarding"The ID of the branch where the process will be created. If there is only one branch associated with the service account, this parameter is not required. If there is a separation of processes by branch, you will receive the branch IDs from the Unico team.
"60837cd3-ed3c-4038-ad7c-0a85ad64b03a"Encrypted file generated by the SDK or Base64 (if not using liveness).
"/9j/4AAQSkZJR..."Process successfully created.
Process ID.
"80371b2a-3ac7-432e-866d-57fe37896ac6"Process status. Possible values: '1' - Processing; '4' - Canceled (e.g., timeout); '5' - Error.
1Information about identity verification.
Identity verification result. Possible values: 'yes' - Matches the CPF holder's face; 'no' - Does not match the CPF holder's face; 'inconclusive' - Unable to ensure if this is the CPF holder's face.
"inconclusive"Liveness result. Possible values: '1' - Liveness approved; '2' - Liveness denied.
1