1 de 15

Integração by Client

Nesta seção, você encontrará todas as especificações técnicas das APIs REST do IDCloud, utilizando o meio de integração by Client

Overview

In this section, you will find all the technical specifications for By Client REST APIs

Introduction

By Client is a channel that provides complete freedom for clients to leverage the IDCloud platform’s identity validation solutions. It aims to offer a wide range of possibilities in using IDCloud platform capabilities, delivering a solution that can be integrated with your back-end and allowing clients to control the user experience with their own front-end (for this, see Capture Standard) or through our SDKs.

Available Flows

By Client is an integration method for Unico IDCloud that allows clients to integrate as they see fit, combining or not combining capabilities as needed. This integration method provides the necessary resources for performing Proof of Life, Fraud Profile Detection, Identity Verification, and Document Capture and Reuse validation.

You can combine capabilities as desired and use them in various cases; however, API Keys configured with the desired capabilities are required.

o request specific capabilities for an API Key, please contact your integration project manager or Unico’s support team for assistance with the configuration.

See below for all possible capability combinations in By Client:

You can also use the above capabilities without the Liveness Detection if you already have a Liveness provider in your operation. I
f you use the Identity Verification capability, regardless of any other combinations, it’s also possible to retrieve the Serpro similarity result (click here to learn more).

Synchronous and Asynchronous Capabilities

In by Client, there are capabilities with synchronous responses (meaning the response is provided immediately upon process creation) and asynchronous capabilities (where data processing requires that you "retrieve" the result through a GET method on the REST API).

In your operation, you can combine capabilities as you see fit, but each capability has its own communication method. For example:

You might operate with both Identity Verification and Fraud Profile Detection capabilities.
When creating the process, the response for Identity Verification will be synchronous and included in the API response.
Fraud Profile Detection, however, will operate asynchronously, requiring a wait for processing and then a separate GET request to obtain the final result.

Below are the synchronous and asynchronous capabilities:

Synchronous Capabilities

Liveness:

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

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

Identity verification:

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

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

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

Validation (1:1)

{
    "authenticated": "true"
}

{
    "authenticated": "false"
}

Asynchronous Capabilities

Identity verification:

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

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

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

Just like the Identity Verification capability is a "synchronous" capability, it can also be configured for "asynchronous" use.

Risk scoring:

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

Fraud Profile Detection:

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

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

Document capture and reuse:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": 3,
  },
  "document": {
    "id": "b97c3fd9-d95d-413f-bc0a-75eb87304421",
    "type": "CNH",
    "cpfMatch": false,
    "content": {
      "numero": "044589731564",
      "rgNumero": "123456789 SESP PR",
      "nomeCivil": "Homer Simpson",
      "filiacao": [
        "Monasimpson",
        "Monasimpson"
      ],
      "dataNascimento": "1990-05-12T00:00:00Z",
      "dataHabilitacao": "1997-11-18T00:00:00Z",
      "dataExpiracao": "2017-12-07T00:00:00Z",
      "dataEmissao": "2012-12-07T00:00:00Z",
      "localEmissao": "Curitiba PR",
      "categoria": "B",
      "renachNumero": "PR904987581"
    },
    "fileUrls": [
            "https://url-signer-1",
            "https://url-signer-2"
        ]
  }
}

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.

Capture standard (without SDK)

In this section, you will find how the capture standard for the user's selfie should be if you do not use our SDKs

For optimal performance of the IDCloud platform's capabilities, we recommend using our SDKs. They will ensure the best functioning of the product as a whole, both in terms of drop rate and in validating the Liveness.

To achieve better results in image capture, a capture standard has been defined. The image should be clear with sufficient frontal lighting. The face should be straight, facing the camera, free from objects or obstructions, and with a neutral expression.

Common issues in captured images include:

Lighting behind the client: Frontal lighting must be strong enough for a clear capture of the face.
Overexposed lighting: Frontal lighting needs to be adequate for a sharp capture.
Face too close to the camera: The face should be centered in the camera frame with proper lighting.
Blurry images: The person’s face needs to be well-focused at the moment of capture.
Shaky images: Stabilize the camera during capture.
Client wearing glasses: The client should not wear glasses or objects that obstruct full visibility of the face.

How to Obtain a Good Image Capture

For capturing and sending images, the ICAO standard is used. The ICAO (International Civil Aviation Organization) standard consists of characteristics that a photograph must comply with regarding capture and sending configurations:

Face Positioning and Additional Information:

