# Onboarding

### 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 [<mark style="color:blue;">**here**</mark>](/trust-en/integrations/integration-by-client/authentication.md).

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

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

## Create Process

> Endpoint to create a new Onboarding process in by Client integration.

```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 Process","description":"Endpoint to create a new Onboarding process in by Client integration.","parameters":[{"in":"header","name":"APIKEY","required":true,"schema":{"type":"string"},"description":"A valid APIKEY."},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"A valid access-token."}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","imageBase64"],"properties":{"subject":{"type":"object","description":"User information.","required":["code"],"properties":{"duiType":{"type":"integer","description":"This is the user ID that will be used to validate the process. See the possible uses at the end of this section."},"code":{"type":"string","description":"User's identifier. Must be sent without dots or dashes."},"name":{"type":"string","description":"User's name."},"email":{"type":"string","description":"User's email."},"phone":{"type":"string","description":"User's phone number. Must contain 12 characters and be sent without dots or dashes, in the format DDI + DDD + phone number."},"birthDate":{"type":"string","description":"User's birth date. Must be in ISO 8601 format (yyyy-MM-dd)."},"gender":{"type":"string","description":"User's gender. Possible values: 'M' for male or 'F' for female."}}},"useCase":{"type":"string","description":"Use case of the operation."},"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, this parameter is not required. If there is a separation of processes by branch, you will receive the branch IDs from the Unico team."},"imageBase64":{"type":"string","description":"User's selfie in base64."},"document":{"type":"object","properties":{"purpose":{"type":"string","description":"The intended purpose of the document upload."},"files":{"type":"array","description":"List of files associated with the document.","items":{"type":"object","properties":{"data":{"type":"string","description":"Base64 encoded string of the file content."}}}}}}}}}}},"responses":{"200":{"description":"Process successfully created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Process ID."},"status":{"type":"integer","enum":[3,5],"description":"Process status. Possible values:<br><br> **'3'** - Completed;<br> **'5'** - Error."},"idCloud":{"type":"object","description":"Information about Identity Verification.","properties":{"result":{"type":"string","enum":["approved","reproved","risk-critical","risk-high","inconclusive"],"description":"The final result. Possible values: <br> <br>**'approved'** - it is the face of the ID holder, and no evidence related to fraud was found; <br>**'reproved'** - rejection is recommended, as multiple fraud indicators were detected; <br>**'risk-critical'** - rejection is recommended, but the final decision is up to your discretion. Critical risk indicates that we found at least 2 strong evidences of fraud; <br>**'risk-high'** - rejection is also recommended, but the decision remains yours. High risk indicates that we found at least one strong evidence of fraud; <br>**'inconclusive'** - no strong evidence of fraud was found. Therefore, it’s not possible to conclude whether there is relevant risk or not."}}}}}}}},"400":{"description":"Invalid payload.","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":"Unexpected error (Internal error or parameter issue).","content":{"application/json":{"schema":{"type":"object","properties":{"Error":{"type":"object","properties":{"Code":{"type":"integer","description":"Error code."},"Description":{"type":"string","description":"Error description."}}}}}}}}}}}}}
```

<details>

<summary>DuiType enum</summary>

<table><thead><tr><th width="132.5" align="center">Country</th><th width="90" align="center">Code</th><th>Description</th></tr></thead><tbody><tr><td align="center">BR</td><td align="center">1</td><td>Brazilian CPF</td></tr><tr><td align="center">BR</td><td align="center">5</td><td>Brazilian Passport</td></tr><tr><td align="center">MX</td><td align="center">2</td><td>Mexican CURP</td></tr><tr><td align="center">AR</td><td align="center">7</td><td>Argentine DNI</td></tr><tr><td align="center">US</td><td align="center">4</td><td>United States SSN</td></tr><tr><td align="center">US</td><td align="center">11</td><td>United States Passport</td></tr><tr><td align="center">US</td><td align="center">18</td><td>United Status Driver's License</td></tr><tr><td align="center">ID</td><td align="center">16</td><td>Indonesian NIK</td></tr><tr><td align="center">NG</td><td align="center">8</td><td>Nigerian NIN</td></tr><tr><td align="center">ZZ</td><td align="center">17</td><td>Phone number</td></tr><tr><td align="center">ZZ</td><td align="center">15</td><td>Email address</td></tr></tbody></table>

</details>

{% hint style="info" %}
The answer `approved` is not activate by default. If you wan't implement this rule, align with the responsible for your project in Unico.
{% endhint %}

{% hint style="warning" %}
**Important**:

* If status = 3, consider the response from the idCloud.result parameter;
* If an error occurs in the biometrics process, the request will return a status `code = 200` and the process will have a `status = 5`, as in the following example:

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

{% endhint %}

#### Error Responses

{% tabs %}
{% tab title="Click on the side to see more" %}

{% endtab %}

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

<table><thead><tr><th>Code</th><th width="278.6666259765625">Message</th><th>Description</th></tr></thead><tbody><tr><td><code>20807</code></td><td><code>The image must be in HD standard or have a resolution greater than 640 x 480.</code></td><td>The resolution of the uploaded image is too small.</td></tr><tr><td><code>20507</code></td><td><code>The subject.code field is invalid.</code></td><td>Non-standard or non-existent identifier.</td></tr><tr><td><code>20506</code></td><td><code>The base64 file you provided is too large. The maximum supported size is up to 800kb.</code></td><td>The image is too large. The image can be compressed to JPEG92 without loss of quality.</td></tr><tr><td><code>20505</code></td><td><code>The specified base64 is not supported. Accepted formats are png, jpeg, and webp.</code></td><td>Invalid base64. Possible causes: not a valid image or invalid prefix.</td></tr><tr><td><code>20009</code></td><td><p><code>The imagebase64 field</code> </p><p><code>is missing.</code></p></td><td>The imagebase64 parameter, which contains the person's selfie, is missing.</td></tr><tr><td><code>20005</code></td><td><p><code>The subject.code field</code> </p><p><code>is missing.</code></p></td><td>The subject.code parameter, which contains the person's identifier, is missing.</td></tr><tr><td><code>20003</code></td><td><code>The request body is missing or invalid.</code></td><td>Null or invalid payload.</td></tr><tr><td><code>20002</code></td><td><code>The APIKEY header is missing.</code></td><td>The APIKEY parameter is missing from the request header.</td></tr><tr><td><code>20001</code></td><td><code>The authorization token is missing.</code></td><td>The integration token parameter is missing from the request header.</td></tr><tr><td><code>10201</code></td><td><code>The APIKEY header is invalid.</code></td><td>The APIKEY parameter has not been entered or does not exist.</td></tr></tbody></table>
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Jwt is expired
```

{% endtab %}

{% tab title="403 Forbidden" %}

| Code         | Message                               | Description                                           |
| ------------ | ------------------------------------- | ----------------------------------------------------- |
| `30017`      | `Jwt header is an invalid JSON.`      | When the access-token used contains wrong characters. |
| `10502`      | `The token informado está expirado.`  | When the access-token used has expired.               |
| `10501`      | `The authorization token is invalid.` | The authentication token is invalid.                  |
| {% endtab %} |                                       |                                                       |

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

| Code          | Message                             | Description                      |
| ------------- | ----------------------------------- | -------------------------------- |
| `99999`       | `Internal failure! Try again later` | When there is an internal error. |
| {% 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/trust-en/integrations/integration-by-client/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.