Create Process

This endpoint handles two products 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 product 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 product and enabled capabilities.
Content-Type	application/json

Body parameters

Onboarding

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.
subject.clientReference	string	conditional	Unique identifier of the user in your system. Required for the Multi Accounts capability. Unique in your base, maximum of 256 characters, no spaces.
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.

Transactional

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 product, 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

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..."
  }'

Onboarding — Node.js

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();

Transactional — cURL

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..."
  }'

Transactional — Node.js

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

200 OK

The contract is unique — the idCloud.result field carries the consolidated verdict of the capabilities used.

Unico consolidates the results of the executed capabilities into a single idCloud.result, ready to decide your flow's next step — with no need to orchestrate individual results.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

Possible result values

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

The returned values depend on the recipe configured in your APIKey. See Flows for the result values each recipe can return.

Transactional

200 OK

The contract is unique — the idCloud.result field carries the consolidated verdict of the capabilities used.

Unico consolidates the results of the executed capabilities into a single idCloud.result, ready to decide your flow's next step — with no need to orchestrate individual results.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

Possible result values

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

The returned values depend on the recipe configured in your APIKey. See Flows for the result values each recipe can return.

Error Codes

400 Bad Request

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.
20532	No face detected in image.	No face could be detected in the submitted image.
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.

403 Forbidden

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

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.

409 Conflict

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

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.

500 Internal Server Error

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.
• To see all recipe combinations and their possible result values, see Flows.
• For Document and Age Verification operations, see the respective pages in this section.