The photo must be taken from the front—looking directly at the camera with the head upright. The face should be centered, and the shoulders must be aligned parallel to the camera's image plane.
The eyes should be naturally open—pupils and irises visible.
Glasses: The photo should be captured without glasses.
No hats, caps, or masks: The facial area must be clearly visible.
Neutral Expression: The face should maintain a neutral expression; the person should not smile, raise eyebrows, squint, or frown.
Hairstyle: Hair should not cover the eye visibility zone.

Lighting and Background:

The background should be light, smooth, and free of texture. It must not have stains, lines, or curves that are visible in the captured image. Light colors like light blue or white can be used, provided there is sufficient contrast between the face/hair area and the background.
The camera's color settings should not change based on the background color. There should be no shadows behind the face, and no visible objects in the background, such as people, furniture, patterned wallpaper, or plants.
The lighting must be adequate and uniform, evenly distributed across the face to avoid differences between the left and right sides. The photo should have brightness and good contrast between hair, face, and background. Poorly lit photos occur when lighting is only on the side, above, or below.
Images should be in JPEG, PNG, or JWT formats.
Captured images must be in color.

Sizes/Proportions

Selfies:

Recommended size: Aspect ratio 1920x1080 or 1080x1920;
Orientation: Portrait;
Size: Maximum 800kb, if necessary you can compress it to Jpeg92.

Documents:

Recommended size: HD aspect ratio - 1280x720 or 720x1280;
Minimum size: VGA aspect ratio - 640x480 or 480x640;
Orientation: There is no restriction regarding portrait or landscape orientation;
Size: Maximum 800kb, if necessary you can compress it to Jpeg92.

Examples of Standard and Non-Standard Photos:

The photo must include:

Color
Proper framing
Sharp and clear focus, free of ink marks or creases.

Look directly at the camera.
Show the natural skin tone.
Have appropriate brightness and contrast.

Neutral expression and eyes clearly visible.
No hair covering the eyes.
Facing the camera directly, without looking over the shoulder or tilted, and showing both edges of the face clearly.
With a simple light-colored background, preferably white.
With even lighting, no shadows or flash reflections on the face, and without red-eye.
No colored contact lenses.
No makeup.

The use of glasses is not recommended; however, if necessary:

The eyes must be clear, without reflections from flash or ambient light on the glasses, and without colored lenses.
The frame must not cover any part of the eyes.

Note: Images taken from the guide "ICAO Guide for MRTD Photo Guidelines. ICAO. Icao guide for mrtd photo guidelines. http://www.icao.int/Security/mrtd/Downloads/TechnicalReports/Annex_A-Photograph_Guidelines.pdf

Tips

Add instructions before capturing for the user:

Use capture "frames" to guide the client's positioning in front of the camera:

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.

APIs

In this section, you will find all the available REST APIs for using the by Client integration method

CreateProcess

In this section, you will find how to create a process in by Client through the REST API

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.

The parameters above represent the most common usage of the API but may change depending on the capabilities you are using. Check the subsections of this section for the possibilities of capabilities and their differences.

To implement your business rules, always validate the final statuses of the processes (3, 4, 5). To validate the response from IDCloud capabilities, only consider status = 3 for your decision-making. For more information on the possible statuses, see the Parameters Specification section.

The Client API does not reject photos (meaning there is no drop). The existing returns are from the Identity Verification capability and will always be: yes, no, or inconclusive. Thus, cases of poor quality in image capture, proof of life, or non-ownership will result in an inconclusive return. The return is "yes" when it is possible to identify a live person who is the actual holder of the CPF.

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.

Liveness

In this section, you will find the specifics of creating a process that only has the Liveness capability

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.

When creating the process, only the subject.code and imageBase64 parameters are mandatory;
In the process response, only the id, status, and liveness (result of Liveness) parameters are returned.

For this use case, there is no need to perform the GetProcess call, as the response is synchronous.

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.

Identity Verification

In this section, you will find the specifics of creating a process that has Identity Verification as a capability, along with its complements

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.

During the process creation, the required fields are subject.code, subject.name, and imageBase64.
In the process response, the responses from the capabilities may arrive at different times, since IDCloud has both synchronous and asynchronous capabilities. Therefore, you should implement the GetProcess method depending on the combination of these capabilities.

The Identity Verification capability can be combined with other capabilities, such as Risk Score or Fraud Profile Detection. For more information on the possible responses, refer to the sections on Response Scenarios and Parameter Specifications.

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.

Validation (1:1)

In this section, you will find the specifics of creating a process that includes the 1:1 Validation capability

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.

In the process creation, the following are mandatory: subject.code, referenteProcessId, and imageBase64;
In the process response, we return the id, authenticated (result of the 1:1 Validation), and liveness (result of the Liveness).

For this use case, there is no need to perform the GetProcess, as the response is synchronous.

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.

Document Capture

