Reprocessing and Biometric Base Import

MarkdownChatGPTClaude

This guide covers how to perform reprocessing or biometric base import on the Unico platform. It details the technical and operational requirements for an effective, secure integration following platform best practices.

Scope

This material covers two types of processes:

• Reprocessing: reprocessing biometric records of users who have already been through the client's and Unico's base for re-evaluation or migration between systems.
• Biometric Base Import: initial upload or update of a base containing selfies for identity verification and/or risk classification purposes.
• Document Base Import: upload of a document base alongside selfies for Facematch or CPF Match verification purposes (Brazil only).

Prerequisites

• The client must have an active contract or NDA signed with Unico and be in the integration phase (exception if approved by the governance team).
• The project will follow formal TPS (transactions per second) agreements. See TPS agreement below.
• Before obtaining production credentials, full integration homologation is mandatory to ensure data quality, payload compliance and stable performance.
• A dedicated service account must be created for the reprocessing or import (e.g., "Reprocessing" or "Legacy_Import").
• A dedicated API Key will be created specifically for the reprocessing/import.
• (Optional) A dedicated subsidiary can be created for the reprocessing/import. This parameter is identified in the payload as subsidiaryId. See Payload parameters below.
• The API Key and service account will be deactivated after the agreed period or processing completion.

Available capabilities

Capability	Description
Identity Verification	Verifies whether the submitted selfie belongs to the actual holder of the identifier.
Fraud Risk Classification	Checks for a history of fraudulent behavior associated with that face.
Facematch	Verifies whether the document photo matches the submitted selfie.
CPF Match Brazil only	Verifies whether the provided CPF matches the CPF number printed on the document. Note: not all RGs have the CPF printed.

info

The capabilities listed above are the most commonly used in reprocessing flows. Other capabilities may be enabled depending on the client's needs and the API Key configuration — contact your Unico project manager to discuss the right setup for your use case.

Selfie requirements

• Must be submitted in base64 format.
• The image must follow the ICAO standard (light background, centered face, no accessories that obstruct identification, proper lighting).
• Recommended dimensions: 1080x1920 (portrait) or 1920x1080 (landscape).
• Maximum size: 800 KB (compress with JPEG 92 if needed).
• Orientation: portrait.

Document requirements

• Supported document types: see Document Capture & Reuse — Supported documents.
• Images must include both the front and back of the document, fully visible with no cropping.
• The document must be legible — clear, well-lit, and free of obstructions.

TPS agreement

• The maximum agreed TPS for this project is 10 TPS.
• Distribute requests evenly over time rather than sending them in large bursts.
• This limit must not be exceeded without formal approval from the Unico team.
• Requests above the limit may be automatically dropped or blocked.
• If a temporary increase is needed, a formal prior agreement is required.

Integration

Endpoints

Environment	Base URL	Access	Notes
Staging	https://api.id.uat.unico.app	Open	Mandatory for testing
Production	https://api.id.unico.app	Only after approved homologation	Requires strict TPS control

Required headers

Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json

Payload parameters

{
  "subject": {
    "duiType": 1,
    "code": "11032395702",
    "name": "User Name",
    "email": "[email protected]",
    "phone": "21998571922",
    "birthDate": "30/07/1989",
    "gender": "M"
  },
  "useCase": "Reprocessamento/Importação",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR...",
  "document": {
    "purpose": "Reprocessamento",
    "documentId": "doc-001",
    "files": [
      {
        "data": "doc_base64_frente",
        "faceDocumentMatch": true
      },
      {
        "data": "doc_base64_verso"
      }
    ]
  }
}

Field	Type	Required	Description
subject	object	Yes	User identification data.
subject.duiType	integer	Yes	Document type identifier. See duiType values below.
subject.code	string	Yes	CPF or other user identifier.
subject.name	string	Yes	User's full name.
subject.email	string	No	User's email.
subject.phone	string	No	User's phone number.
subject.birthDate	string	No	User's date of birth (DD/MM/YYYY).
subject.gender	string	No	User's gender (M or F).
useCase	string	Yes	Use case name ("Reprocessamento" or "Importação de base").
subsidiaryId	string	No	Subsidiary UUID (provided by Unico).
imageBase64	base64	Yes	User's selfie image converted to base64.
document	object	No	Document data associated with the process.
document.purpose	string	No	Document purpose (e.g., "Reprocessamento").
document.documentId	string	No	Document identifier.
document.files	array	No	List of document image files.
document.files[].data	base64	No	Document image converted to base64.
document.files[].faceDocumentMatch	boolean	No	Indicates whether the face in the document matches the submitted selfie.

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

Important notes

• The selfie must comply with the ICAO standard with proper quality and lighting.
• The selfie must be in base64 format.
• Avoid bulk submissions without TPS control — this can trigger rate limiting (see Error handling below).
• Always test data and integration in the staging environment first.

Responses

Success — 200 OK

Without document

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "riskLevel": {
    "result": "inconclusive"
  }
}

Field	Type	Description
id	string	Process identifier. Store it for future queries or if you implement 1:1 Validation later.
status	integer	Transaction status.
unicoId.result	string	Identity Verification capability response.
riskLevel.result	string	Fraud Risk Classification result. Possible values: reproved, risk-critical, risk-high, inconclusive.

With document (Facematch)

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "score": 0,
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "faceDocumentMatch": {
    "faceMatch": true
  },
  "riskLevel": {
    "result": "inconclusive"
  }
}

Field	Type	Description
id	string	Process identifier. Store it for future queries or if you implement 1:1 Validation later.
status	integer	Transaction status.
score	number	Facematch score.
unicoId.result	string	Identity Verification capability response.
faceDocumentMatch.faceMatch	boolean	Whether the document photo matches the submitted selfie.
riskLevel.result	string	Fraud Risk Classification result. Possible values: reproved, risk-critical, risk-high, inconclusive.

Image processing error

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

Common errors

Codes in the 4xx range indicate validation errors with the provided data. Codes in the 5xx range indicate server-side failures.

HTTP Code	Error Type	Likely Cause	Recommended Action
400	Bad Request	Invalid payload	Validate structure and content.
401	Unauthorized	Expired or invalid token	Regenerate token.
403	Forbidden	Incorrect API Key or insufficient permissions	Verify credentials.
429	Too Many Requests	Request rate exceeded	Wait and respect TPS limit.
500+	Internal Server Error	Internal failure	Retry after a few seconds; open a ticket if persistent.

Error handling

• Rate Limit (HTTP 429) must be carefully monitored. Request overload can block the pipeline.
• Always respect the TPS agreed with Unico (see TPS agreement).
• For persistent failures (5xx), reprocess with retry/backoff control.