Get Reusable Documents

Use this endpoint to check if a user already has a document available for reuse before starting a new Document capture flow. If a document is found, its documentId can be passed directly to POST /processes/v1 (Document type) to skip the capture step.

Endpoint

Environment	URL
Production	GET https://api.id.unico.app/documents/v1
Sandbox	GET https://api.id.uat.unico.app/documents/v1

Request

Headers

Header	Value
Authorization	Bearer <access_token> (see Authentication)
APIKEY	Provisioned API key with Document Capture and Reuse enabled.

Query parameters

Parameter	Type	Required	Description
code	string	yes	User identifier (CPF or CURP, without formatting).
type	string	yes	Document type to query. Accepted values: BR_RG, BR_CNH, BR_CIN, BR_PASSPORT.

note

The type values above are specific to this endpoint. Do not confuse them with:

• subject.duiType in POST requests — uses the DUI_TYPE_* prefix and identifies the person, not the document type (e.g., DUI_TYPE_BR_CPF).
• documentType in the response — uses the full registry path (e.g., unico.moja.dictionary.br.cnh.v2.Cnh).

Example

cURL

curl -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.id.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → pass to POST /processes/v1 for reuse

Responses

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

Field	Type	Description
items	array	List of reusable documents found for the user. Empty array if no reusable document was found for the given code and type.
items[].documentType	string	Document type identifier. Possible values: unico.moja.dictionary.br.rg.v2.Rg, unico.moja.dictionary.br.cnh.v2.Cnh, unico.moja.dictionary.br.cin.v1.Cin, unico.moja.dictionary.br.passaporte.v1.Passaporte.
items[].documentId	string	Document identifier. Pass this value in document.documentId on POST /processes/v1 to reuse the document.

403 Forbidden

Bearer token or APIKEY missing, expired, or invalid.

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.

Using the documentId for reuse

Once you have a documentId, pass it in the Document process request to skip capture:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

Field	Description
document.purpose	Business purpose for this document process. Accepted values: creditprocess, carpurchase, paybypaycheck, onboarding, fgts. These values are specific to the Document API and differ from the biometric SDK's purpose enum.
document.authProcessId	ID of the biometric process previously created for this user (from POST /processes/v1).
document.documentId	Document ID obtained from this endpoint's response. When provided, document.files can be omitted — the platform retrieves the previously captured document automatically.

For the full Document process request schema, see Create Document Process.

Error Codes

400 Bad Request

Code	Message	Description
20507	O parâmetro subject.code é inválido.	Malformed or non-existent identifier value (CPF or CURP).
20002	O parâmetro APIKey não foi informado.	Missing APIKEY header.
20001	O parâmetro authtoken não foi informado.	Missing authentication token header.

403 Forbidden

Code	Message	Description
30020	The provided authorization token does not have permission to perform this action.	Token lacks permission to access the document selfie.
30017	User does not have permission to perform this action.	Malformed JWT or user without permission to perform this operation.
10502	O token informado está expirado.	Expired access-token.
10501	O token informado é inválido.	Invalid authentication token.
10201	O AppKey informado é inválido.	Missing or nonexistent APIKEY.

404 Not Found

Code	Message	Description
99987	Attachment not found.	Attachment associated with the document was not found.
50001	The process is not found.	No document found for the provided parameters.

500 Internal Server Error

Code	Message	Description
99999	Internal failure! Try again later.	Server-side processing error.