Overview
Choosing a contract
The choice of contract is a consequence of where the biometric capture happens — not an independent decision. Use the table below as a guide.
| Contract | Use when… | Capture | Flow |
|---|---|---|---|
| Web & SDK | The capture journey is hosted by Unico (Web iFrame, Redirect, or native SDK) | Unico controls | Process is created before capture → user goes through the journey → result returns via callback or polling |
| API | Your application controls capture (with or without the Unico SDK) and sends the image directly in the call | Client controls | Image is sent together with process creation → result returns synchronously |
Hosts and environments
| Contract | Sandbox host | Production host |
|---|---|---|
| Web & SDK | https://api.idcloud.uat.unico.app | https://api.idcloud.unico.app |
| API | https://api.id.uat.unico.app | https://api.id.unico.app |
| OAuth2 / Token | https://identityhomolog.acesso.io | https://identity.acesso.io |
Full details in Environments.
Authentication
All Unico contracts use Bearer token (JWT) obtained via OAuth2 with urn:ietf:params:oauth:grant-type:jwt-bearer.
Full details in Authentication.
Payload differences across contracts
The same conceptual operation ("create an identity verification process") looks different in each contract. Use the tables below as a quick reference when migrating between integrations.
Process creation
| Aspect | Web & SDK | API |
|---|---|---|
| Endpoint | POST /client/v1/process | POST /processes/v1 |
| Auth | Authorization: Bearer <jwt> | Authorization: Bearer <jwt> + APIKEY |
| Image | Not sent (captured by Unico's journey) | Sent as imageBase64 |
| User identification | person.duiType + person.duiValue | subject.code (CPF / CURP) |
| Document types | CPF, CURP, SSN, NIN, DNI, NIK | CPF, CURP only |
| Pipeline definition | flow (enum, 30+ values) | Implicit in APIKEY (capabilities) |
| Callback | callbackUri (user redirect) | None (synchronous) |
| Webhook | Webhook v1 (final result) | Webhook v1 (optional) |
| Returns journey URL | Yes (userRedirectUrl) | No |
| Result | Async (GET poll or webhook) | Synchronous (in the response) |
| SDK token | Yes (token, webAppToken) | No |
Result retrieval
| Aspect | Web & SDK | API |
|---|---|---|
| Endpoint | GET /client/v1/process/\{id\} | GET /processes/v1/\{id\} (also in creation response) |
| Status | state + result (prefixed enums) | status (1, 3, 5) |
| Result structure | Nested under process.authenticationInfo.{capability}Result | Flat: unicoId, liveness, government, identityFraudsters |
| Document | services[].documents[] (RG/CNH with OCR) | Separate endpoint (GET /processes/v1/\{id\}/document) |
What's next
- Authentication — OAuth2 flow and JWT generation
- Environments — sandbox vs production
- Postman Collection — ready-to-use collections
- Webhooks and Events — async result delivery
- SDKs and Tools — Web SDK, Android, iOS, Flutter