# Onboarding

{% hint style="info" %}
**URL Base**:

* UAT: <mark style="color:blue;">`https://api.id.uat.unico.app`</mark>.
* Production: <mark style="color:blue;">`https://api.id.unico.app`</mark>.
  {% endhint %}

{% hint style="success" %}
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.
{% endhint %}

## Create Onboarding Process

> Endpoint to create a new Onboarding process in by Client

```json
{"openapi":"3.0.0","info":{"title":"CreateProcess by Client","version":"1.0.0"},"servers":[{"url":"https://api.id.uat.unico.app"}],"paths":{"/processes/v1":{"post":{"summary":"Create Onboarding Process","description":"Endpoint to create a new Onboarding process in by Client","parameters":[{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Valid access-token."},{"in":"header","name":"APIKEY","required":true,"schema":{"type":"string"},"description":"Valid APIKEY with the capabilities for Onboarding use."}],"requestBody":{"description":null,"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","imageBase64"],"properties":{"subject":{"type":"object","description":"User information.","required":["code"],"properties":{"code":{"type":"string","description":"User identifier. Can be the Brazilian CPF or the Mexican CURP. Must be sent without dots or dashes."},"name":{"type":"string","description":"User's name."},"gender":{"type":"string","description":"User's gender. Possible values: 'M' for male or 'F' for female."},"birthDate":{"type":"string","description":"User's birth date. Must be in ISO 8601 format (yyyy-MM-dd)."},"email":{"type":"string","description":"User's e-mail."},"phone":{"type":"string","description":"User's phone. Must contain 13 characters and be sent without dots or dashes, in the format IDD + Area Code + Phone Number."}}},"useCase":{"type":"string","description":"Operation's use case."},"subsidiaryId":{"type":"string","description":"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."},"imageBase64":{"type":"string","description":"Encrypted file generated by the SDK or base64 (if not using Liveness Detection)."}}}}}},"responses":{"200":{"description":"Process created successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Process ID."},"status":{"type":"integer","enum":[1,3,5],"description":"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)."},"unicoId":{"type":"object","description":"Information about the identity verification.","properties":{"result":{"type":"string","enum":["yes","no","inconclusive"],"description":"Result of the identity verification. Possible values: 'yes' - It is the face of the CPF holder; 'no' - It is not the face of the CPF holder; 'inconclusive' - We cannot guarantee with precision if this is the face of the CPF holder."}}},"identityFraudsters":{"type":"object","description":"Information about the behavioral alert.","properties":{"result":{"type":"enjum","enum":["yes","inconclusive"],"description":"Result of the behavioral alert. Possible values: 'yes' - The face has already been involved in a fraudulent identity transaction; 'inconclusive' - We have no indication that the face has been involved in a fraudulent identity transaction."}}},"government":{"type":"object","description":"Information about the Serpro similarity score.","properties":{"serpro":{"type":"string","description":"Result of the Serpro similarity score. When Serpro finds the face, a score of 0-100 is returned. When Serpro does not find the face, a score of -1 is returned. When there is an error in the integration with Serpro, a score of -2 is returned."}}},"liveness":{"type":"integer","enum":[1,2],"description":"Liveness detection result. Possible values: '1' - Liveness detection approved; '2' - Liveness detection rejected."}}}}}},"400":{"description":"Bad Request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"403":{"description":"Forbidden.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}}}}}}}
```

{% hint style="warning" %}
**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:
* ```json
    {
    "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "status": 5
    }
  ```

{% endhint %}

{% hint style="success" %}
**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.
  {% endhint %}

### Errors

{% tabs %}
{% tab title="400 Bad Request" %}

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

{% tab title="403 Forbidden" %}

<table><thead><tr><th width="183" align="center">Code</th><th>Message</th><th>Description</th></tr></thead><tbody><tr><td align="center"><code>30017</code></td><td><code>Jwt header is an invalid JSON.</code></td><td>When the access-token used contains wrong characters.</td></tr><tr><td align="center"><code>10502</code></td><td><code>O token informado está expirado.</code></td><td>When the access-token used has expired</td></tr><tr><td align="center"><code>10501</code></td><td><code>O token informado é inválido.</code></td><td>The authentication token is invalid.</td></tr><tr><td align="center"><code>10201</code></td><td><code>O AppKey informado é inválido.</code></td><td>The APIKEY parameter has not been entered or does not exist.</td></tr></tbody></table>
{% endtab %}

{% tab title="500 Internal Server Error" %}

<table><thead><tr><th width="99" align="center">Code</th><th width="299">Message</th><th>Description</th></tr></thead><tbody><tr><td align="center"><code>99999</code></td><td><code>Internal failure! Try again later</code></td><td>When there is an internal error.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Check Process Result

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

