Onboarding

URL Base:

• UAT: https://api.id.uat.unico.app.

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

Below you'll find the endpoint for Onboarding by Cilent with all capabilities enabled, but you can also use the capabilities individually (except for Serpro's similarity score and risk score, which depend on the use of Identity Verification). Discuss with your project manager which capabilities to enable for your operation.

Create Onboarding Process

post

Endpoint to create a new Onboarding process in by Client

Header parameters

AuthorizationstringRequired

Valid access-token.

APIKEYstringRequired

Valid APIKEY with the capabilities for Onboarding use.

Body

application/json

useCasestringOptional

Operation's use case.

Example: Onboarding

subsidiaryIdstringOptional

The ID of the branch where the process will be created. If there is only one branch associated with the service account, there is no need to pass this parameter. If there is a separation of processes by branch, you will receive the branch IDs from the Unico team.

Example: 35d734c4-7fbb-4b2f-a1dc-7e1575514819

imageBase64stringRequired

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

Example: /9j/4AAQSkZJR...

Responses

200

Process created successfully.

application/json

idstringOptional

Process ID.

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

statusinteger · enumOptional

Process status. Possible values: '1' - Processing (occurs only when the Identity Verification response is inconclusive and there is orchestration with the Risk Score); '3' - Completed (occurs when the Identity Verification response is conclusive - 'yes' or 'no'); - '5' - Error (occurs when there is an error in processing).

Example: 1Possible values:

livenessinteger · enumOptional

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

Example: 1Possible values:

400

Bad Request.

application/json

403

Forbidden.

application/json

500

Internal Server Error.

application/json

post

/processes/v1

HTTPcURLJavaScriptPython

POST /processes/v1 HTTP/1.1
Host: api.id.uat.unico.app
Authorization: text
APIKEY: text
Content-Type: application/json
Accept: */*
Content-Length: 253

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker",
    "gender": "M",
    "birthDate": "2000-05-20",
    "email": "[email protected]",
    "phone": "551972557070"
  },
  "useCase": "Onboarding",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR..."
}

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

Important:

• If the response from the Identity Verification capability is unicoId = yes/no, this response already includes the Liveness (meaning you will not receive the liveness parameter in the response).

• If the response from the Identity Verification capability is unicoId = inconclusive, there will be orchestration with the Risk Score capability.

• 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 life proof, not even passive validation.

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

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

Tips:

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

Errors

400 Bad Request

Code	Message	Description
20900	O base64 informado não é válido.	The base64 parameter is invalid. Possible causes: It's not an image or it's an injection attempt.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	The resolution of the uploaded image is too low.
20507	O parâmetro subject.code é inválido.	Non-standard or non-existent CPF.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	When the e-mail address provided is not vThe image is too large. The image can be compressed to JPEG92 without loss of quality.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	When the phone number entered is not validBase64 invalid. Possible causes: not a valid image or invalid prefix.
20009	O parâmetro imagebase64 não foi informado.	The imagebase64 parameter, which contains the person's selfie, is missing.
20006	O parâmetro subject.name não foi informado.	The subject.name parameter, which contains the person's name, is missing.
20005	O parâmetro subject.code não foi informado.	The subject.code parameter, which contains the person's cpf, is missing.
20004	O parâmetro subject não foi informado.	The subject parameter, which contains the person's data (cpf, name), is missing.
20003	The request body is missing or invalid.	Null or invalid payload.
20002	O parâmetro APIKey não foi informado.	The APIKEY parameter is missing from the request header.
20001	O parâmetro authtoken não foi informado	The integration token parameter is missing from the request header.
10508	The JWT with the captured face has already been used.	The jwt can only be used once.
10507	The JWT with the captured face is expired.	JWT expired. The .jwt must be sent within 10 minutes.
10506	The bundle is invalid.	Invalid bundle. APIKEY uses a security method and this request does not meet the security requirements (SDK).

403 Forbidden

500 Internal Server Error

Check Process Result

get

Endpoint to fetch the result of an Onboarding process in by Client (specific for when there is orchestration with the Risk Score)

Path parameters

processIdstringRequired

Process ID.

Header parameters

AuthorizationstringRequired

Valid access-token.

APIKEYstringRequired

Valid APIKEY with the capabilities for Onboarding use.

Responses

200

Process information obtained successfully.

application/json

idstringOptional

Process ID.

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

statusinteger · enumOptional

Process status. Possible values: '1' - Processing; '2' - Divergence (occurs when the Risk Score found a divergence for this face and will still complete the verification) '3' - Completed; '4' - Canceled (e.g.: timeout); - '5' - Error.

Example: 3Possible values:

scoreintegerOptional

Result of the risk score.

Example: 90

livenessinteger · enumOptional

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

Example: 1Possible values:

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

410

Gone.

application/json

500

Internal Server Error.

application/json

get

/processes/v1/{processId}

HTTPcURLJavaScriptPython

GET /processes/v1/{processId} HTTP/1.1
Host: api.id.uat.unico.app
Authorization: text
APIKEY: text
Accept: */*

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

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, identityFraudsters = inconclusive/yes 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.

Errors

400 Bad Request

Code	Message	Description
20023	O parâmetro processId não foi informado.	The process id parameter is missing.
20002	O parâmetro APIKey não foi informado.	The APIKEY parameter is missing from the request header.
20001	O parâmetro authtoken não foi informado.	The integration token parameter is missing from the request header.

404 Not Found

403 Forbidden

410 Gone

500 Internal Server Error