# 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.idcloud.uat.unico.app`</mark>;
* Production:  <mark style="color:blue;">`https://api.idcloud.unico.app`</mark>.
  {% endhint %}

***

## Create Process

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

```json
{"openapi":"3.0.0","info":{"title":"CreateProcess","version":"1.0.0"},"servers":[{"url":"https://api.idcloud.uat.unico.app"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/client/v1/process":{"post":{"summary":"Create Process","description":"Endpoint to create a new Onboarding process in by Unico integration.","requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","required":["callbackUri","flow","purpose","person"],"properties":{"callbackUri":{"type":"string","description":"Defines where the user will be redirected at the end of the process. Possible values are: A URL (e.g., https://unico.io), a Schema URL for redirection in native mobile applications (e.g., br.com.meupacote.app://callback - the callback must be registered in your mobile app)"},"flow":{"type":"string","enum":["idonboarding"],"description":"Flow used for Onboarding processes"},"clientReference":{"type":"string","description":"It is a non-mandatory identifier that will be used as an indexer in the portal and you can use it as a form of association (foreign key) between your system and IDCloud."},"companyBranchId":{"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."},"person":{"type":"object","description":"User information.","required":["duiType","duiValue"],"properties":{"duiType":{"type":"string","enum":["DUI_TYPE_MX_CURP","DUI_TYPE_BR_CPF","DUI_TYPE_US_SSN","DUI_TYPE_NG_NIN","DUI_TYPE_AR_DNI","DUI_TYPE_ID_NIK"],"description":"Identification document type. Possible values: **'DUI_TYPE_MX_CURP'** - Mexican CURP as a identifier; **'DUI_TYPE_BR_CPF'** - Brazilian CPF as a identifier; **'DUI_TYPE_US_SSN'** - American SSN as a identifier; **'DUI_TYPE_NG_NIN'** - Nigerian NIN as identifier **'DUI_TYPE_AR_DNI'** - Argentine DNI as identifier; **'DUI_TYPE_ID_NIK'** - Indonesian NIK as identifier."},"duiValue":{"type":"string","description":"Identification document value (e.g., CURP number). Must be sent without dots or dashes."},"friendlyName":{"type":"string","description":"User's name."},"phone":{"type":"string","description":"User's phone number. Mandatory if sending a notification via SMS or WhatsApp. Must contain 12 characters and be sent without dots or dashes, in the DDI + DDD + phone number format."},"email":{"type":"string","description":"The person's email address."},"notifications":{"type":"array","description":"Notification information. This parameter is not required if notifications are not needed.","items":{"type":"object","properties":{"notificationChannel":{"type":"string","description":"Notification channel. Possible values: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS (it's also possible to send notifications to multiple channels by informing more than one)."}}}}}},"purpose":{"type":"string","enum":["creditprocess","biometryonboarding","carpurchase"],"description":"Purpose of the process."},"expiresIn":{"type":"string","description":"Expiration time of the process in seconds from its creation. The value must be in the format \"10080s\", with \"s\" at the end. If not provided, the default value of 7 days will be used."}}}}}},"responses":{"200":{"description":"Process successfully created.","content":{"application/json":{"schema":{"type":"object","properties":{"process":{"type":"object","description":"Information about the Unico process.","properties":{"id":{"type":"string","description":"Process ID."},"flow":{"type":"string","enum":["idonboarding"],"description":"Selected flow."},"callbackUri":{"type":"string","description":"Callback URI."},"userRedirectUrl":{"type":"string","description":"URL for the user journey."},"state":{"type":"string","enum":["PROCESS_STATE_CREATED","PROCESS_STATE_FAILED"],"description":"Process state. Possible values: **'PROCESS_STATE_CREATED'** - Process created; **'PROCESS_STATE_FAILED'** - Process failed."},"result":{"type":"string","enum":["PROCESS_RESULT_UNSPECIFIED"],"description":"Result of the process. Possible values: **'PROCESS_RESULT_UNSPECIFIED'** - The process has not yet finished."},"createdAt":{"type":"string","description":"Process creation date."},"person":{"type":"object","description":"User information.","properties":{"duiType":{"type":"string","description":"Identification document type."},"duiValue":{"type":"string","description":"Identification document value."},"friendlyName":{"type":"string","description":"User's name."},"email":{"type":"string","description":"User's email."},"phone":{"type":"string","description":"User's phone number."},"notifications":{"type":"array","description":"Notification information.","items":{"type":"object","properties":{"notificationChannel":{"type":"string","description":"Notification channel."}}}},"phoneCountryCodeAlpha3":{"type":"string","description":"The information about the CountryCode."}}},"purpose":{"type":"string","enum":["creditprocess","biometryonboarding","carpurchase"],"description":"Process purpose."},"services":{"type":"array","items":{"type":"string"}},"authenticationInfo":{"type":"object","description":"Authentication information.","properties":{"authenticationId":{"type":"string","description":"The process authentication ID."}}},"capacities":{"type":"array","description":"Process capacities.","items":{"type":"string"}},"expiresAt":{"type":"string","description":"Process expiration date."},"token":{"type":"string","description":"Signed token containing the necessary parameters to initialize the Unico web SDK, enabling integration via iFrame."},"companyData":{"type":"object","description":"Information about the company where the process was created. Refers to the 'companyBranchId' field.","properties":{"branchId":{"type":"string"},"countryCode":{"type":"string"}}},"webAppToken":{"type":"string","description":"It is the token for using the SDK-S."}}}}}}}},"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."}}}}}}}},"401":{"description":"Access token error.","content":{"application/json":{"schema":{"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."}}}}}}}}}}}}}
```

