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.duiType + 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.duiType`	integer	yes	Document type identifier. See `duiType` values below.
`subject.code`	string	yes	User identifier value as defined by `subject.duiType`. No dots or dashes.
`subject.name`	string	no	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`.
`subsidiaryId`	string	no	Branch ID — required only if multiple branches exist.
`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.duiType`	string	no	Identifier type. Possible values: `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`subject.code`	string	no	User identifier value as defined by `subject.duiType`. No dots or dashes.
`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.

duiType values

Country	Code	Description
BR	1	Brazilian CPF
BR	5	Brazilian Passport
MX	2	Mexican CURP
AR	6	Argentine Passport
AR	7	Argentine DNI
US	4	United States SSN
US	11	United States Passport
US	18	United States Driver's License
ID	16	Indonesian NIK
NG	8	Nigerian NIN
CL	9	Chilean RUN
EC	10	Ecuadorian NI
GT	12	Guatemalan CUI
UY	13	Uruguayan CI
ZZ	15	Email address
ZZ	17	Phone number
MX	25	Mexican RFC (Persona Física)
CO	26	Colombian NIT
PE	27	Peruvian RUC
CA	28	Canadian SIN
DK	29	Danish CPR
GB	30	British National Insurance Number (NINO)
PL	31	Polish PESEL
SE	32	Swedish Personal Number (PNR)
AT	34	Austrian Tax Number (STNR)
FI	35	Finnish Personal Identity Code (HETU)
—	0	Unspecified
—	3	Internal Unico identifier

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": {
      "duiType": 1,
      "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: {
      duiType: 1,
      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 '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "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({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    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"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}

Response fields depend on your APIKey

The example above shows all possible capability fields. Your actual response will only include fields for the capabilities enabled in your APIKey configuration — fields for disabled capabilities are omitted entirely. Contact your Unico project manager to enable or adjust capabilities.

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).
`unicoId.result`	string	`yes`, `no`, `inconclusive` — see Identity Verification.
`riskLevel.result`	string	`approved`, `reproved`, `risk-critical`, `risk-high`, `inconclusive` — see possible values below or Fraud Risk Classification.
`idFace.result`	string	`FOUND`, `NOT_FOUND` — see Face Identifier.
`idFace.personId`	string	Stable opaque identifier for the face. Present only when `idFace.result = FOUND`.
`identityFraudsters.result`	string	Deprecated. Use `riskLevel` instead. Clients with ongoing integrations may continue using it while coordinating the migration with their project team.
`government.serpro`	integer	Serpro similarity score (0–100, -1, -2). Available in Brazil only. See Serpro Similarity.
`liveness`	integer	`1` (passed), `2` (failed) — see Liveness.

riskLevel.result — possible values

Value	Meaning
`approved`	It is the face of the ID holder, and no evidence related to fraud was found.
`reproved`	Rejection is recommended, as multiple fraud indicators were detected.
`risk-critical`	Rejection is recommended, but the final decision is up to your discretion. Critical risk indicates that we found at least 2 strong evidences of fraud.
`risk-high`	Rejection is also recommended, but the decision remains yours. High risk indicates that we found at least one strong evidence of fraud.
`inconclusive`	No strong evidence of fraud was found. Therefore, it's not possible to conclude whether there is relevant risk or not.

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