Create Process

MarkdownChatGPTClaude

This endpoint handles three 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).
• Cardholder Verification — confirms a card belongs to its declared holder, without any selfie capture (subject.code + card required). Optionally reuses a previously validated process via referenceProcessId to trigger the reuse gate; without it, the response defaults to unsure. See the Cardholder Verification capability.

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_AR_DNI, DUI_TYPE_BR_CPF, DUI_TYPE_ID_NIK, DUI_TYPE_MX_CURP, DUI_TYPE_NG_NIN, DUI_TYPE_US_SSN.
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.

Cardholder Verification

Field	Type	Required	Description
subject.duiType	integer	yes	Document type identifier. See duiType values below. Currently DUI_TYPE_BR_CPF only.
subject.code	string	yes	CPF of the cardholder being verified. No dots or dashes.
card.bin	string	conditional	First 6 or 8 digits of the card (BIN). Required together with card.last4.
card.last4	string	conditional	Last 4 digits of the card. Required together with card.bin.
card.name	string	no	Cardholder's name as printed on the card.
referenceProcessId	string (UUID)	no	ID of a previously validated process to reuse — one with an approved Identity Verification or Liveness result for the same CPF. This capability's current version is reuse-based: without this field, the gate is never triggered and the response defaults to the standard unsure result — the request itself never fails.
useCase	string	no	Operation context, e.g. CardholderVerification.
subsidiaryId	string	no	Branch ID — required only if multiple branches exist.

info

No imageBase64 is sent for this product — Cardholder Verification runs entirely back-end, with no selfie capture step.

duiType values

Country	Code	Description
AR	6	Argentine Passport
AR	7	Argentine DNI
AR	49	Argentine Driving Licence (Licencia Nacional de Conducir)
AT	34	Austrian Tax Number (STNR)
BE	36	Belgian National Number (NN)
BR	1	Brazilian CPF
BR	5	Brazilian Passport
BR	14	Brazilian CNPJ
CA	28	Canadian SIN
CH	33	Swiss AHV/AVS Number
CL	9	Chilean RUN
CL	52	Chilean Passport
CL	57	Chilean Driving Licence (Licencia de Conducir)
CO	26	Colombian NIT
CO	53	Colombian Passport
CO	55	Colombian Driving Licence (Licencia de Conducción)
CO	56	Colombian Citizenship Card (Cédula de Ciudadanía)
DE	41	German Tax Identification Number (IdNr)
DK	29	Danish CPR
EC	10	Ecuadorian NI
ES	50	Spanish Foreigner Identity Number (NIE)
ES	51	Spanish National Identity Document (DNI)
FI	35	Finnish Personal Identity Code (HETU)
FR	46	French Tax Reference Number (SPI)
GB	30	British National Insurance Number (NINO)
GT	12	Guatemalan CUI
ID	16	Indonesian NIK
IE	47	Irish Personal Public Service Number (PPSN)
IT	37	Italian Codice Fiscale (CF)
LU	48	Luxembourg National Identification Number (Matricule)
MX	2	Mexican CURP
MX	25	Mexican RFC (Persona Física)
MX	58	Mexican Driving Licence (Licencia de Conducir)
NG	8	Nigerian NIN
NG	20	Nigerian Bank Verification Number (BVN)
NG	43	Nigerian BVN Token (hashed)
NG	44	Nigerian NIN Token (hashed)
NL	42	Dutch Citizen Service Number (BSN)
NO	39	Norwegian National Identity Number (Fødselsnummer)
PE	27	Peruvian RUC
PE	40	Peruvian DNI
PE	54	Peruvian Passport
PL	31	Polish PESEL
PT	45	Portuguese Tax Identification Number (NIF)
SE	32	Swedish Personal Number (PNR)
SE	38	Swedish Coordination Number (Samordningsnummer)
TR	24	Turkish Identification Number (TCKN)
US	4	United States SSN
US	11	United States Passport
US	18	United States Driver's License
US	21	United States Passport Card
US	22	United States Polycarbonate Passport
US	23	United States ID Card
UY	13	Uruguayan CI
ZZ	15	Email address
ZZ	17	Phone number
—	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

Compressed requests

The API supports sending the request body compressed, using the standard Content-Encoding HTTP header. This is optional and fully backward-compatible: clients that don't send this header keep working exactly as before.

Supported formats

Encoding	Content-Encoding header	Status
Gzip	gzip	✅ Recommended
Deflate	deflate	✅ Supported
No compression	(header absent)	✅ Supported (default behavior)

Recommendation