{% hint style="warning" %}
Processes must be created exclusively through backend-to-backend communication, due to our CORS policy, which prevents processes from being created through frontend-to-backend communication.
{% endhint %}

#### Error Responses

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

{% endtab %}

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

<table><thead><tr><th width="110" align="center">Code</th><th width="290" align="center">Message</th><th align="center">Description</th></tr></thead><tbody><tr><td align="center"><code>3</code></td><td align="center"><code>invalid flow</code></td><td align="center">When the specified flow does not exist.</td></tr><tr><td align="center"><code>3</code></td><td align="center"><code>invalid person: friendly name exceeds 50 characters.</code></td><td align="center">When the friendly name exceeds 50 characters.</td></tr><tr><td align="center"><code>3</code></td><td align="center"><code>invalid purpose</code></td><td align="center">When the provided proposal is invalid.</td></tr><tr><td align="center"><code>3</code></td><td align="center"><code>invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:</code></td><td align="center">When the provided callbackUri is invalid.</td></tr><tr><td align="center"><code>3</code></td><td align="center">i<code>nvalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL</code></td><td align="center">When the provided email is invalid, but there is email notification.</td></tr><tr><td align="center"><code>3</code></td><td align="center"><code>invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP</code></td><td align="center">When the provided phone number is invalid, but there is notification via SMS or WhatsApp.</td></tr><tr><td align="center"><code>3</code></td><td align="center"><code>idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value</code></td><td align="center">When the provided identifier is invalid.</td></tr><tr><td align="center"><code>3</code></td><td align="center"><code>invalid expiresIn argument</code></td><td align="center">When the expirenIn is invalid.</td></tr><tr><td align="center"><code>9</code></td><td align="center"><code>XX ID Apikeys are not set</code></td><td align="center">When an API Key has not been configured correctly.</td></tr></tbody></table>
{% endtab %}

{% tab title="401 Unauthorized" %}

|             Message             |                        Description                        |
| :-----------------------------: | :-------------------------------------------------------: |
| `Jwt header is an invalid JSON` | When the access token used contains incorrect characters. |
|         `Jwt is expired`        |          When the access token used has expired.          |
|           {% endtab %}          |                                                           |

{% tab title="429 Too Many Requests" %}
No detailed error code will be provided for this situation, only the HTTP status code.
{% endtab %}

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

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

## Get Result

> Endpoint to get the result of a process in by Unico.

