Skip to main content

Create Process

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​

EnvironmentURL
ProductionPOST https://api.id.unico.app/processes/v1
SandboxPOST https://api.id.uat.unico.app/processes/v1

Request​

Headers
HeaderValue
AuthorizationBearer <access_token> (see Authentication)
APIKEYProvisioned API key — defines the active product and enabled capabilities.
Content-Typeapplication/json
Body parameters
FieldTypeRequiredDescription
subject.duiTypeintegeryesDocument type identifier. See duiType values below.
subject.codestringyesUser identifier value as defined by subject.duiType. No dots or dashes.
subject.namestringnoFull name.
subject.genderstringnoM or F.
subject.birthDatestring (ISO 8601)noDate of birth (YYYY-MM-DD).
subject.emailstringnoEmail address.
subject.phonestringnoE.164 phone number.
subject.clientReferencestringconditionalUnique identifier of the user in your system. Required for the Multi Accounts capability. Unique in your base, maximum of 256 characters, no spaces.
useCasestringnoOperation context, e.g. Onboarding.
subsidiaryIdstringnoBranch ID — required only if multiple branches exist.
imageBase64stringyesSelfie captured by your front-end, in base64.
duiType values
CountryCodeDescription
BR1Brazilian CPF
MX2Mexican CURP
US4United States SSN
BR5Brazilian Passport
AR6Argentine Passport
AR7Argentine DNI
NG8Nigerian NIN
CL9Chilean RUN
EC10Ecuadorian NI
US11United States Passport
GT12Guatemalan CUI
UY13Uruguayan CI
BR14Brazilian CNPJ
ZZ15Email address
ID16Indonesian NIK
ZZ17Phone number
US18United States Driver's License
NG20Nigerian Bank Verification Number (BVN)
US21United States Passport Card
US22United States Polycarbonate Passport
US23United States ID Card
TR24Turkish Identification Number (TCKN)
MX25Mexican RFC (Persona Física)
CO26Colombian NIT
PE27Peruvian RUC
CA28Canadian SIN
DK29Danish CPR
GB30British National Insurance Number (NINO)
PL31Polish PESEL
SE32Swedish Personal Number (PNR)
CH33Swiss AHV/AVS Number
AT34Austrian Tax Number (STNR)
FI35Finnish Personal Identity Code (HETU)
BE36Belgian National Number (NN)
IT37Italian Codice Fiscale (CF)
SE38Swedish Coordination Number (Samordningsnummer)
NO39Norwegian National Identity Number (Fødselsnummer)
PE40Peruvian DNI
DE41German Tax Identification Number (IdNr)
NL42Dutch Citizen Service Number (BSN)
NG43Nigerian BVN Token (hashed)
NG44Nigerian NIN Token (hashed)
PT45Portuguese Tax Identification Number (NIF)
FR46French Tax Reference Number (SPI)
IE47Irish Personal Public Service Number (PPSN)
LU48Luxembourg National Identification Number (Matricule)
AR49Argentine Driving Licence (Licencia Nacional de Conducir)
ES50Spanish Foreigner Identity Number (NIE)
ES51Spanish National Identity Document (DNI)
CL52Chilean Passport
CO53Colombian Passport
PE54Peruvian Passport
CO55Colombian Driving Licence (Licencia de Conducción)
CO56Colombian Citizenship Card (Cédula de Ciudadanía)
CL57Chilean Driving Licence (Licencia de Conducir)
MX58Mexican Driving Licence (Licencia de Conducir)
—0Unspecified
—3Internal 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​

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

Responses​

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"
  }
}
FieldTypeDescription
idstring (UUID)Process identifier. Use with Get Process for re-queries.
statusinteger1 (processing), 3 (finished with success), 5 (error).
Possible result values
idCloud.resultMeaningRecommended action
approvedReal person and validated identity.Proceed with the flow.
deniedIdentity not validated, liveness check failed, or extreme risk identified.End the flow or redirect to an alternative flow.
critical-riskCritical risk level identified.End the flow or route to manual review.
high-riskHigh risk level identified.Route to manual review or an alternative flow.
retryInsufficient capture or score to evaluate.Ask the user for a new capture.
inconclusiveNot 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.

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

FieldTypeDescription
unicoId.resultstringyes, no, inconclusive — see Identity Verification.
riskLevel.resultstringapproved, reproved, risk-critical, risk-high, inconclusive — see possible values below or Fraud Risk Classification.
idFace.resultstringFOUND — see Face Identifier.
idFace.personIdstringStable 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.resultstringDeprecated. Use riskLevel instead. Clients with ongoing integrations may continue using it while coordinating the migration with their project team.
government.serprointegerSerpro similarity score (0–100, -1, -2). Available in Brazil only. See Serpro Similarity.
livenessinteger1 (passed), 2 (failed) — see Liveness.
riskLevel.result — possible values
ValueMeaning
approvedIt is the face of the ID holder, and no evidence related to fraud was found.
reprovedRejection is recommended, as multiple fraud indicators were detected.
risk-criticalRejection 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-highRejection is also recommended, but the decision remains yours. High risk indicates that we found at least one strong evidence of fraud.
inconclusiveNo 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.

Error Codes​

CodeMessageDescription
40221This 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.
20900O base64 informado não é válido.The base64 parameter is invalid. Possible causes: it's not an image or it's an injection attempt.
20807A 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.
20532No face detected in image.No face could be detected in the submitted image.
20513The referenced process was not found.The referenceProcessId points to a process that does not exist or is no longer accessible.
20512The referenced process is not available for reuse.The referenced process exists but is not available for reuse.
20509The subject.name field is invalid.subject.name contains invalid characters.
20508The subject.gender field is invalid.subject.gender must be M or F.
20507O parâmetro subject.code é inválido.Non-standard or non-existent CPF.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.Image size exceeds 800 KB; compress to JPEG92.
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.The base64 format is invalid or unsupported.
20065The referenceProcessId field is invalid.The referenceProcessId is not a valid UUID.
20062The useCase field is invalid.Unrecognized value in the useCase field.
20024The 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.
20533The card field is missing.Cardholder Verification: the card object was not provided.
20534The card.bin field is missing.Cardholder Verification: card.bin was not provided.
20535The card.last4 field is missing.Cardholder Verification: card.last4 was not provided.
20536The card data is invalid.Cardholder Verification: the card data was rejected as invalid.
20021The subject.phone field is invalid.subject.phone format is invalid (IDD + area code + number, 13 chars).
20019The subject.birthDate field is invalid.subject.birthDate is outside ISO 8601 format (YYYY-MM-DD).
20009O parâmetro imagebase64 não foi informado.The selfie image parameter is missing.
20008The subject.email field is invalid.Invalid email format in subject.email.
20006O parâmetro subject.name não foi informado.The subject.name parameter is missing.
20005O parâmetro subject.code não foi informado.The subject.code parameter is missing.
20004O parâmetro subject não foi informado.The subject parameter is missing.
20003The request body is missing or invalid.Null or invalid payload.
20002O parâmetro APIKey não foi informado.The APIKEY parameter is missing from the request header.
20001O parâmetro authtoken não foi informado.The integration token parameter is missing from the request header.
10508The JWT with the captured face has already been used.The JWT can only be used once.
10507The JWT with the captured face is expired.JWT expired; must be sent within 10 minutes.
10506The imageBase64 field is not a valid JWT from SDK.The imageBase64 is not a valid JWT generated by the SDK.

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.
Last updated on