Create Process

MarkdownChatGPTClaude

This is the entry point of every Unico API integration. Your back-end calls it to create a process; your front-end uses the returned tokens to render the iFrame, redirect the user, or initialize a native SDK.

For the full integration flow, see Flows.

Endpoint

Environment	URL
Production	POST https://api.idcloud.unico.app/client/v1/process
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process

Request

Headers

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

Body parameters

Field requirements depend on the flow

Whether a field is required, optional, or not applicable depends on the flow you're integrating — check Flows for the specific recipe you're using before assuming a field's requirement from this table alone.

Field	Type	Description
callbackUri	string	URL to which the user is redirected after the journey ends. Use / for native SDK flows where the callback is handled in-app.
flow	string	Flow identifier — determines which capabilities run. Examples: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. See Available flows.
purpose	string	Business purpose. Accepted values: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	Document type. See duiType values below.
person.duiValue	string	Document number, without formatting.
person.friendlyName	string	User's display name shown in the journey UI. Maximum 50 characters.
person.phone	string	Phone number in DDI + DDD + number format, without separators. Required when sending notifications via SMS or WhatsApp.
person.email	string	Email address. Required for flows with Electronic Signature.
person.​notifications	array	Notification channels for sending the journey link. Each item has notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS, or NOTIFICATION_CHANNEL_EMAIL.
references	array	Reference inputs for 1:1 validation and Smart Revalidation flows. Each item contains referenceType (REFERENCE_TYPE_IMAGE_BASE64 or REFERENCE_TYPE_PROCESS_ID) and referenceContent (base64-encoded image or process UUID). Send at most one item — a longer array is rejected with 400, and referenceContent must not be empty.
useCase	string	Smart Revalidation scenario. Required for 🇧🇷 idsmart, idsmart_r2, idsmart_tp1. Examples: USE_CASE_LOGIN, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	Unique identifier of the user in your system. Required for the Multi Accounts capability. Unique in your base, maximum of 256 characters, no spaces.
companyBranchId	string (UUID)	Branch ID. Required only if the service account has more than one branch associated.
expiresIn	string	Process validity window from creation. Format: "3600s". Defaults to 7 days if omitted.
flowConfig	object	Per-flow configuration overrides.
flowConfig.​biometryCapture.​enabledBackCamera	boolean	Use the device's rear camera. Not compatible with document capture or Electronic Signature flows.
contextualization	object	Transaction context shown to the user during the journey to explain the capture. Available to clients in any region — not limited to a specific country.
contextualization.​company_name	string	Company name displayed during the journey. Maximum 20 characters.
contextualization.​currency	string	Currency code displayed to the user. Accepted values: BRL, MXN, USD.
contextualization.​price	number	Transaction amount displayed to the user.
contextualization.​locale	object	Localized text shown during the journey. Keys: ptBr, enUs, esMx — these are the only supported languages for the text, regardless of the client's own region.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	Short reason for the capture, shown during the journey. Maximum 50 characters.
contextualization.locale.{ptBr|enUs|esMx}.title	string	Title of the customer notice shown during the journey. Maximum 100 characters. Must be provided together with text. HTML tags are stripped.
contextualization.locale.{ptBr|enUs|esMx}.text	string	Body of the customer notice shown during the journey. Maximum 210 characters. Must be provided together with title. HTML tags are stripped.
imageBase64	string	The selfie, captured by your front-end and sent directly, in base64.
document.purpose	enum	What the document is for. Fixed vocabulary: DOCUMENT_PURPOSE_ONBOARDING, DOCUMENT_PURPOSE_CREDIT_PROCESS, DOCUMENT_PURPOSE_CAR_PURCHASE, DOCUMENT_PURPOSE_PAY_BY_PAYCHECK, DOCUMENT_PURPOSE_FGTS. Only used with Face Document Match flows.
document.​files[].​data	bytes	New document capture, base64-encoded. Available globally, not limited to Brazil. Mutually exclusive with document.documentId.
document.documentId	string (UUID)	Reuses a document already captured by the same person, instead of a new capture. Mutually exclusive with document.files[].
expectedResult	object	Mocks a capability's result in test/sandbox environments and marks the response with simulated: true. See Simulating Results (Test Mock).

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

Creating a process without a document