In this section, you will find the specific details on creating a process that includes Document Capture as a capability

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: ;
Production: .

In creating the process, the following fields are required: subject.code, subject.name, document.Purpose, document.files.id or document.files.data, and imageBase64;
In the process response, we return the id, status, and document.id. The capability's response is always asynchronous; therefore, the GetProcess method must be implemented.

GetProcess

In this section, you will find instructions on how to retrieve the result of a process in by Client using the REST API

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: ;
Production: .

The parameters above represent the most common usage of the API but may change depending on the capabilities you are using.

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

GetReusableDocuments

In this section, you will find how to retrieve a document for reuse in by Client via the REST API

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/documents/v1;
Production: https://api.id.unico.app/documents/v1.

The documentId obtained in the API response should be used in the payload when creating the document capture process. Learn more in the Document Capture 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.

Response Scenarios

In this section, you will find the possible responses for the combinations of capabilities separated by their methods to facilitate your understanding of the by Client integration

Understanding how the return of each parameter works is essential for implementing the best decision-making. To see in detail the meaning of each parameter, see the section Parameter Specification

In all the combinations described below, if an error occurs during processing, the process will return a status = 5. For this reason, the scenarios below do not display responses related to this condition. Example:

Liveness

Response CreateProcess

Response GetProcess

Liveness

Response CreateProcess

Response GetProcess

For the scenarios where the response in CreateProcess is the same as the response from GetProcess, optimize your application and make your decision synchronously.

Liveness + Identity Verification

For the scenarios where the response in CreateProcess is the same as the response from GetProcess, optimize your application and make your decision synchronously.

Liveness + Identity Verification + Risk scoring

For the scenarios where the response in CreateProcess is the same as the response from GetProcess, optimize your application and make your decision synchronously.

Parameter Specification

In this section, you will find the specification of all the parameters for the by Client integration REST API

CreateProcess - Request Payload

Name

Type

Mandatory / Optional

Description

GetProcess (Liveness + Identity verification and more) - Request response

Nome

Tipo

Descrição

GetProcess (Document capture) - Request response

GetReusableDocuments - Request response

Additional Resources

In this section, you will find additional resources related to the by Client integration method

Postman Collection

In this section, you will find the Postman collection for the by Client REST APIs

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 .

Capture standard (without SDK)

In this section, you will find how the capture standard for the user's selfie should be if you do not use our SDKs

Common issues in captured images include:

Lighting behind the client: Frontal lighting must be strong enough for a clear capture of the face.
Overexposed lighting: Frontal lighting needs to be adequate for a sharp capture.
Face too close to the camera: The face should be centered in the camera frame with proper lighting.
Blurry images: The person’s face needs to be well-focused at the moment of capture.
Shaky images: Stabilize the camera during capture.
Client wearing glasses: The client should not wear glasses or objects that obstruct full visibility of the face.

How to Obtain a Good Image Capture

Face Positioning and Additional Information:

The photo must be taken from the front—looking directly at the camera with the head upright. The face should be centered, and the shoulders must be aligned parallel to the camera's image plane.
The eyes should be naturally open—pupils and irises visible.
Glasses: The photo should be captured without glasses.
No hats, caps, or masks: The facial area must be clearly visible.
Neutral Expression: The face should maintain a neutral expression; the person should not smile, raise eyebrows, squint, or frown.
Hairstyle: Hair should not cover the eye visibility zone.

Lighting and Background:

The background should be light, smooth, and free of texture. It must not have stains, lines, or curves that are visible in the captured image. Light colors like light blue or white can be used, provided there is sufficient contrast between the face/hair area and the background.
The camera's color settings should not change based on the background color. There should be no shadows behind the face, and no visible objects in the background, such as people, furniture, patterned wallpaper, or plants.
The lighting must be adequate and uniform, evenly distributed across the face to avoid differences between the left and right sides. The photo should have brightness and good contrast between hair, face, and background. Poorly lit photos occur when lighting is only on the side, above, or below.
Images should be in JPEG, PNG, or JWT formats.
Captured images must be in color.

Sizes/Proportions

Selfies:

Recommended size: Aspect ratio 1920x1080 or 1080x1920;
Orientation: Portrait;
Size: Maximum 800kb, if necessary you can compress it to Jpeg92.

Documents:

Recommended size: HD aspect ratio - 1280x720 or 720x1280;
Minimum size: VGA aspect ratio - 640x480 or 480x640;
Orientation: There is no restriction regarding portrait or landscape orientation;
Size: Maximum 800kb, if necessary you can compress it to Jpeg92.

Examples of Standard and Non-Standard Photos:

The photo must include:

