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 for processes whose Custom Flow allows creation without a document — i.e., processes in the AWAITING_FOR_DOCUMENT state.

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

Path parameters

Field	Type	Required	Description
processId	string	yes	Process ID returned in process.id at creation.

Body parameters

Field	Type	Required	Description
duiType	enum	yes	Document type. Values: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN. This endpoint supports a subset of the document types accepted by Create Process — Custom Flows that allow optional document creation are currently validated against this narrower list.
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).

Example

cURL

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

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  'https://api.idcloud.unico.app/client/v1/process/abc-123/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 { process: proc } = await res.json();
// proc.id, proc.person.duiType, proc.person.duiValue

Responses

200 OK

{
  "process": {
    "id": "abc-123",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678901"
    }
  }
}

Field	Type	Description
process.id	string	Process identifier.
process.person.duiType	string	Document type set on the process.
process.person.duiValue	string	Document value set on the process.

400 Bad Request

Returned when the request payload is malformed, required fields are missing, or the process state does not allow the operation.

401 Unauthorized

Bearer token missing, expired, or invalid. See Authentication.

404 Not Found

Process not found.

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.

Error Codes

400 Bad Request

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

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.

404 Not Found

Code	Message	Description
5	error getting process: rpc error: code = NotFound desc = process not found	When the process ID was not found.

429 Too Many Requests

No detailed error code is provided for this status — HTTP status only. See the 429 Too Many Requests section above for best practices.

500 Internal Server Error

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.