When the flow allows an optional document, you can omit person.duiType and person.duiValue. After the capture, the process waits in AWAITING_FOR_DOCUMENT until your back-end sends the document with Set Process Document.

Example

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "idunicodocs_r2",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "person": {
      "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', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    flow: 'idunicodocs_r2',
    purpose: 'biometryonboarding',
    clientReference: 'pedido-88216',
    callbackUri: 'https://your-app.example.com/onboarding/callback',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    },
  }),
});

const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken

Responses

200 OK

{
  "process": {
    "id": "b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "flow": "idunicodocs_r2",
    "state": "PROCESS_STATE_CREATED",
    "result": "PROCESS_RESULT_UNSPECIFIED",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    },
    "capacities": [
      "PROCESS_CAPACITY_IDLIVE",
      "PROCESS_CAPACITY_IDUNICO",
      "PROCESS_CAPACITY_IDDOCS"
    ],
    "authenticationInfo": {
      "authenticationId": ""
    },
    "companyData": {
      "branchId": "",
      "countryCode": "BRA"
    },
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "userRedirectUrl": "https://cadastro.unico.app/flow?id=b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
    "webAppToken": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0…",
    "simulated": false
  }
}

Field	Type	Description
process.id	string (UUID)	Process identifier. Use it to fetch the result via Get Process.
process.state	enum	PROCESS_STATE_CREATED — process created, journey not yet started. PROCESS_STATE_FAILED — process creation failed.
process.result	enum	Verification outcome. Present only when state = PROCESS_STATE_FINISHED — see Flows for the result values a given flow can return.
process.flow	string	Flow identifier sent on creation.
process.purpose	string	Business purpose sent on creation.
process.callbackUri	string	Callback URI sent on creation.
process.​clientReference	string	Your internal identifier sent on creation. Only present if provided in the request.
process.​companyBranchId	string (UUID)	Branch ID. Only present if provided in the request.
process.​userRedirectUrl	string	URL to redirect the user to (Web Redirect and iFrame integrations). Do not modify this URL.
process.token	string	JWT for initializing the Web SDK iFrame.
process.webAppToken	string	JWT for initializing native SDKs (Android, iOS, Flutter).
process.createdAt	string (date-time)	Timestamp when the process was created.
process.expiresAt	string (date-time)	Timestamp after which the process expires and can no longer be completed.
process.capacities	array	Capabilities configured for this process.
process.​authenticationInfo	object	Authentication information for the process (empty at creation time).
process.person	object	Echo of the person object sent on creation.
process.​companyData.​branchId	string (UUID)	Branch ID associated with the process.
process.​companyData.​countryCode	string	Country code associated with the branch (e.g., BR, MX).

Error Codes

400 Bad Request

