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.
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.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 reason text. Keys: ptBr, enUs, esMx — each with a reason string shown during the journey.

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. Retry after the interval indicated in the response headers.

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

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.