Set Process DocumentPOST

Create a process without a document, let the user complete the capture, then send the document from your back-end. The process finishes after that.

MarkdownChatGPTClaude

Lifecycle

1. Your back-end creates the process with Create Process, without person.duiType and person.duiValue. The flow must allow an optional document. The process starts as PROCESS_STATE_CREATED.
2. The user runs the journey and performs the capture.
3. The Unico API moves the process to AWAITING_FOR_DOCUMENT, the state that Get Process returns while the process waits for the document. You can already read the partial results of the capabilities that do not depend on duiValue.
4. Your back-end calls this endpoint with the process ID in the URL and the document in the body. The Unico API then finishes the process, and it moves to PROCESS_STATE_FINISHED.

The response does not carry the final result

Read the final state and result with Get Process, or wait for the webhook.

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

Headers

Header	Value
Authorization	Bearer <access_token> (see Authentication)
Content-Type	application/json

The credentials need the same permission used to call Create Process.

Path parameters

Parameter	Type	Required	Description
processId	string (UUID)	yes	Process identifier returned by Create Process.

Body parameters

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. Up to 320 characters.

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

When the call is accepted

• The process is in AWAITING_FOR_DOCUMENT: the user already completed the capture.
• The process has not expired.
• The flow allows an optional document.

The document is immutable. A second call fails, because the process is no longer awaiting a document.

Example

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678909"
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}/document`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    }),
  }
);
const { processId: id, duiType, duiValue } = await res.json();

Responses

200 OK

{
  "processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
  "duiType": "DUI_TYPE_BR_CPF",
  "duiValue": "12345678909"
}

Field	Type	Description
processId	string (UUID)	Process identifier.
duiType	enum	Document type registered for the process.
duiValue	string	Document number registered for the process.

The example values are placeholders.

Error Codes

400 Bad Request

Code	Description
3	processId is missing or invalid, duiType is unspecified, or duiValue is empty or longer than 320 characters.
9	The process is not awaiting a document (this includes a document already set), has expired or finished, or the flow does not allow an optional document.

401 Unauthorized

Code	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.

403 Forbidden

Code	Description
7	The credentials lack the permission required by Create Process.

404 Not Found

Code	Description
5	The process does not exist, or does not belong to your company.

429 Too Many Requests

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.

warning

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.

500 Internal Server Error

Code	Description
13	The document could not be saved.

note

The document is registered with the identity service before it is stored. If that registration fails, the call returns the status of that failure.

What's next

• To read the final state and result, see Get Process.
• To be notified when the process finishes, see Webhooks and Events.