Use gzip. It has the most universal support across languages and HTTP libraries, avoiding the implementation ambiguities present in other formats.

Compression is recommended for requests with a large body (e.g. extensive JSON payloads, base64-encoded image uploads, batch submissions). For small requests, the overhead of compressing may not bring a relevant benefit.

How to send a compressed request

1. Compress the request body (e.g. the serialized JSON) using the chosen algorithm.
2. Send the compressed body as binary bytes in the request.
3. Include the Content-Encoding header with the matching value (gzip or deflate).
4. Keep Content-Type describing the original content format (e.g. application/json), not the transport encoding.

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

tip

For the Python example, use the data= parameter, not json=. The json= parameter serializes the payload automatically but does not compress it.

Using deflate instead: the flow above is identical — only the compression call and the Content-Encoding value change.

Language	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate (from qpdf), then -H "Content-Encoding: deflate"
Python	zlib.compress(data) instead of gzip.compress(data)
.NET (C#)	System.IO.Compression.DeflateStream instead of GZipStream

deflate is ambiguous in practice

HTTP's deflate content encoding is specified as a zlib stream (RFC 1950), but some clients and servers historically emit or expect raw DEFLATE (RFC 1951) instead. This API expects the standard zlib-wrapped stream — the same output zlib.compress() (Python) or DeflateStream (.NET) produce by default. When in doubt, prefer gzip, which has no such ambiguity.

Error behavior

If Content-Encoding is sent with an unsupported value, or the body is corrupted or invalid for the declared encoding, the API returns 400 Bad Request with a message indicating the request body failed to decompress.

FAQ

Do I need to change anything if I don't want to use compression? No. Content-Encoding support is additive — requests without this header continue to be processed normally.

Does this affect the API response? No. This feature only concerns the body sent by the client (request). Response compression (what the API returns) is controlled separately by the Accept-Encoding header.

Which format should I choose? Use gzip, unless some specific constraint in your environment requires another format.

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

Cardholder Verification — 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"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

Cardholder Verification — 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'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

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

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

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.

Clients in Brazil may receive the response by capability

The overall response structure stays the same — the single result is the default.

Integrations in Brazil may receive the open, per-capability results. Each capability enabled in the APIKey adds its own block to the response — fields for disabled capabilities are omitted.

{
  "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
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 — see Face Identifier.
idFace.personId	string	Stable opaque identifier for the face, returned alongside idFace.result = FOUND. When no face can be identified in the image, the request fails with error 20532 instead of returning an idFace block.
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.

Clients in Mexico may receive the RENAPO Verification block

The response keeps the same structure and adds the idGov block.

Integrations in Mexico with RENAPO Verification enabled receive an additional idGov block with the record RENAPO holds for the user's CURP. It is a separate answer from the identity result.

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

Field	Type	Description
idGov	object	RENAPO record for the CURP. Absent when the capability is not enabled. {} when RENAPO did not respond. Mexico only. See RENAPO Verification.

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

Field	Type	Description
id	string (UUID)	Process identifier.
status	integer	3 (finished with success), 5 (error). For all possible values, see Get Process.

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.

Clients in Brazil may receive the response by capability

The overall response structure stays the same — the single result is the default.

Integrations in Brazil may receive the open, per-capability results. Each capability enabled in the APIKey adds its own block to the response — fields for disabled capabilities are omitted.

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

Field	Type	Description
biometryToken.result	boolean	true if the submitted face matches the reference process; false otherwise.
liveness	integer	1 (passed), 2 (failed) — see Liveness.

Cardholder Verification

200 OK

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

Field	Type	Description
id	string (UUID)	Process identifier.
status	integer	1 (processing), 3 (finished with success), 5 (error). For all values, see Get Process.
cardholderVerification.result	string	approved — the CPF and the card belong to the same person. unsure — either the reuse gate wasn't satisfied, or the verification itself was inconclusive. Absent while status is not yet 3. See Cardholder Verification.

Error Codes

400 Bad Request

Code	Message	Description
40221	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	The reuse flow (referenceProcessId/bioTokenId, no image) was rejected because process reuse is not enabled for this API key.
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. Does not apply to Cardholder Verification — its referenceProcessId is never validated as required; an unsatisfied reuse gate answers unsure instead.
20533	The card field is missing.	Cardholder Verification: the card object was not provided.
20534	The card.bin field is missing.	Cardholder Verification: card.bin was not provided.
20535	The card.last4 field is missing.	Cardholder Verification: card.last4 was not provided.
20536	The card data is invalid.	Cardholder Verification: the card data was rejected as invalid.
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.