1 de 8

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

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.

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

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.

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

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.

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

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"
  }
}

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.

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.

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

GetProcess

Endpoint to retrieve the result of a verification identity process by Client.

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

Path parameters

processId*string

Process ID.

Header parameters

Authorization*string

Valid access-token.

APIKEY*string

Valid APIKEY.

Response

Process information retrieved successfully.

Body

idstring

Process ID.

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

statusinteger

Process status.

Example: 3

unicoIdobject

Identity verification result.

resultstring

Identity verification result.

Example: "inconclusive"

livenessinteger

Liveness test result, where: '1' is LIVE and '2' is NOT LIVE.

Example: 1

scoreinteger

Risk score result.

Example: 50

Request

Response

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:

"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"
  }
}

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.

CreateProcess

Endpoint to create a new document process by Client.

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

Header parameters

Authorization*string

Valid access-token.

APIKEY*string

Valid APIKEY with document capture and reuse capability.

Body

subject*object

code*string

User's CPF.

Example: "12345678909"

name*string

User's name.

Example: "Luke Skywalker"

emailstring

User's email.

Example: "luke@unico.io"

phonestring

User's phone.

Example: "551972557070"

document*object

Information about the document to be captured.

purpose*string

Indicates the purpose of sharing the document. Can receive values: creditprocess, carpurchase, paybypaycheck, onboarding, or fgts.

Example: "creditprocess"

authProcessId*string

ID of the biometrics process that must have been carried out previously. The ID must be from a completed process with valid biometrics.

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

documentId*string

Identifier of the document to be reused. You will find it when using the GetReusableDocuments API. If you do not find a document to be reused, you must capture the document and send the base64 in the data.files parameter.

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

files*array of object

Base64 of the user's document if no reusable document is found in the GetReusableDocuments API. The array can contain 1 file (e.g., full CNH) or 2 files (e.g., CNH front and CNH back).

datastring

Image of the document encoded in base64.

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

imageBase64*string

Base64 of the user's selfie.

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

Response

Document process created successfully.

Body

idstring

Process ID.

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

statusinteger

Process status.

Example: 3

documentobject

idstring

ID of the document that was created.

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

Request

Response

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.

GetReusableDocuments

Endpoint to retrieve a user's documents for reuse in by Client.

GEThttps://api.id.uat.unico.app/documents/v1/client/v1/process

Query parameters

code*string

User identifier value (e.g., CPF value).

Example: 12345678909

type*string

Document type (e.g., BR_CPF).

Example: "BR_CPF"

Header parameters

Authorization*string

Valid access-token.

APIKEY*string

Valid APIKEY.

Response

Process information retrieved successfully.

Body

itemsarray of object

List of documents associated with the process.

documentTypestring

Document type.

Example: "unico.moja.dictionary.br.rg.v2.Rg"

documentIdstring

Document ID.

Example: "2aaf6037-0153-415d-b9fe-cf7e8198408f"

Request

Response

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.

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.

CreateProcess

Endpoint to create a new identity verification process by Client.

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

Header parameters

Authorization*string

Valid access-token.

APIKEY*string

Valid APIKEY with the capabilities you will use.

Body

subject*object

code*string

User's CPF.

Example: "12345678909"

name*string

User's name.

Example: "Luke Skywalker"

emailstring

User's email.

Example: "luke@unico.io"

phonestring

User's phone.

Example: "551972557070"

useCase*string

Use case of the operation.

Example: "Onboarding"

imageBase64*string

Encrypted generated by the SDK or base64.

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

Response

Process created successfully (YES from Identity Verification).

Body

idstring

Process ID.

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

statusinteger

Process status.

Example: 3

unicoIdobject

resultstring

Result of the identity verification.

Example: "yes"

Request

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

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

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.

CreateProcess

Endpoint to create a new document process by Client.

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

Header parameters

Authorization*string

Valid access-token.

APIKEY*string

Valid APIKEY with document capture and reuse capability.

Body

subject*object

code*string

User's CPF.

Example: "12345678909"

name*string

User's name.

Example: "Luke Skywalker"

emailstring

User's email.

Example: "luke@unico.io"

phonestring

User's phone.

Example: "551972557070"

document*object

Information about the document to be captured.

purpose*string

Indicates the purpose of sharing the document. Can receive values: creditprocess, carpurchase, paybypaycheck, onboarding, or fgts.

Example: "creditprocess"

authProcessId*string

ID of the biometrics process that must have been carried out previously. The ID must be from a completed process with valid biometrics.

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

documentId*string

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

files*array of object

Base64 of the user's document if no reusable document is found in the GetReusableDocuments API. The array can contain 1 file (e.g., full CNH) or 2 files (e.g., CNH front and CNH back).

datastring

Image of the document encoded in base64.

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

imageBase64*string

Base64 of the user's selfie.

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

Response

Document process created successfully.

Body

idstring

Process ID.

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

statusinteger

Process status.

Example: 3

documentobject

idstring

ID of the document that was created.

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

Request

Response

CreateProcess

Endpoint to create a new identity verification process by Client.

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

Header parameters

Authorization*string

Valid access-token.

APIKEY*string

Valid APIKEY with the capabilities you will use.

Body

subject*object

code*string

User's CPF.

Example: "12345678909"

name*string

User's name.

Example: "Luke Skywalker"

emailstring

User's email.

Example: "luke@unico.io"

phonestring

User's phone.

Example: "551972557070"

useCase*string

Use case of the operation.

Example: "Onboarding"

imageBase64*string

Encrypted generated by the SDK or base64.

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

Response

Process created successfully (YES from Identity Verification).

Body

idstring

Process ID.

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

statusinteger

Process status.

Example: 3

unicoIdobject

resultstring

Result of the identity verification.

Example: "yes"

Request

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

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