```json
{"openapi":"3.0.0","info":{"title":"Get Process Info","version":"1.0.0"},"servers":[{"url":"https://api.id.uat.unico.app"}],"paths":{"/processes/v1/{processId}":{"get":{"summary":"Check Process Result","description":"Endpoint to fetch the result of an Onboarding process in by Client (specific for when there is orchestration with the Risk Score)","parameters":[{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Valid access-token."},{"in":"header","name":"APIKEY","required":true,"schema":{"type":"string"},"description":"Valid APIKEY with the capabilities for Onboarding use."},{"name":"processId","in":"path","required":true,"description":"Process ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Process information obtained successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Process ID."},"status":{"type":"integer","enum":[1,2,3,4],"description":"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."},"unicoId":{"type":"object","description":"Information about the identity verification.","properties":{"result":{"type":"string","enum":["yes","no","inconclusive"],"description":"Result of the identity verification. Possible values: 'yes' - It is the face of the CPF holder; 'no' - It is not the face of the CPF holder; 'inconclusive' - We cannot guarantee with precision if this is the face of the CPF holder."}}},"identityFraudsters":{"type":"object","description":"Information about the behavioral alert.","properties":{"result":{"type":"string","enum":["yes","inconclusive"],"description":"Result of the behavioral alert. Possible values: 'yes' - The face has already been involved in a fraudulent identity transaction; 'inconclusive' - We have no indication that the face has been involved in a fraudulent identity transaction."}}},"score":{"type":"integer","description":"Result of the risk score."},"government":{"type":"object","description":"Information about the Serpro similarity score.","properties":{"serpro":{"type":"string","description":"Result of the Serpro similarity score. When Serpro finds the face, a score of 0-100 is returned. When Serpro does not find the face, a score of -1 is returned. When there is an error in the integration with Serpro, a score of -2 is returned."}}},"liveness":{"type":"integer","enum":[1,2],"description":"Liveness detection result. Possible values: '1' - Liveness detection approved; '2' - Liveness detection rejected."}}}}}},"400":{"description":"Bad Request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"403":{"description":"Forbidden.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"404":{"description":"Not Found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"410":{"description":"Gone.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Process ID."},"status":{"type":"integer","description":"Process status."}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}}}}}}}
```

{% hint style="danger" %}
**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.
  {% endhint %}

{% hint style="success" %}
**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.
  {% endhint %}

### Errors

{% tabs %}
{% tab title="400 Bad Request" %}

<table><thead><tr><th width="108" align="center">Code</th><th width="310">Message</th><th>Description</th></tr></thead><tbody><tr><td align="center"><code>20023</code></td><td><code>O parâmetro processId não foi informado.</code></td><td>The process id parameter is missing.</td></tr><tr><td align="center"><code>20002</code></td><td><code>O parâmetro APIKey não foi informado.</code></td><td>The APIKEY parameter is missing from the request header.</td></tr><tr><td align="center"><code>20001</code></td><td><code>O parâmetro authtoken não foi informado.</code></td><td>The integration token parameter is missing from the request header.</td></tr></tbody></table>
{% endtab %}

{% tab title="404 Not Found" %}

<table><thead><tr><th width="100" align="center">Code</th><th width="252">Message</th><th>Description</th></tr></thead><tbody><tr><td align="center"><code>50001</code></td><td><code>O processo informado não foi encontrado.</code></td><td>The process does not exist in the database.</td></tr></tbody></table>
{% endtab %}

{% tab title="403 Forbidden" %}

<table><thead><tr><th width="182" align="center">Code</th><th>Message</th><th>Description</th></tr></thead><tbody><tr><td align="center"><code>30017</code></td><td><code>O usuário não tem permissão para executar está ação.</code></td><td>When the access-token used contains wrong characters.</td></tr><tr><td align="center"><code>10502</code></td><td><code>O token informado está expirado.</code></td><td>When the access-token used has expired.</td></tr><tr><td align="center"><code>10501</code></td><td><code>O token informado é inválido.</code></td><td>The authentication token is invalid.</td></tr><tr><td align="center"><code>10201</code></td><td><code>O AppKey informado é inválido.</code></td><td>The APIKEY parameter has not been entered or does not exist.</td></tr></tbody></table>
{% endtab %}

{% tab title="410 Gone" %}

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

{% endtab %}

{% tab title="500 Internal Server Error" %}

<table><thead><tr><th width="99" align="center">Code</th><th width="299">Message</th><th>Description</th></tr></thead><tbody><tr><td align="center"><code>99999</code></td><td><code>Internal failure! Try again later</code></td><td>When there is an internal error.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devcenter.unico.io/unico-idcloud/by-client-integration/by-client-api/api-reference/onboarding.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.