Code	Message	Description
3	invalid flow	When the specified flow does not exist.
3	invalid person: friendly name exceeds 50 characters.	When the friendly name exceeds 50 characters.
3	invalid purpose	When the provided purpose is invalid.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	When the provided callbackUri is invalid.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	When the provided email is invalid and email notification is configured.
3	invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP	When the provided phone number is invalid and SMS or WhatsApp notification is configured.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	When the provided identifier (duiValue) is invalid.
3	invalid expiresIn argument	When the expiresIn value is invalid.
3	invalid company_name argument in process contextualization, max length is 20	When contextualization.​company_name exceeds 20 characters.
3	title and text must be provided together in process contexts	When only one of title or text is provided in a locale.
3	invalid title argument in process contexts, max length is 100	When a locale title exceeds 100 characters.
3	invalid text argument in process contexts, max length is 210	When a locale text exceeds 210 characters.
3	invalid reason argument in process contexts, max length is 50	When a locale reason exceeds 50 characters.
3	The references array must contain at most one element.	When more than one item is sent in references.
3	The references[].referenceContent field is missing.	When referenceContent is empty.
3	The references[].referenceType field must be IMAGE_BASE64 or PROCESS_ID.	When referenceType is not one of the supported values.
3	A reference is required for this flow.	When the flow requires a reference and none was sent. Send references[0] with referenceType PROCESS_ID or IMAGE_BASE64.
9	The referenceProcessId field is invalid.	When the reference process does not exist or cannot be reused. Names the field you sent — bioTokenId if you sent that one.
3	INVALID_IMAGE	When the image is not valid base64, or looks like an injection attempt.
3	INVALID_DUI	When the document number is non-standard or does not exist.
3	IMAGE_TOO_LARGE	When the image exceeds the maximum size of 800 KB.
3	UNSUPPORTED_IMAGE_FORMAT	When the image format is not PNG, JPEG or WebP.
3	MISSING_IMAGE	When the image is required for this flow and was not sent.
3	MISSING_NAME	When the name is required for this flow and was not sent.
3	MISSING_DUI	When the document number is required for this flow and was not sent.
3	MISSING_PERSON	When the person object is required for this flow and was not sent.
3	INVALID_REQUEST	When the request body is null or cannot be interpreted.
3	TOKEN_ALREADY_USED	When the capture token has already been used. It is single-use.
3	TOKEN_EXPIRED	When the capture token has expired. It must be used within 10 minutes.
3	INVALID_BUNDLE	When the request does not meet the security requirements.
3	INVALID_NAME	When the name is longer than the allowed maximum.
3	INVALID_EMAIL	When the email address is malformed or too long.
3	INVALID_PHONE	When the phone number is longer than 20 characters.
3	INVALID_DUI_TYPE	When the document type is not one of the supported values.
3	INVALID_CLIENT_REFERENCE	When clientReference is too long, or contains a space or #.
3	INVALID_CONSENT_TYPE	When consentType is not NONE, DIRECT or INDIRECT.
3	INVALID_USE_CASE	When useCase is not recognised, or is too long.
3	INVALID_DEVICE_TRUST_TOKEN	When the device-trust token is invalid or has already been consumed.
3	TOO_MANY_REFERENCES	When more than one item is sent in references.
3	INVALID_REFERENCE_TYPE	When referenceType is not IMAGE_BASE64 or PROCESS_ID.
3	INVALID_REFERENCE_PROCESS	When the reference process ID is not a valid identifier.
3	REFERENCE_PROCESS_NOT_FOUND	When the referenced process does not exist.
3	REFERENCE_PROCESS_NOT_READY	When the referenced process has no reusable result, or was already consumed.
3	REFERENCE_SELFIE_NOT_FOUND	When the referenced process carries no selfie to reuse.
3	INVALID_CAPTURE_TOKEN	When the captured image is not a valid token produced by a capture SDK.
3	INVALID_CAPTURE_SIGNATURE	When the capture token's signature does not validate.
3	PRIOR_CAPTURE_NOT_FOUND	When the prior capture this request builds on could not be located. Restart the process.
3	PRIOR_CAPTURE_IN_PROGRESS	When the prior capture has not finished yet. Retry shortly.
3	PRIOR_CAPTURE_FAILED	When the prior capture could not be completed. Restart the process.
3	INVALID_DOCUMENT	When a document file is unreadable, password-protected, or in an unsupported format.
3	INVALID_AUTH_PROCESS	When document.authProcessId is invalid, expired, or belongs to another person.
3	INVALID_DOCUMENT_PURPOSE	When document.purpose is not one of the supported values.
3	PROCESS_REUSE_NOT_ENABLED	When the flow does not allow reusing a prior process without an image. Send an image instead.
9	PROCESS_FAILED	When the process reached a terminal failure while being created.
9	Tenant API key is not configured	When the API Key is not properly configured.

401 Unauthorized

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.

403 Forbidden

Code	Message	Description
7	INVALID_API_KEY	When the API key is invalid or missing.
7	INVALID_AUTH_TOKEN	When the authentication token is invalid.
7	PERMISSION_DENIED	When the credentials are valid but not entitled to this action.
7	TOKEN_TENANT_MISMATCH	When the capture token was issued for a different tenant.
7	MISSING_ACCESS_TOKEN	When the authorization header is missing.

404 Not Found

Code	Message	Description
5	NO_RESULTS_FOUND	When a document referenced by the request could not be 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.

500 Internal Server Error

Code	Message	Description
13	Internal failure! Try again later	When there is an internal error.

What's next

• After the user finishes the journey, call Get Process to fetch the result, or wait for the webhook.
• To see all recipe combinations and their possible result values, see Flows.
• To test a result without a real biometric capture, see Simulating Results (Test Mock).