--- title: Create Process description: Create a verification process. Returns a journey URL and SDK tokens that hand the user off to the Unico-hosted capture experience. canonical: https://developer.unico.io/developers/api-reference/post-processes locale: en generated_by: markdown-export --- - [/](/) - API Reference - Create Process **On this page# Create Process 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](/developers/start/flows). ### Endpoint​ EnvironmentURL**Production**`POST https://api.idcloud.unico.app/client/v1/process`**Sandbox**`POST https://api.idcloud.uat.unico.app/client/v1/process` ### Request​ Headers HeaderValue`Authorization``Bearer ` (see [Authentication](/developers/start/authentication))`Content-Type``application/json` Body parameters Field requirements depend on the flowWhether a field is required, optional, or not applicable depends on the `flow` you're integrating — check [Flows](/developers/start/flows) for the specific recipe you're using before assuming a field's requirement from this table alone. FieldTypeDescription`callbackUri`stringURL to which the user is redirected after the journey ends. Use `/` for native SDK flows where the callback is handled in-app.`flow`stringFlow identifier — determines which capabilities run. Examples: `idunicodocs`, `idunicosign`, `idchecktrust`, `idtoken`, `idsmart`. See [Available flows](/developers/start/flows).`purpose`stringBusiness purpose. Accepted values: `creditprocess`, `biometryonboarding`, `carpurchase`, `ageverification`.`person.duiType`enumDocument type. See [`duiType` values](#duitype-values) below.`person.duiValue`stringDocument number, without formatting.`person.friendlyName`stringUser's display name shown in the journey UI. Maximum 50 characters.`person.phone`stringPhone number in DDI + DDD + number format, without separators. Required when sending notifications via SMS or WhatsApp.`person.email`stringEmail address. Required for flows with Electronic Signature.`person.​notifications`arrayNotification channels for sending the journey link. Each item has `notificationChannel`: `NOTIFICATION_CHANNEL_WHATSAPP`, `NOTIFICATION_CHANNEL_SMS`, or `NOTIFICATION_CHANNEL_EMAIL`.`references`arrayReference 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`stringSmart Revalidation scenario. Required for 🇧🇷 `idsmart`, `idsmart_r2`, `idsmart_tp1`. Examples: `USE_CASE_LOGIN`, `USE_CASE_FIN_TRANSACTIONS`.`clientReference`stringUnique identifier of the user in your system. **Required for the [Multi Accounts](/capabilities/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`stringProcess validity window from creation. Format: `"3600s"`. Defaults to 7 days if omitted.`flowConfig`objectPer-flow configuration overrides.`flowConfig.​biometryCapture.​enabledBackCamera`booleanUse the device's rear camera. Not compatible with document capture or Electronic Signature flows.`contextualization`objectTransaction 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`stringCompany name displayed during the journey. Maximum 20 characters.`contextualization.​currency`stringCurrency code displayed to the user. Accepted values: `BRL`, `MXN`, `USD`.`contextualization.​price`numberTransaction amount displayed to the user.`contextualization.​locale`objectLocalized 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`stringShort reason for the capture, shown during the journey. Maximum 50 characters.`contextualization.locale.{ptBr|enUs|esMx}.title`stringTitle 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`stringBody of the customer notice shown during the journey. Maximum 210 characters. Must be provided together with `title`. HTML tags are stripped.`imageBase64`stringThe selfie, captured by your front-end and sent directly, in base64.`document.purpose`enumWhat 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`bytesNew 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`objectMocks a capability's result in test/sandbox environments and marks the response with `simulated: true`. See [Simulating Results (Test Mock)](/developers/start/test-mock). **`duiType` values**CountryValueDescriptionAR`DUI_TYPE_AR_PASSPORT`Argentine PassportAR`DUI_TYPE_AR_DNI`Argentine DNIAR`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 CPFBR`DUI_TYPE_BR_PASSPORT`Brazilian PassportBR`DUI_TYPE_BR_CNPJ`Brazilian CNPJCA`DUI_TYPE_CA_SIN`Canadian SINCH`DUI_TYPE_CH_AHV`Swiss AHV/AVS NumberCL`DUI_TYPE_CL_RUN`Chilean RUNCL`DUI_TYPE_CL_PASSPORT`Chilean PassportCL`DUI_TYPE_CL_LICENCIA_CONDUCIR`Chilean Driving Licence (Licencia de Conducir)CO`DUI_TYPE_CO_NIT`Colombian NITCO`DUI_TYPE_CO_PASSPORT`Colombian PassportCO`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 CPREC`DUI_TYPE_EC_NI`Ecuadorian NIES`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 CUIID`DUI_TYPE_ID_NIK`Indonesian NIKIE`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 NICLU`DUI_TYPE_LU_MATRICULE`Luxembourg National Identification Number (Matricule)MX`DUI_TYPE_MX_CURP`Mexican CURPMX`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 NINNG`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 RUCPE`DUI_TYPE_PE_DNI`Peruvian DNIPE`DUI_TYPE_PE_PASSPORT`Peruvian PassportPL`DUI_TYPE_PL_PESEL`Polish PESELPT`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 SSNUS`DUI_TYPE_US_PASSPORT`United States PassportUS`DUI_TYPE_US_DRIVER_LICENSE`United States Driver's LicenseUS`DUI_TYPE_US_PASSPORT_CARD`United States Passport CardUS`DUI_TYPE_US_POLYCARBONATE_PASSPORT`United States Polycarbonate PassportUS`DUI_TYPE_US_ID_CARD`United States ID CardUY`DUI_TYPE_UY_CI`Uruguayan CIZZ`DUI_TYPE_ZZ_EMAIL`Email addressZZ`DUI_TYPE_ZZ_PHONE_NUMBER`Phone number Creating a process without a documentWhen 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](/developers/api-reference/set-process-document). ### Example​ cURLNode.js``` 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" } }' ``` ``` 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 }} ``` FieldTypeDescription`process.id`string (UUID)Process identifier. Use it to fetch the result via [Get Process](/developers/api-reference/get-process).`process.state`enum`PROCESS_STATE_CREATED` — process created, journey not yet started. `PROCESS_STATE_FAILED` — process creation failed.`process.result`enumVerification outcome. Present only when `state = PROCESS_STATE_FINISHED` — see [Flows](/developers/start/flows) for the result values a given flow can return.`process.flow`stringFlow identifier sent on creation.`process.purpose`stringBusiness purpose sent on creation.`process.callbackUri`stringCallback URI sent on creation.`process.​clientReference`stringYour 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`stringURL to redirect the user to (Web Redirect and iFrame integrations). Do not modify this URL.`process.token`stringJWT for initializing the **Web SDK iFrame**.`process.webAppToken`stringJWT 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`arrayCapabilities configured for this process.`process.​authenticationInfo`objectAuthentication information for the process (empty at creation time).`process.person`objectEcho of the `person` object sent on creation.`process.​companyData.​branchId`string (UUID)Branch ID associated with the process.`process.​companyData.​countryCode`stringCountry code associated with the branch (e.g., `BR`, `MX`). ### Error Codes​ 400 Bad Request401 Unauthorized403 Forbidden404 Not Found429 Too Many Requests500 Internal Server ErrorCodeMessageDescription`3`invalid flowWhen the specified flow does not exist.`3`invalid person: friendly name exceeds 50 characters.When the friendly name exceeds 50 characters.`3`invalid purposeWhen 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_EMAILWhen 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_WHATSAPPWhen 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 valueWhen the provided identifier (duiValue) is invalid.`3`invalid expiresIn argumentWhen the `expiresIn` value is invalid.`3`invalid company_name argument in process contextualization, max length is 20When `contextualization.​company_name` exceeds 20 characters.`3`title and text must be provided together in process contextsWhen only one of `title` or `text` is provided in a locale.`3`invalid title argument in process contexts, max length is 100When a locale `title` exceeds 100 characters.`3`invalid text argument in process contexts, max length is 210When a locale `text` exceeds 210 characters.`3`invalid reason argument in process contexts, max length is 50When 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_IMAGEWhen the image is not valid base64, or looks like an injection attempt.`3`INVALID_DUIWhen the document number is non-standard or does not exist.`3`IMAGE_TOO_LARGEWhen the image exceeds the maximum size of 800 KB.`3`UNSUPPORTED_IMAGE_FORMATWhen the image format is not PNG, JPEG or WebP.`3`MISSING_IMAGEWhen the image is required for this flow and was not sent.`3`MISSING_NAMEWhen the name is required for this flow and was not sent.`3`MISSING_DUIWhen the document number is required for this flow and was not sent.`3`MISSING_PERSONWhen the `person` object is required for this flow and was not sent.`3`INVALID_REQUESTWhen the request body is null or cannot be interpreted.`3`TOKEN_ALREADY_USEDWhen the capture token has already been used. It is single-use.`3`TOKEN_EXPIREDWhen the capture token has expired. It must be used within 10 minutes.`3`INVALID_BUNDLEWhen the request does not meet the security requirements.`3`INVALID_NAMEWhen the name is longer than the allowed maximum.`3`INVALID_EMAILWhen the email address is malformed or too long.`3`INVALID_PHONEWhen the phone number is longer than 20 characters.`3`INVALID_DUI_TYPEWhen the document type is not one of the supported values.`3`INVALID_CLIENT_REFERENCEWhen `clientReference` is too long, or contains a space or `#`.`3`INVALID_CONSENT_TYPEWhen `consentType` is not `NONE`, `DIRECT` or `INDIRECT`.`3`INVALID_USE_CASEWhen `useCase` is not recognised, or is too long.`3`INVALID_DEVICE_TRUST_TOKENWhen the device-trust token is invalid or has already been consumed.`3`TOO_MANY_REFERENCESWhen more than one item is sent in `references`.`3`INVALID_REFERENCE_TYPEWhen `referenceType` is not `IMAGE_BASE64` or `PROCESS_ID`.`3`INVALID_REFERENCE_PROCESSWhen the reference process ID is not a valid identifier.`3`REFERENCE_PROCESS_NOT_FOUNDWhen the referenced process does not exist.`3`REFERENCE_PROCESS_NOT_READYWhen the referenced process has no reusable result, or was already consumed.`3`REFERENCE_SELFIE_NOT_FOUNDWhen the referenced process carries no selfie to reuse.`3`INVALID_CAPTURE_TOKENWhen the captured image is not a valid token produced by a capture SDK.`3`INVALID_CAPTURE_SIGNATUREWhen the capture token's signature does not validate.`3`PRIOR_CAPTURE_NOT_FOUNDWhen the prior capture this request builds on could not be located. Restart the process.`3`PRIOR_CAPTURE_IN_PROGRESSWhen the prior capture has not finished yet. Retry shortly.`3`PRIOR_CAPTURE_FAILEDWhen the prior capture could not be completed. Restart the process.`3`INVALID_DOCUMENTWhen a document file is unreadable, password-protected, or in an unsupported format.`3`INVALID_AUTH_PROCESSWhen `document.authProcessId` is invalid, expired, or belongs to another person.`3`INVALID_DOCUMENT_PURPOSEWhen `document.purpose` is not one of the supported values.`3`PROCESS_REUSE_NOT_ENABLEDWhen the flow does not allow reusing a prior process without an image. Send an image instead.`9`PROCESS_FAILEDWhen the process reached a terminal failure while being created.`9`Tenant API key is not configuredWhen the API Key is not properly configured.Bearer token missing, expired, or invalid. See [Authentication](/developers/start/authentication).MessageDescriptionJwt header is an invalid JSONWhen the access token used contains incorrect characters.Jwt is expiredWhen the access token used has expired.CodeMessageDescription`7`INVALID_API_KEYWhen the API key is invalid or missing.`7`INVALID_AUTH_TOKENWhen the authentication token is invalid.`7`PERMISSION_DENIEDWhen the credentials are valid but not entitled to this action.`7`TOKEN_TENANT_MISMATCHWhen the capture token was issued for a different tenant.`7`MISSING_ACCESS_TOKENWhen the authorization header is missing.CodeMessageDescription`5`NO_RESULTS_FOUNDWhen a document referenced by the request could not be found.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. warningContinuously 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](/developers/start/rate-limits).CodeMessageDescription`13`Internal failure! Try again laterWhen there is an internal error. ### What's next​ After the user finishes the journey, call [Get Process](/developers/api-reference/get-process) to fetch the result, or wait for the [webhook](/developers/webhooks-and-events). To see all recipe combinations and their possible result values, see [Flows](/developers/start/flows). To test a result without a real biometric capture, see [Simulating Results (Test Mock)](/developers/start/test-mock). Last updated on Oct 8, 2026**