Set Process Document
Sets the identification document (CPF, CURP, SSN or other duiType) on a process that was created without one. Once set, the document is immutable.
Only available when the Custom Flow allows creating a process without a document, and only while the process is in PROCESS_STATE_AWAITING_FOR_DOCUMENT.
Lifecycle
- Your back-end creates the process with Create Process, without
person.duiTypeandperson.duiValue. The Custom Flow must allow an optional document. The process starts asPROCESS_STATE_CREATED. - The user runs the journey and performs the capture.
- The process moves to
PROCESS_STATE_AWAITING_FOR_DOCUMENT. Check it in thestatefield returned by Get Process. - Your back-end calls this endpoint with the process ID in the URL and the document in the body. The process moves back to
PROCESS_STATE_CREATEDand resumes: the capabilities that depend on the document run, and the process moves toPROCESS_STATE_FINISHEDwhen they complete.
Endpoint
| Environment | URL |
|---|---|
| Production | POST https://api.idcloud.unico.app/client/v1/process/{processId}/document |
| Sandbox | POST https://api.idcloud.uat.unico.app/client/v1/process/{processId}/document |
Request
| Header | Value |
|---|---|
Authorization | Bearer <access_token> (see Authentication) |
Content-Type | application/json |
| Field | Type | Required | Description |
|---|---|---|---|
processId | string | yes | Process ID returned in process.id at creation. |
| Field | Type | Required | Description |
|---|---|---|---|
duiType | enum | yes | Document type. DUI_TYPE_UNSPECIFIED is rejected. See duiType values below. |
duiValue | string | yes | Document number, without formatting. Maximum 320 characters (accommodates encoded or composite identifiers; standard document numbers such as CPF or CURP are significantly shorter). |
duiType values
| Country | Value | Description |
|---|---|---|
| AR | DUI_TYPE_AR_PASSPORT | Argentine Passport |
| AR | DUI_TYPE_AR_DNI | Argentine DNI |
| AR | DUI_TYPE_AR_LNC | Argentine Driving Licence (Licencia Nacional de Conducir) |
| AT | DUI_TYPE_AT_STNR | Austrian Tax Number (STNR) |
| BE | DUI_TYPE_BE_NN | Belgian National Number (NN) |
| BR | DUI_TYPE_BR_CPF | Brazilian CPF |
| BR | DUI_TYPE_BR_PASSPORT | Brazilian Passport |
| BR | DUI_TYPE_BR_CNPJ | Brazilian CNPJ |
| CA | DUI_TYPE_CA_SIN | Canadian SIN |
| CH | DUI_TYPE_CH_AHV | Swiss AHV/AVS Number |
| CL | DUI_TYPE_CL_RUN | Chilean RUN |
| CL | DUI_TYPE_CL_PASSPORT | Chilean Passport |
| CL | DUI_TYPE_CL_LICENCIA_CONDUCIR | Chilean Driving Licence (Licencia de Conducir) |
| CO | DUI_TYPE_CO_NIT | Colombian NIT |
| CO | DUI_TYPE_CO_PASSPORT | Colombian Passport |
| CO | DUI_TYPE_CO_LICENCIA_CONDUCCION | Colombian Driving Licence (Licencia de Conducción) |
| CO | DUI_TYPE_CO_CC | Colombian Citizenship Card (Cédula de Ciudadanía) |
| DE | DUI_TYPE_DE_IDNR | German Tax Identification Number (IdNr) |
| DK | DUI_TYPE_DK_CPR | Danish CPR |
| EC | DUI_TYPE_EC_NI | Ecuadorian NI |
| ES | DUI_TYPE_ES_NIE | Spanish Foreigner Identity Number (NIE) |
| ES | DUI_TYPE_ES_DNI | Spanish National Identity Document (DNI) |
| FI | DUI_TYPE_FI_HETU | Finnish Personal Identity Code (HETU) |
| FR | DUI_TYPE_FR_SPI | French Tax Reference Number (SPI) |
| GB | DUI_TYPE_GB_NINO | British National Insurance Number (NINO) |
| GT | DUI_TYPE_GT_CUI | Guatemalan CUI |
| ID | DUI_TYPE_ID_NIK | Indonesian NIK |
| IE | DUI_TYPE_IE_PPSN | Irish Personal Public Service Number (PPSN) |
| IT | DUI_TYPE_IT_CF | Italian Codice Fiscale (CF) |
| LK | DUI_TYPE_LK_NIC | Sri Lankan NIC |
| LU | DUI_TYPE_LU_MATRICULE | Luxembourg National Identification Number (Matricule) |
| MX | DUI_TYPE_MX_CURP | Mexican CURP |
| MX | DUI_TYPE_MX_RFC_PERSONA_FISICA | Mexican RFC (Persona Física) |
| MX | DUI_TYPE_MX_LICENCIA_CONDUCIR | Mexican Driving Licence (Licencia de Conducir) |
| NG | DUI_TYPE_NG_NIN | Nigerian NIN |
| NG | DUI_TYPE_NG_BVN | Nigerian Bank Verification Number (BVN) |
| NG | DUI_TYPE_NG_BVN_TOKEN | Nigerian BVN Token (hashed) |
| NG | DUI_TYPE_NG_NIN_TOKEN | Nigerian NIN Token (hashed) |
| NL | DUI_TYPE_NL_BSN | Dutch Citizen Service Number (BSN) |
| NO | DUI_TYPE_NO_FNR | Norwegian National Identity Number (Fødselsnummer) |
| PE | DUI_TYPE_PE_RUC | Peruvian RUC |
| PE | DUI_TYPE_PE_DNI | Peruvian DNI |
| PE | DUI_TYPE_PE_PASSPORT | Peruvian Passport |
| PL | DUI_TYPE_PL_PESEL | Polish PESEL |
| PT | DUI_TYPE_PT_NIF | Portuguese Tax Identification Number (NIF) |
| SE | DUI_TYPE_SE_PNR | Swedish Personal Number (PNR) |
| SE | DUI_TYPE_SE_SAMORDNINGSNUMMER | Swedish Coordination Number (Samordningsnummer) |
| TR | DUI_TYPE_TR_TCKN | Turkish Identification Number (TCKN) |
| US | DUI_TYPE_US_SSN | United States SSN |
| US | DUI_TYPE_US_PASSPORT | United States Passport |
| US | DUI_TYPE_US_DRIVER_LICENSE | United States Driver's License |
| US | DUI_TYPE_US_PASSPORT_CARD | United States Passport Card |
| US | DUI_TYPE_US_POLYCARBONATE_PASSPORT | United States Polycarbonate Passport |
| US | DUI_TYPE_US_ID_CARD | United States ID Card |
| UY | DUI_TYPE_UY_CI | Uruguayan CI |
| ZZ | DUI_TYPE_ZZ_EMAIL | Email address |
| ZZ | DUI_TYPE_ZZ_PHONE_NUMBER | Phone number |
Example
- cURL
- Node.js
curl -X POST https://api.idcloud.unico.app/client/v1/process/3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21/document \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678901"
}'
import fetch from 'node-fetch';
const res = await fetch(
'https://api.idcloud.unico.app/client/v1/process/3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21/document',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
duiType: 'DUI_TYPE_BR_CPF',
duiValue: '12345678901',
}),
}
);
const { processId, duiType, duiValue } = await res.json();
Responses
{
"processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678901"
}
| Field | Type | Description |
|---|---|---|
processId | string | Process identifier. |
duiType | string | Document type set on the process. |
duiValue | string | Document value set on the process. |
The example values are placeholders.
Error Codes
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 429 Too Many Requests
- 500 Internal Server Error
| Code | Message | Description |
|---|---|---|
3 | process id is invalid | When the process id is invalid. |
3 | dui_type is required | When the document type is not provided. |
3 | dui_value is required | When the document number is not provided. |
3 | dui_value exceeds maximum length | When the document number exceeds the maximum character limit. |
3 | — | When duiValue is not a valid number for the given duiType. |
9 | process is not awaiting for document | When the specified process does not accept document submission. |
9 | process expired | When the specified process has expired. |
9 | document already set, cannot be modified | When the process already has a linked document. |
9 | process already finished | When the process has already been finalized. |
9 | flow does not allow optional document | When the document is mandatory for the flow executed by the process. |
Bearer token missing, expired, or invalid. See Authentication.
| 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. |
| Code | Message | Description |
|---|---|---|
7 | — | When the credentials lack the permission required by Create Process. |
| Code | Message | Description |
|---|---|---|
5 | error getting process: rpc error: code = NotFound desc = process not found | When the process ID was not found. |
Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.
Best practices:
- Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
- Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
- Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.
Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.
For default limits, increase requests and additional details, see Rate Limits.
| Code | Message | Description |
|---|---|---|
99999 | Internal failure! Try again later | When an internal error occurs. |
What's next
- After setting the document, the process continues its pipeline. Call Get Process to fetch the result, or wait for the webhook.