Color
Proper framing
Sharp and clear focus, free of ink marks or creases.

Look directly at the camera.
Show the natural skin tone.
Have appropriate brightness and contrast.

Neutral expression and eyes clearly visible.
No hair covering the eyes.
Facing the camera directly, without looking over the shoulder or tilted, and showing both edges of the face clearly.
With a simple light-colored background, preferably white.
With even lighting, no shadows or flash reflections on the face, and without red-eye.
No colored contact lenses.
No makeup.

The use of glasses is not recommended; however, if necessary:

The eyes must be clear, without reflections from flash or ambient light on the glasses, and without colored lenses.
The frame must not cover any part of the eyes.

Tips

Add instructions before capturing for the user:

Use capture "frames" to guide the client's positioning in front of the camera:

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.

Overview

In this section, you will find all the technical specifications for By Client REST APIs

Introduction

Available Flows

You can combine capabilities as desired and use them in various cases; however, API Keys configured with the desired capabilities are required.

o request specific capabilities for an API Key, please contact your integration project manager or Unico’s support team for assistance with the configuration.

See below for all possible capability combinations in By Client:

You can also use the above capabilities without the Liveness Detection if you already have a Liveness provider in your operation. I
f you use the Identity Verification capability, regardless of any other combinations, it’s also possible to retrieve the Serpro similarity result (click here to learn more).

Synchronous and Asynchronous Capabilities

In your operation, you can combine capabilities as you see fit, but each capability has its own communication method. For example:

You might operate with both Identity Verification and Fraud Profile Detection capabilities.
When creating the process, the response for Identity Verification will be synchronous and included in the API response.
Fraud Profile Detection, however, will operate asynchronously, requiring a wait for processing and then a separate GET request to obtain the final result.

Below are the synchronous and asynchronous capabilities:

Synchronous Capabilities

Liveness:

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

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

Identity verification:

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

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

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

Validation (1:1)

{
    "authenticated": "true"
}

{
    "authenticated": "false"
}

Asynchronous Capabilities

Identity verification:

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

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

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

Just like the Identity Verification capability is a "synchronous" capability, it can also be configured for "asynchronous" use.

Risk scoring:

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

Fraud Profile Detection:

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

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

Document capture and reuse:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": 3,
  },
  "document": {
    "id": "b97c3fd9-d95d-413f-bc0a-75eb87304421",
    "type": "CNH",
    "cpfMatch": false,
    "content": {
      "numero": "044589731564",
      "rgNumero": "123456789 SESP PR",
      "nomeCivil": "Homer Simpson",
      "filiacao": [
        "Monasimpson",
        "Monasimpson"
      ],
      "dataNascimento": "1990-05-12T00:00:00Z",
      "dataHabilitacao": "1997-11-18T00:00:00Z",
      "dataExpiracao": "2017-12-07T00:00:00Z",
      "dataEmissao": "2012-12-07T00:00:00Z",
      "localEmissao": "Curitiba PR",
      "categoria": "B",
      "renachNumero": "PR904987581"
    },
    "fileUrls": [
            "https://url-signer-1",
            "https://url-signer-2"
        ]
  }
}

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.

Response Scenarios

In this section, you will find the possible responses for the combinations of capabilities separated by their methods to facilitate your understanding of the by Client integration

Understanding how the return of each parameter works is essential for implementing the best decision-making. To see in detail the meaning of each parameter, see the section Parameter Specification

Liveness

Response CreateProcess

Response GetProcess

Liveness

Response CreateProcess

Response GetProcess

For the scenarios where the response in CreateProcess is the same as the response from GetProcess, optimize your application and make your decision synchronously.

Liveness + Identity Verification

Liveness + Identity Verification

Response CreateProcess

Response GetProcess

Notes:

The "yes" response from unicoId.result (identity verification) already includes the validation of the Liveness capability. That is, if the response is "yes," it is understood that the user's face matches that of the CPF holder AND that the user was live at the time the selfie was taken.

Liveness + Identity Verification ❔

Response CreateProcess

Response GetProcess

Liveness + Identity Verification ❔

Response CreateProcess

Response GetProcess

Liveness + Identity Verification

Response CreateProcess

Response GetProcess

Liveness + Identity Verification

Response CreateProcess

Response GetProcess

For the scenarios where the response in CreateProcess is the same as the response from GetProcess, optimize your application and make your decision synchronously.

When the status = 3 and the unicoId.result is "no," there will be no orchestration with the Risk Score capability.

Liveness + Identity Verification + Risk scoring

Response CreateProcess

Response GetProcess

For the scenarios where the response in CreateProcess is the same as the response from GetProcess, optimize your application and make your decision synchronously.

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 .