Create Process

This endpoint handles two use cases that share the same path but differ in body parameters, capabilities, and response fields:

Onboarding — validates who the user is by comparing their face against Unico's identity base (subject.code required).
Transactional — verifies it's the same person from a previous process by comparing face-to-face (referenceProcessId OR references array with selfie / process id required).

The active use case is determined by the APIKEY sent in the request header.

For the full integration flow, see API Overview.

Endpoint

Environment	URL
Production	`POST https://api.id.unico.app/processes/v1`
Sandbox	`POST https://api.id.uat.unico.app/processes/v1`

Request

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (see Authentication)
`APIKEY`	Provisioned API key — defines the active use case and enabled capabilities.
`Content-Type`	`application/json`

Body parameters

Onboarding
Transactional

Field	Type	Required	Description
`subject.code`	string	yes	CPF (BR) or CURP (MX).
`subject.name`	string	yes	Full name.
`subject.gender`	string	no	`M` or `F`.
`subject.birthDate`	string (ISO 8601)	no	Date of birth (`YYYY-MM-DD`).
`subject.email`	string	no	Email address.
`subject.phone`	string	no	E.164 phone number.
`useCase`	string	no	Operation context, e.g. `Onboarding`.
`imageBase64`	string	yes	Selfie captured by your front-end, in base64.

Field	Type	Required	Description
`references`	array	conditional	Reference inputs for 1:1 validation flows. Each item contains `referenceType` (`REFERENCE_TYPE_IMAGE_BASE64` or `REFERENCE_TYPE_PROCESS_ID`) and `referenceContent` (base64-encoded image or process UUID).
`referenceProcessId`	string	conditional	Deprecated. Use `references` instead. ID of the reference Onboarding process to compare against. If the reference is a by-Unico process, use `authenticationInfo.authenticationId`.
`imageBase64`	string	yes	Selfie captured by your front-end, in base64.
`subject`	object	no	User information container.
`subject.code`	string	no	CPF (BR) or CURP (MX).
`subject.name`	string	no	User's full name.
`subject.gender`	string	no	`M` or `F`.
`subject.birthDate`	string (ISO 8601)	no	Date of birth (`YYYY-MM-DD`).
`subject.email`	string	no	Email address.
`subject.phone`	string	no	E.164 phone number.
`useCase`	string	no	Operation context, e.g. `Transactional`.
`subsidiaryId`	string	no	Branch ID — required only if multiple branches exist.

info

For this use case, it is not possible to orchestrate with Risk Score. The result is always returned synchronously in the POST response.

Image requirements

Minimum resolution: 640 × 480 (HD standard)
Maximum file size: 800 KB (JPEG92 compression recommended)
Accepted formats: PNG, JPEG, WebP
JWT tokens from the SDK expire after 10 minutes and can only be used once

Example

Onboarding — cURL
Onboarding — Node.js
Transactional — cURL
Transactional — Node.js

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    referenceProcessId: referenceProcessId,
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Responses

Onboarding
Transactional

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

Field	Type	Description
`id`	string (UUID)	Process identifier. Use with Get Process for re-queries.
`status`	integer	`1` (processing), `3` (finished with success), `5` (error). For all possible values, see Get Process.
`unicoId.result`	string	`yes`, `no`, `inconclusive` — see Identity Verification.
`identityFraudsters.result`	string	`yes`, `inconclusive` — see Risk Fraud Classification.
`government.serpro`	integer	Serpro similarity score (0–100, -1, -2). See Serpro Similarity.
`liveness`	integer	`1` (passed), `2` (failed) — see Liveness.

info

When unicoId.result = inconclusive and Risk Score orchestration is active, the process may return status: 1 (processing). Poll Get Process or use webhooks to retrieve the final result.

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": { "result": true },
  "liveness": 1
}

Field	Type	Description
`id`	string (UUID)	Process identifier.
`status`	integer	`3` (finished with success), `5` (error). For all possible values, see Get Process.
`biometryToken.result`	boolean	`true` if the submitted face matches the reference process; `false` otherwise.
`liveness`	integer	`1` (passed), `2` (failed) — see Liveness.

400 Bad Request

The payload is malformed, the image is invalid, or required fields are missing. See Error Codes below.

403 Forbidden

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

409 Conflict

The processId provided already exists for this tenant. See Error Codes below.

429 Too Many Requests

Rate limit reached. Retry after the interval indicated in the Retry-After response header. See Rate limits.

Error Codes

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

Code	Message	Description
`20900`	O base64 informado não é válido.	The base64 parameter is invalid. Possible causes: it's not an image or it's an injection attempt.
`20807`	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	The resolution of the uploaded image is too low.
`20513`	The referenced process was not found.	The `referenceProcessId` points to a process that does not exist or is no longer accessible.
`20512`	The referenced process is not available for reuse.	The referenced process exists but is not available for reuse.
`20509`	The subject.name field is invalid.	`subject.name` contains invalid characters.
`20508`	The subject.gender field is invalid.	`subject.gender` must be `M` or `F`.
`20507`	O parâmetro subject.code é inválido.	Non-standard or non-existent CPF.
`20506`	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Image size exceeds 800 KB; compress to JPEG92.
`20505`	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	The base64 format is invalid or unsupported.
`20065`	The referenceProcessId field is invalid.	The `referenceProcessId` is not a valid UUID.
`20062`	The useCase field is invalid.	Unrecognized value in the `useCase` field.
`20024`	The referenceProcessId field is missing.	The `referenceProcessId` parameter was not provided and `references` was not sent as an alternative.
`20021`	The subject.phone field is invalid.	`subject.phone` format is invalid (IDD + area code + number, 13 chars).
`20019`	The subject.birthDate field is invalid.	`subject.birthDate` is outside ISO 8601 format (`YYYY-MM-DD`).
`20009`	O parâmetro imagebase64 não foi informado.	The selfie image parameter is missing.
`20008`	The subject.email field is invalid.	Invalid email format in `subject.email`.
`20006`	O parâmetro subject.name não foi informado.	The subject.name parameter is missing.
`20005`	O parâmetro subject.code não foi informado.	The subject.code parameter is missing.
`20004`	O parâmetro subject não foi informado.	The subject parameter is missing.
`20003`	The request body is missing or invalid.	Null or invalid payload.
`20002`	O parâmetro APIKey não foi informado.	The APIKEY parameter is missing from the request header.
`20001`	O parâmetro authtoken não foi informado.	The integration token parameter is missing from the request header.
`10508`	The JWT with the captured face has already been used.	The JWT can only be used once.
`10507`	The JWT with the captured face is expired.	JWT expired; must be sent within 10 minutes.
`10506`	The imageBase64 field is not a valid JWT from SDK.	The `imageBase64` is not a valid JWT generated by the SDK.

Code	Message	Description
`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.	The access-token has expired.
`10501`	O token informado é inválido.	The authentication token is invalid.
`10201`	O AppKey informado é inválido.	The APIKEY is invalid or does not exist.

Code	Message	Description
`20073`	The processID already exists.	The `processId` provided already exists for this tenant.

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

What's next

For querying an Onboarding process result, see Get Process.
For Document and Age Verification operations, see the respective pages in this section.

Endpoint​

Request​

Example​

Responses​

Error Codes​

What's next​