Liveness + Identity Verification + Risk Score

In this section, you will find the specifics of creating a process that has Liveness + Identity Verification + Risk score as a capabilities

---

Introduction

---

In this section, you will find detailed documentation about the functionality of the endpoints related to the Liveness + Identity Verification + Risk Score capabilities, used together.

These consist of two synchronous capabilities (Liveness + Identity Verification) integrated with one asynchronous capability (Risk Score). In other words, while most processes will return synchronous responses, some will be orchestrated with the Risk Score and will require subsequent queries.

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 Client are managed through API Keys—used as a parameter in the request headers—that define the access scope. As a prerequisite, it is necessary to have an API Key configured with the Liveness + Identity Verification + Risk Score capabilities, ensuring dedicated and secure access to the resource.

Talk to your project manager to obtain the API Key with this configuration.

Getting started

---

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:

• UAT: https://api.id.uat.unico.app/processes/v1;

• Production: https://api.id.unico.app/processes/v1.

CreateProcess

---

Create Process

Endpoint to create a new process for Liveness + Identity Verification + Risk Score by Client.

POSThttps://api.id.uat.unico.app/processes/v1/

Header parameters

Body

application/json

subject*object

User information.

useCase*string

Use case of the operation.

Example: "Onboarding"

subsidiaryIdstring

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.

Example: "60837cd3-ed3c-4038-ad7c-0a85ad64b03a"

imageBase64*string

Encrypted file generated by the SDK or base64 (if not using Liveness).

Example: "/9j/4AAQSkZJR..."

Response

200400500

Process created successfully (INCONCLUSIVE for Identity Verification and forwarded to Risk Score).

Body

application/json

idstring

Process ID.

Example: "80371b2a-3ac7-432e-866d-57fe37896ac6"

statusenum

Process status. Possible values: '1' - In processing (occurs when forwarded to Risk Score); '3' - Completed; '4' - Canceled (e.g., timeout); '5' - Error.

Example: 1

1345

unicoIdobject

Information about the identity verification.

livenessenum

Result of Liveness. Possible values: '1' - Liveness approved; '2' - Liveness rejected.

Example: 1

12

Request

JavaScriptCurlPython

const response = await fetch('https://api.id.uat.unico.app/processes/v1/', {
    method: 'POST',
    headers: {
      "Authorization": "text",
      "APIKEY": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "subject": {
        "code": "12345678909",
        "name": "Luke Skywalker"
      },
      "useCase": "Onboarding",
      "imageBase64": "/9j/4AAQSkZJR..."
    }),
});
const data = await response.json();

Response

200400500

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 1,
  "unicoId": {
    "result": "inconclusive"
  },
  "liveness": 1
}

Important:

• If the response for the Identity Verification capability returns unicoId = yes, this result already includes Liveness (i.e., the liveness parameter will not be included in the response);

• To use the Liveness capability, it is mandatory to use our SDKs;

  • It is possible to use the Identity Verification capability without Liveness. For this use case, the liveness value will always return as liveness = 1. In this scenario, no Liveness validation is performed, not even passive validation.

• If the response for the Identity Verification capability is unicoId = inconclusive, orchestration with the Risk Score capability will occur. Therefore, it will be necessary to Get the Process Result (endpoint described below), as the Risk Score response is asynchronous.

• If an error occurs during biometric processing, the request will return a status code = 200, and the process will return a status = 5, as shown in the example below:

    {
    "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "status": 5
    }

Tips:

• When implementing your business rules, always validate the final statuses of the processes (3, 4, 5). To validate the response of IDCloud capabilities, only consider status = 3 for your decision-making process:

  • A percentage of your operation will have a conclusive response from the Identity Verification capability (yes or no). For these, you can decide whether to approve or reject the registration without needing to Get the Process Result;

  • For cases where the response from the Identity Verification capability is inconclusive (inconclusive), it will be necessary to Get the Process Result.

GetProcess

---

GetProcess

Endpoint to get the result of an Liveness + Identity Verification + Risk Score process by Client.

GEThttps://api.id.uat.unico.app/processes/v1/{processId}

Path parameters

processId*string

Process ID.

Header parameters

Response

200400403404410500

Process information successfully retrieved.

Body

application/json

idstring

Process ID.

Example: "2b034568-dfaf-463f-94fb-18ed93c312e8"

statusenum

Process status. Possible values: '1' - Processing (occurs when forwarded for Risk Score evaluation); '2' - Divergence (occurs when the Risk Score detects a divergence for this face and verification is still in progress); '3' - Completed; '4' - Canceled (e.g., timeout); '5' - Error.

Example: 3

12345

unicoIdobject

Information about identity verification.

livenessenum

Liveness result. Possible values: '1' - Liveness approved; '2' - Liveness rejected.

Example: 1

12

scoreinteger

Risk score result.

Example: 50

Request

JavaScriptCurlPython

const response = await fetch('https://api.id.uat.unico.app/processes/v1/{processId}', {
    method: 'GET',
    headers: {
      "Authorization": "text",
      "APIKEY": "text"
    },
});
const data = await response.json();

Response

200400403404410500

{
  "id": "2b034568-dfaf-463f-94fb-18ed93c312e8",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "liveness": 1,
  "score": 50
}

In the v2 endpoint (/processes/v2/{id}), we also return additional user information, as shown in the example below:

"processAdditionalInfo": {
      "transactionId": "2ed76ac5-8fd7-4477-839d-92bedd7e9fd5",
      "personName": "Nome da pessoa",
      "personDocument": "Número do documento da pessoa",
      "personImage": "URL assinada da imagem da pessoa",
      "finishedAt": "2024-10-04T18:53:17.028228"
  }
}

Attention:

• When making a GET request for a process with status = 5 (error), the return status code will be 410 (Gone) instead of 200 (Success);

• There may be cases of drops during orchestration with the Risk Score capability. In this scenario, the process will have the following combination: {status = 3, unicoId = inconclusive, liveness = 1, and NO score in the API response}. Learn more in the Response Scenarios section;

• If you query a process with status = 2, implement polling until you receive status = 3 or implement Unico's Webhook to know when to get the result.

Tips:

• When implementing your business rules, always validate the final statuses of the processes (3, 4, 5). To validate the response of IDCloud capabilities, only consider status = 3 for your decision-making process;

• To improve the performance of your operation, you can use our Webhooks and only query the results of processes that have a finalized status;

• For more details on the scenarios you might 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.