Create Process

This is the entry point of every Web & SDK 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 Web & SDK Overview.

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	Type	Required	Description
callbackUri	string	yes	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	yes	Flow identifier — determines which capabilities run. Examples: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. See Available flows.
purpose	string	yes	Business purpose. Accepted values: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	yes	Document type. Accepted values: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_BR_PASSPORT, DUI_TYPE_AR_PASSPORT, DUI_TYPE_AR_DNI, DUI_TYPE_NG_NIN, DUI_TYPE_CL_RUN, DUI_TYPE_EC_NI, DUI_TYPE_US_PASSPORT, DUI_TYPE_GT_CUI, DUI_TYPE_UY_CI, DUI_TYPE_ZZ_EMAIL, DUI_TYPE_ID_NIK, DUI_TYPE_ZZ_PHONE_NUMBER, DUI_TYPE_US_DRIVER_LICENSE, DUI_TYPE_NG_BVN, DUI_TYPE_MX_RFC_PERSONA_FISICA, DUI_TYPE_CO_NIT, DUI_TYPE_PE_RUC, DUI_TYPE_CA_SIN, DUI_TYPE_DK_CPR, DUI_TYPE_GB_NINO, DUI_TYPE_PL_PESEL, DUI_TYPE_SE_PNR, DUI_TYPE_AT_STNR, DUI_TYPE_FI_HETU.
person.duiValue	string	yes	Document number, without formatting.
person.friendlyName	string	no	User's display name shown in the journey UI. Maximum 50 characters.
person.phone	string	no	Phone number in DDI + DDD + number format, without separators. Required when sending notifications via SMS or WhatsApp.
person.email	string	no	Email address. Required for flows with Electronic Signature.
person.notifications	array	no	Notification channels for sending the journey link. Each item has notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS, or NOTIFICATION_CHANNEL_EMAIL.
bioTokenId	string (UUID)	conditional	Deprecated. Use references instead. ID of the reference biometric process. Required for 1:1 validation flows (idtoken, idtokentrust, idtokensign) and Smart Revalidation (idsmart).
references	array	conditional	Reference inputs for 1:1 validation and Smart Revalidation flows, replacing bioTokenId. Each item contains referenceType (REFERENCE_TYPE_IMAGE_BASE64 or REFERENCE_TYPE_PROCESS_ID) and referenceContent (base64-encoded image or process UUID).
useCase	string	conditional	Smart Revalidation use case. Required for idsmart. Examples: USE_CASE_LOGIN, USE_CASE_IDENTITY_REVALIDATION_7_DAYS, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	no	Your internal identifier for this process (foreign key for cross-referencing in the portal).
companyBranchId	string (UUID)	no	Branch ID. Required only if the service account has more than one branch associated.
expiresIn	string	no	Process validity window from creation. Format: "3600s". Defaults to 7 days if omitted.
flow_config	object	no	Per-flow configuration overrides.
flow_config.biometry_capture.enabled_back_camera	boolean	no	Use the device's rear camera. Not compatible with document capture or Electronic Signature flows.
contextualization	object	no	Transaction context shown to the user during the journey to explain the capture.
contextualization.company_name	string	no	Company name displayed during the journey. Maximum 20 characters.
contextualization.currency	string	no	Currency code displayed to the user. Accepted values: BRL, MXN, USD.
contextualization.price	number	no	Transaction amount displayed to the user.
contextualization.locale	object	no	Localized text shown during the journey. Keys: ptBr, enUs, esMx.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	no	Short reason for the capture, shown during the journey. Maximum 50 characters.
contextualization.locale.{ptBr|enUs|esMx}.title	string	no	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	no	Body of the customer notice shown during the journey. Maximum 210 characters. Must be provided together with title. HTML tags are stripped.

Example

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUri": "https://app.client.com/callback",
    "flow": "idunicodocs",
    "purpose": "biometryonboarding",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]"
    }
  }'

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({
    callbackUri: 'https://app.client.com/callback',
    flow: 'idunicodocs',
    purpose: 'biometryonboarding',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
      friendlyName: 'Luke Skywalker',
      phone: '5511912345678',
      email: '[email protected]'
    }
  })
});

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

Responses

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "flow": "idunicosign",
    "purpose": "biometryonboarding",
    "callbackUri": "https://app.client.com/callback",
    "clientReference": "your-internal-id-123",
    "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "webAppToken": "eyJhbGciOiJSUzI1NiIs...",
    "createdAt": "2023-10-09T09:15:25.417105Z",
    "expiresAt": "2023-10-09T16:15:25.417105Z",
    "capacities": [],
    "authenticationInfo": {},
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

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

400 Bad Request

Returned when the request payload is malformed, required fields are missing, or the flow value is unknown.

401 Unauthorized

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

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	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.
9	XX ID Apikeys are not set	When the API Key is not properly configured.

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.

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