```json
{"openapi":"3.0.0","info":{"title":"GetProcess","version":"1.0.0"},"servers":[{"url":"https://api.idcloud.uat.unico.app"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/client/v1/process/{processId}":{"get":{"summary":"Get Result","description":"Endpoint to get the result of a process in by Unico.","parameters":[{"name":"processId","in":"path","required":true,"description":"Process ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Process details retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"process":{"type":"object","description":"by Unico process information.","properties":{"id":{"type":"string","description":"Process ID."},"flow":{"type":"string","enum":["idonboarding"],"description":"Flow used in the process."},"callbackUri":{"type":"string","description":"Callback URI."},"userRedirectUrl":{"type":"string","description":"User redirect URL."},"state":{"type":"string","enum":["PROCESS_STATE_CREATED","PROCESS_STATE_FAILED","PROCESS_STATE_FINISHED"],"description":"Process state. Possible values: **'PROCESS_STATE_CREATED'** - Process created; **'PROCESS_STATE_FINISHED'** - Process finished; **'PROCESS_STATE_FAILED'** - Process failed."},"result":{"type":"string","enum":["PROCESS_RESULT_UNSPECIFIED","PROCESS_RESULT_ERROR","PROCESS_RESULT_VERIFIED","PROCESS_RESULT_LIVE","PROCESS_RESULT_HIGH_RISK","PROCESS_RESULT_CRITICAL_RISK","PROCESS_RESULT_NOT_APPROVED","PROCESS_RESULT_NOT_LIVE"],"description":"Process result. Possible values: **'PROCESS_RESULT_UNSPECIFIED'** - the process has not yet finished; **'PROCESS_RESULT_ERROR'** - process finished with error; **'PROCESS_RESULT_VERIFIED'** - the user was active at the time of capture; it is the face of the ID holder and no evidence related to fraud was found; **'PROCESS_RESULT_LIVE'** - the user was active at the time of the capture; we did not find sufficient evidence to guarantee that they are the ID holder and no evidence of fraud; **'PROCESS_RESULT_HIGH_RISK'** - we recommend rejection, but the decision remains yours. High Risk indicates that we found at least one strong evidence of fraud; **'PROCESS_RESULT_CRITICAL_RISK'** - we recommend rejection, but leave it open for you to decide. Critical Risk indicates that we found at least 2 strong evidences of fraud; **'PROCESS_RESULT_NOT_APPROVED'** - rejection recommended as multiple indications of fraud were detected; **'PROCESS_RESULT_NOT_LIVE'** - the user was not live at the time of capture, although we found no other indications of fraud."},"person":{"type":"object","description":"User information.","properties":{"duiType":{"type":"string","description":"Identification document type."},"duiValue":{"type":"string","description":"Identification document value."},"friendlyName":{"type":"string","description":"User's name."},"email":{"type":"string","description":"User's email."},"phone":{"type":"string","description":"User's phone number."},"notifications":{"type":"array","description":"Notification information.","items":{"type":"object","properties":{"notificationChannel":{"type":"string","description":"Notification channel."}}}},"phoneCountryCodeAlpha3":{"type":"string","description":"The information about the CountryCode."}}},"purpose":{"type":"string","enum":["creditprocess","biometryonboarding","carpurchase"],"description":"Process purpose."},"services":{"type":"array","items":{"type":"string"}},"authenticationInfo":{"type":"object","description":"Authentication information.","properties":{"authenticationId":{"type":"string","description":"Authentication ID."}}},"capacities":{"type":"array","items":{"type":"string"},"description":"Process capabilities."},"expiresAt":{"type":"string","description":"Process expiration date."},"token":{"type":"string","description":"Signed token containing the necessary parameters to initialize the Unico web SDK, enabling integration via iFrame."},"companyData":{"type":"object","description":"Information about the company where the process was created. Refers to the 'companyBranchId' field.","properties":{"branchId":{"type":"string"},"countryCode":{"type":"string"}}}}}}}}}},"400":{"description":"When the process ID is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"Error":{"type":"object","properties":{"Code":{"type":"integer","description":"Error code."},"Description":{"type":"string","description":"Error description."}}}}}}}},"401":{"description":"Access token error.","content":{"application/json":{"schema":{"type":"string","description":"Error description."}}}},"404":{"description":"When the process cannot be found.","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."}}}}}}}}}}}}}
```

{% hint style="info" %}
The answer `PROCESS_RESULT_VERIFIED` 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" %}
To implement your business rules, always validate the parameters in the following order:

* If `state = PROCESS_STATE_FINISHED`, then look at the `result` parameter return and make the decision.

You can also use our [<mark style="color:blue;">**Webhook**</mark>](https://devcenter.unico.io/trust-mx-en/integrations/integration-by-unico/webhook) to know when make to request to retrieve the validation result.
{% endhint %}

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

{% endtab %}

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

<table><thead><tr><th width="110" align="center">Code</th><th width="290" align="center">Message</th><th align="center">Description</th></tr></thead><tbody><tr><td align="center"><code>3</code></td><td align="center"><code>process id is invalid</code></td><td align="center">When the process ID is invalid.</td></tr></tbody></table>
{% endtab %}

{% tab title="401 Unauthorized" %}

|             Message             |                        Description                        |
| :-----------------------------: | :-------------------------------------------------------: |
| `Jwt header is an invalid JSON` | When the access token used contains incorrect characters. |
|         `Jwt is expired`        |          When the access token used has expired.          |
|           {% endtab %}          |                                                           |

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

<table><thead><tr><th width="110" align="center">Code</th><th width="290" align="center">Message</th><th align="center">Description</th></tr></thead><tbody><tr><td align="center"><code>5</code></td><td align="center"><code>error getting process: rpc error: code = NotFound desc = process not found</code></td><td align="center"><p>When the process ID was not found.</p><h4 id="get-users-selfie"><br></h4></td></tr></tbody></table>
{% endtab %}

{% tab title="429 Too Many Requests" %}
No detailed error code will be provided for this situation, only the HTTP status code.
{% endtab %}

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

<table><thead><tr><th width="106" align="center">Code</th><th width="316" align="center">Message</th><th align="center">Description</th></tr></thead><tbody><tr><td align="center">99999</td><td align="center"><code>Internal failure! Try again later</code></td><td align="center">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/trust-en/integrations/integration-by-unico/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.