Authentication
Send X-API-Key from your backend. Never expose the key in a browser. The .invalid address is illustrative; obtain your authorized API base from the Portal.
POST /v1/face-auth/transactions
Criar transacao
Cria uma transacao no tenant e ambiente resolvidos pela API key. Envie somente os campos documentados nesta especificacao. Use Idempotency-Key para repetir a mesma criacao sem duplicar a transacao.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| false |
Body / responses
{
"requestBody": {
"content": {
"application/json": {
"examples": {
"complete": {
"summary": "Payload completo",
"value": {
"callback_url": "https://customer.example.invalid/webhooks/kyc",
"country_code": "BR",
"expires_in_minutes": 10080,
"external_id": "docs-example-0001",
"locale": "pt-BR",
"metadata": {
"branch": "SAO-01",
"order_id": "pedido-123"
},
"source": {
"channel": "callcenter",
"integration": "onboarding-digital",
"system": "CRM"
},
"subject": {
"email": "person@example.invalid",
"identity": {
"country": "BR",
"number": "00000000000",
"type": "CPF"
},
"name": "Pessoa de exemplo / Example person",
"phone": "+5500000000000",
"tenant_subject_id": "subject_docs_example"
}
}
},
"minimal": {
"summary": "Payload minimo",
"value": {
"country_code": "BR",
"external_id": "docs-example-0001",
"locale": "pt-BR",
"subject": {
"identity": {
"country": "BR",
"number": "00000000000",
"type": "CPF"
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/TransactionCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"approved": {
"summary": "Fluxo aprovado",
"value": {
"accepted_evidence_documents": [
"CIN",
"CNH",
"RG"
],
"canonical_url": "https://journey.example.invalid/demo/0001",
"configuration_snapshot": {
"captured_at": "2026-06-18T12:00:00Z",
"default_transaction_ttl_minutes": 10080,
"docmatch_threshold": 85,
"document_capture_max_attempts": 3,
"document_expiration_policy": "reject_expired",
"environment": "prod",
"liveness_max_attempts": 10,
"liveness_threshold": 80,
"location_capture_mode": "required",
"manual_review_ttl_hours": 720,
"snapshot_quality": "complete"
},
"country_code": "BR",
"created_at": "2026-06-18T12:00:00Z",
"created_by": null,
"created_by_type": "api_key",
"current_step": "done",
"decision": "approved",
"decision_reason": "document_match_and_identity_backing_passed",
"document_required": true,
"document_requirement": {
"reason": "missing_trusted_identity_backing",
"required": true,
"trusted_document_id": null,
"trusted_identity_backing_id": null,
"valid_until": null
},
"environment": "prod",
"expires_at": "2026-06-25T12:00:00Z",
"external_id": "docs-example-0001",
"links": {
"short_url": "https://short.example.invalid/demo0001",
"webview_url": "https://journey.example.invalid/demo/0001"
},
"locale": "pt-BR",
"location_captured_at": null,
"metadata": {
"branch": "SAO-01",
"order_id": "pedido-123"
},
"origin": "api",
"result": {
"document_expiration_status": "unknown",
"document_match_similarity": 96.7,
"document_match_status": "passed",
"evidence_document_type": null,
"liveness_score": 98.4,
"liveness_status": "passed",
"trusted_identity_backing_created": false
},
"short_code": "demo0001",
"short_url": "https://short.example.invalid/demo0001",
"source": {
"channel": "callcenter",
"integration": "onboarding-digital",
"system": "CRM"
},
"status": "approved",
"subject": {
"email": "person@example.invalid",
"identity": {
"country": "BR",
"number": "00000000000",
"type": "CPF"
},
"name": "Pessoa de exemplo / Example person",
"phone": "+5500000000000",
"tenant_subject_id": "subject_docs_example"
},
"tenant_id": "tenant_docs_example",
"tenant_subject_id": "subject_docs_example",
"terms_accepted_at": null,
"terms_version": "BR-pt-BR-v1",
"transaction_id": "00000000-0000-4000-8000-000000000001",
"updated_at": "2026-06-18T12:10:22Z",
"webhook_delivery": {
"attempts": 0,
"last_error": null,
"last_event_id": "evt_docs_9b7a4a04ceacc0f2",
"last_event_type": "approved",
"status": "pending",
"updated_at": "2026-06-18T12:10:22Z"
},
"webhook_events": [
{
"attempts": 0,
"callback_configured": true,
"created_at": "2026-06-18T12:00:00Z",
"delivered_at": null,
"event_id": "evt_docs_9b7a4a04ceacc0f2",
"event_type": "approved",
"failed_at": null,
"last_error": null,
"last_http_status": null,
"max_attempts": 5,
"published_at": null,
"status": "pending",
"transaction_id": "00000000-0000-4000-8000-000000000001",
"updated_at": "2026-06-18T12:10:22Z"
}
],
"webview_url": "https://journey.example.invalid/demo/0001"
}
},
"created": {
"summary": "Transacao criada",
"value": {
"accepted_evidence_documents": [
"CIN",
"CNH",
"RG"
],
"canonical_url": "https://journey.example.invalid/demo/0001",
"configuration_snapshot": {
"captured_at": "2026-06-18T12:00:00Z",
"default_transaction_ttl_minutes": 10080,
"docmatch_threshold": 85,
"document_capture_max_attempts": 3,
"document_expiration_policy": "reject_expired",
"environment": "prod",
"liveness_max_attempts": 10,
"liveness_threshold": 80,
"location_capture_mode": "required",
"manual_review_ttl_hours": 720,
"snapshot_quality": "complete"
},
"country_code": "BR",
"created_at": "2026-06-18T12:00:00Z",
"created_by": null,
"created_by_type": "api_key",
"current_step": "terms",
"decision": "pending",
"decision_reason": null,
"document_required": true,
"document_requirement": {
"reason": "missing_trusted_identity_backing",
"required": true,
"trusted_document_id": null,
"trusted_identity_backing_id": null,
"valid_until": null
},
"environment": "prod",
"expires_at": "2026-06-25T12:00:00Z",
"external_id": "docs-example-0001",
"links": {
"short_url": "https://short.example.invalid/demo0001",
"webview_url": "https://journey.example.invalid/demo/0001"
},
"locale": "pt-BR",
"location_captured_at": null,
"metadata": {
"branch": "SAO-01",
"order_id": "pedido-123"
},
"origin": "api",
"result": {
"document_expiration_status": "unknown",
"document_match_similarity": null,
"document_match_status": "not_started",
"evidence_document_type": null,
"liveness_score": null,
"liveness_status": "not_started",
"trusted_identity_backing_created": false
},
"short_code": "demo0001",
"short_url": "https://short.example.invalid/demo0001",
"source": {
"channel": "callcenter",
"integration": "onboarding-digital",
"system": "CRM"
},
"status": "created",
"subject": {
"email": "person@example.invalid",
"identity": {
"country": "BR",
"number": "00000000000",
"type": "CPF"
},
"name": "Pessoa de exemplo / Example person",
"phone": "+5500000000000",
"tenant_subject_id": "subject_docs_example"
},
"tenant_id": "tenant_docs_example",
"tenant_subject_id": "subject_docs_example",
"terms_accepted_at": null,
"terms_version": "BR-pt-BR-v1",
"transaction_id": "00000000-0000-4000-8000-000000000001",
"updated_at": "2026-06-18T12:00:00Z",
"webhook_delivery": {
"attempts": 0,
"last_error": null,
"last_event_id": "evt_docs_9b7a4a04ceacc0f2",
"last_event_type": "transaction.created",
"status": "pending",
"updated_at": "2026-06-18T12:00:00Z"
},
"webhook_events": [
{
"attempts": 0,
"callback_configured": true,
"created_at": "2026-06-18T12:00:00Z",
"delivered_at": null,
"event_id": "evt_docs_9b7a4a04ceacc0f2",
"event_type": "transaction.created",
"failed_at": null,
"last_error": null,
"last_http_status": null,
"max_attempts": 5,
"published_at": null,
"status": "pending",
"transaction_id": "00000000-0000-4000-8000-000000000001",
"updated_at": "2026-06-18T12:00:00Z"
}
],
"webview_url": "https://journey.example.invalid/demo/0001"
}
}
},
"schema": {
"$ref": "#/components/schemas/TenantTransactionResponse"
}
}
},
"description": "Transacao criada ou recuperada por idempotencia."
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"403": {
"$ref": "#/components/responses/TenantEnvironmentDisabled"
},
"409": {
"$ref": "#/components/responses/IdempotencyConflict"
}
}
}GET /v1/face-auth/transactions/{transaction_id}
Consultar transacao
Retorna a visao tenant-safe da transacao. A API key precisa pertencer ao mesmo tenant e ao mesmo ambiente da transacao.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
transaction_id | path | true | Identificador oficial retornado no POST. |
Body / responses
{
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"approved": {
"summary": "Fluxo aprovado",
"value": {
"accepted_evidence_documents": [
"CIN",
"CNH",
"RG"
],
"canonical_url": "https://journey.example.invalid/demo/0001",
"configuration_snapshot": {
"captured_at": "2026-06-18T12:00:00Z",
"default_transaction_ttl_minutes": 10080,
"docmatch_threshold": 85,
"document_capture_max_attempts": 3,
"document_expiration_policy": "reject_expired",
"environment": "prod",
"liveness_max_attempts": 10,
"liveness_threshold": 80,
"location_capture_mode": "required",
"manual_review_ttl_hours": 720,
"snapshot_quality": "complete"
},
"country_code": "BR",
"created_at": "2026-06-18T12:00:00Z",
"created_by": null,
"created_by_type": "api_key",
"current_step": "done",
"decision": "approved",
"decision_reason": "document_match_and_identity_backing_passed",
"document_required": true,
"document_requirement": {
"reason": "missing_trusted_identity_backing",
"required": true,
"trusted_document_id": null,
"trusted_identity_backing_id": null,
"valid_until": null
},
"environment": "prod",
"expires_at": "2026-06-25T12:00:00Z",
"external_id": "docs-example-0001",
"links": {
"short_url": "https://short.example.invalid/demo0001",
"webview_url": "https://journey.example.invalid/demo/0001"
},
"locale": "pt-BR",
"location_captured_at": null,
"metadata": {
"branch": "SAO-01",
"order_id": "pedido-123"
},
"origin": "api",
"result": {
"document_expiration_status": "unknown",
"document_match_similarity": 96.7,
"document_match_status": "passed",
"evidence_document_type": null,
"liveness_score": 98.4,
"liveness_status": "passed",
"trusted_identity_backing_created": false
},
"short_code": "demo0001",
"short_url": "https://short.example.invalid/demo0001",
"source": {
"channel": "callcenter",
"integration": "onboarding-digital",
"system": "CRM"
},
"status": "approved",
"subject": {
"email": "person@example.invalid",
"identity": {
"country": "BR",
"number": "00000000000",
"type": "CPF"
},
"name": "Pessoa de exemplo / Example person",
"phone": "+5500000000000",
"tenant_subject_id": "subject_docs_example"
},
"tenant_id": "tenant_docs_example",
"tenant_subject_id": "subject_docs_example",
"terms_accepted_at": null,
"terms_version": "BR-pt-BR-v1",
"transaction_id": "00000000-0000-4000-8000-000000000001",
"updated_at": "2026-06-18T12:10:22Z",
"webhook_delivery": {
"attempts": 0,
"last_error": null,
"last_event_id": "evt_docs_9b7a4a04ceacc0f2",
"last_event_type": "approved",
"status": "pending",
"updated_at": "2026-06-18T12:10:22Z"
},
"webhook_events": [
{
"attempts": 0,
"callback_configured": true,
"created_at": "2026-06-18T12:00:00Z",
"delivered_at": null,
"event_id": "evt_docs_9b7a4a04ceacc0f2",
"event_type": "approved",
"failed_at": null,
"last_error": null,
"last_http_status": null,
"max_attempts": 5,
"published_at": null,
"status": "pending",
"transaction_id": "00000000-0000-4000-8000-000000000001",
"updated_at": "2026-06-18T12:10:22Z"
}
],
"webview_url": "https://journey.example.invalid/demo/0001"
}
},
"pending": {
"summary": "Fluxo pendente",
"value": {
"accepted_evidence_documents": [
"CIN",
"CNH",
"RG"
],
"canonical_url": "https://journey.example.invalid/demo/0001",
"configuration_snapshot": {
"captured_at": "2026-06-18T12:00:00Z",
"default_transaction_ttl_minutes": 10080,
"docmatch_threshold": 85,
"document_capture_max_attempts": 3,
"document_expiration_policy": "reject_expired",
"environment": "prod",
"liveness_max_attempts": 10,
"liveness_threshold": 80,
"location_capture_mode": "required",
"manual_review_ttl_hours": 720,
"snapshot_quality": "complete"
},
"country_code": "BR",
"created_at": "2026-06-18T12:00:00Z",
"created_by": null,
"created_by_type": "api_key",
"current_step": "terms",
"decision": "pending",
"decision_reason": null,
"document_required": true,
"document_requirement": {
"reason": "missing_trusted_identity_backing",
"required": true,
"trusted_document_id": null,
"trusted_identity_backing_id": null,
"valid_until": null
},
"environment": "prod",
"expires_at": "2026-06-25T12:00:00Z",
"external_id": "docs-example-0001",
"links": {
"short_url": "https://short.example.invalid/demo0001",
"webview_url": "https://journey.example.invalid/demo/0001"
},
"locale": "pt-BR",
"location_captured_at": null,
"metadata": {
"branch": "SAO-01",
"order_id": "pedido-123"
},
"origin": "api",
"result": {
"document_expiration_status": "unknown",
"document_match_similarity": null,
"document_match_status": "not_started",
"evidence_document_type": null,
"liveness_score": null,
"liveness_status": "not_started",
"trusted_identity_backing_created": false
},
"short_code": "demo0001",
"short_url": "https://short.example.invalid/demo0001",
"source": {
"channel": "callcenter",
"integration": "onboarding-digital",
"system": "CRM"
},
"status": "created",
"subject": {
"email": "person@example.invalid",
"identity": {
"country": "BR",
"number": "00000000000",
"type": "CPF"
},
"name": "Pessoa de exemplo / Example person",
"phone": "+5500000000000",
"tenant_subject_id": "subject_docs_example"
},
"tenant_id": "tenant_docs_example",
"tenant_subject_id": "subject_docs_example",
"terms_accepted_at": null,
"terms_version": "BR-pt-BR-v1",
"transaction_id": "00000000-0000-4000-8000-000000000001",
"updated_at": "2026-06-18T12:00:00Z",
"webhook_delivery": {
"attempts": 0,
"last_error": null,
"last_event_id": "evt_docs_9b7a4a04ceacc0f2",
"last_event_type": "transaction.created",
"status": "pending",
"updated_at": "2026-06-18T12:00:00Z"
},
"webhook_events": [
{
"attempts": 0,
"callback_configured": true,
"created_at": "2026-06-18T12:00:00Z",
"delivered_at": null,
"event_id": "evt_docs_9b7a4a04ceacc0f2",
"event_type": "transaction.created",
"failed_at": null,
"last_error": null,
"last_http_status": null,
"max_attempts": 5,
"published_at": null,
"status": "pending",
"transaction_id": "00000000-0000-4000-8000-000000000001",
"updated_at": "2026-06-18T12:00:00Z"
}
],
"webview_url": "https://journey.example.invalid/demo/0001"
}
}
},
"schema": {
"$ref": "#/components/schemas/TenantTransactionResponse"
}
}
},
"description": "Transacao encontrada."
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"403": {
"$ref": "#/components/responses/TenantEnvironmentDisabled"
},
"404": {
"$ref": "#/components/responses/TransactionNotFound"
}
}
}GET /v1/face-auth/transactions/{transaction_id}/assets
Listar assets da transacao
Lista assets operacionais tenant-safe: liveness_reference, document_front, document_back e document_full. Exige API key com permissao document_download e IP autorizado para document_download.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
transaction_id | path | true |
Body / responses
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TransactionAssetsResponse"
}
}
},
"description": "Assets encontrados."
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"403": {
"$ref": "#/components/responses/ForbiddenExternalAccess"
},
"404": {
"$ref": "#/components/responses/TransactionNotFound"
}
}
}GET /v1/face-auth/transactions/{transaction_id}/assets/{asset_id}/content
Baixar asset da transacao
Baixa o conteudo binario de um asset operacional tenant-safe. Exige API key e IP com permissao document_download.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
transaction_id | path | true | |
asset_id | path | true |
Body / responses
{
"responses": {
"200": {
"content": {
"application/octet-stream": {
"schema": {
"format": "binary",
"type": "string"
}
}
},
"description": "Conteudo binario do asset."
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"403": {
"$ref": "#/components/responses/ForbiddenExternalAccess"
},
"404": {
"$ref": "#/components/responses/TransactionNotFound"
}
}
}GET /v1/face-auth/transactions/{transaction_id}/documents/download
Evidência restrita ao Admin interno — indisponível na API Tenant
Esta rota não disponibiliza ZIP/PDF para integrações Tenant. Mesmo com chave válida, escopo document_download e IP autorizado, retorna HTTP 403 evidence_access_restricted. Não solicite permissões adicionais nem repita a chamada para tentar liberar a evidência. A existência da rota não concede acesso a evidências internas.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
transaction_id | path | true |
Body / responses
{
"responses": {
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": {
"code": "evidence_access_restricted",
"message": "evidence access is restricted to internal admin"
}
},
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Evidence access is restricted to internal admin, including for authorized Tenant API keys."
},
"404": {
"$ref": "#/components/responses/TransactionNotFound"
}
}
}GET /v1/face-auth/transactions/{transaction_id}/evidence.pdf
Evidência restrita ao Admin interno — indisponível na API Tenant
Esta rota não disponibiliza ZIP/PDF para integrações Tenant. Mesmo com chave válida, escopo document_download e IP autorizado, retorna HTTP 403 evidence_access_restricted. Não solicite permissões adicionais nem repita a chamada para tentar liberar a evidência. A existência da rota não concede acesso a evidências internas.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
transaction_id | path | true |
Body / responses
{
"responses": {
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": {
"code": "evidence_access_restricted",
"message": "evidence access is restricted to internal admin"
}
},
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Evidence access is restricted to internal admin, including for authorized Tenant API keys."
},
"404": {
"$ref": "#/components/responses/TransactionNotFound"
}
}
}Contract schemas
BiometricAsset
{
"properties": {
"asset_id": {
"type": "string"
},
"asset_kind": {
"enum": [
"liveness_reference",
"document_front",
"document_back",
"document_full"
],
"type": "string"
},
"content_type": {
"nullable": true,
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"download_url": {
"description": "Use /v1/face-auth/transactions/{transaction_id}/assets/{asset_id}/content.",
"type": "string"
},
"size_bytes": {
"nullable": true,
"type": "integer"
},
"tenant_id": {
"type": "string"
},
"transaction_id": {
"nullable": true,
"type": "string"
}
},
"required": [
"asset_id",
"tenant_id",
"transaction_id",
"asset_kind",
"content_type",
"created_at"
],
"type": "object"
}BlacklistSearchAttemptSummary
{
"properties": {
"best_similarity": {
"nullable": true,
"type": "number"
},
"blacklist_search_attempt_id": {
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"environment": {
"enum": [
"hml",
"prod"
],
"type": "string"
},
"kind": {
"enum": [
"identity",
"face"
],
"type": "string"
},
"status": {
"enum": [
"skipped",
"no_match",
"matched",
"failed"
],
"type": "string"
},
"tenant_id": {
"type": "string"
},
"threshold": {
"nullable": true,
"type": "number"
},
"transaction_id": {
"type": "string"
}
},
"required": [
"blacklist_search_attempt_id",
"tenant_id",
"transaction_id",
"environment",
"kind",
"status",
"created_at"
],
"type": "object"
}DocumentExtractionSummary
{
"description": "Resumo operacional tenant-safe da extracao documental, sem OCR bruto, provider, payloads ou identificadores forenses.",
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"declared_document_type": {
"nullable": true,
"type": "string"
},
"detected_document_type": {
"nullable": true,
"type": "string"
},
"document_capture_id": {
"type": "string"
},
"document_expiration_status": {
"nullable": true,
"type": "string"
},
"document_expires_at": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"document_side": {
"enum": [
"front",
"back",
"combined"
],
"nullable": true,
"type": "string"
},
"document_type_confidence": {
"nullable": true,
"type": "number"
},
"document_type_evidence_status": {
"nullable": true,
"type": "string"
},
"environment": {
"enum": [
"hml",
"prod"
],
"type": "string"
},
"tenant_id": {
"type": "string"
},
"transaction_id": {
"type": "string"
}
},
"required": [
"document_capture_id",
"transaction_id",
"tenant_id",
"environment",
"created_at"
],
"type": "object"
}DocumentRequirement
{
"properties": {
"reason": {
"type": "string"
},
"required": {
"type": "boolean"
},
"trusted_document_id": {
"nullable": true,
"type": "string"
},
"trusted_identity_backing_id": {
"nullable": true,
"type": "string"
},
"valid_until": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
}ErrorDetail
{
"properties": {
"code": {
"enum": [
"validation_error",
"invalid_api_key",
"tenant_environment_disabled",
"transaction_not_found",
"idempotency_conflict",
"tenant_ip_not_authorized",
"api_key_scope_not_allowed",
"evidence_access_restricted"
],
"type": "string"
},
"errors": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
}ErrorResponse
{
"properties": {
"detail": {
"$ref": "#/components/schemas/ErrorDetail"
}
},
"required": [
"detail"
],
"type": "object"
}ManualReviewSummary
{
"properties": {
"case_id": {
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"decided_at": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"decision": {
"enum": [
"pending",
"approved",
"rejected"
],
"type": "string"
},
"decision_reason": {
"nullable": true,
"type": "string"
},
"reason": {
"type": "string"
},
"status": {
"enum": [
"pending",
"approved",
"rejected",
"expired"
],
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"case_id",
"status",
"reason",
"decision",
"created_at",
"updated_at"
],
"type": "object"
}Subject
{
"properties": {
"email": {
"maxLength": 254,
"nullable": true,
"type": "string"
},
"identity": {
"$ref": "#/components/schemas/SubjectIdentity"
},
"name": {
"maxLength": 160,
"nullable": true,
"type": "string"
},
"phone": {
"maxLength": 40,
"nullable": true,
"type": "string"
},
"tenant_subject_id": {
"description": "ID persistente do cliente dentro do tenant.",
"maxLength": 128,
"nullable": true,
"type": "string"
}
},
"required": [
"identity"
],
"type": "object"
}SubjectIdentity
{
"properties": {
"country": {
"enum": [
"AR",
"BO",
"BR",
"CL",
"CO",
"CR",
"CU",
"DO",
"EC",
"SV",
"GT",
"HT",
"HN",
"MX",
"NI",
"PA",
"PE",
"PY",
"UY",
"US",
"VE"
],
"type": "string"
},
"number": {
"maxLength": 80,
"minLength": 1,
"type": "string"
},
"type": {
"example": "CPF",
"maxLength": 40,
"minLength": 1,
"type": "string"
}
},
"required": [
"type",
"number",
"country"
],
"type": "object"
}TenantTransactionConfigurationSnapshot
{
"properties": {
"captured_at": {
"format": "date-time",
"type": "string"
},
"default_transaction_ttl_minutes": {
"type": "integer"
},
"docmatch_threshold": {
"type": "number"
},
"document_capture_max_attempts": {
"type": "integer"
},
"document_expiration_policy": {
"enum": [
"reject_expired",
"allow_expired"
],
"type": "string"
},
"environment": {
"enum": [
"hml",
"prod"
],
"type": "string"
},
"liveness_max_attempts": {
"type": "integer"
},
"liveness_threshold": {
"type": "number"
},
"location_capture_mode": {
"enum": [
"disabled",
"optional",
"required"
],
"type": "string"
},
"manual_review_ttl_hours": {
"type": "integer"
},
"snapshot_quality": {
"type": "string"
}
},
"type": "object"
}TenantTransactionLinks
{
"properties": {
"short_url": {
"format": "uri",
"nullable": true,
"type": "string"
},
"webview_url": {
"format": "uri",
"nullable": true,
"type": "string"
}
},
"type": "object"
}TenantTransactionResponse
{
"description": "Resposta tenant-safe da transacao para integracao diaria.",
"properties": {
"accepted_evidence_documents": {
"items": {
"type": "string"
},
"type": "array"
},
"canonical_url": {
"format": "uri",
"nullable": true,
"type": "string"
},
"configuration_snapshot": {
"oneOf": [
{
"$ref": "#/components/schemas/TenantTransactionConfigurationSnapshot"
},
{
"type": "null"
}
]
},
"country_code": {
"enum": [
"AR",
"BO",
"BR",
"CL",
"CO",
"CR",
"CU",
"DO",
"EC",
"SV",
"GT",
"HT",
"HN",
"MX",
"NI",
"PA",
"PE",
"PY",
"UY",
"US",
"VE"
],
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"created_by": {
"nullable": true,
"type": "string"
},
"created_by_type": {
"enum": [
"api_key",
"tenant_user",
"internal_admin",
"system"
],
"type": "string"
},
"current_step": {
"enum": [
"terms",
"liveness",
"document",
"done"
],
"type": "string"
},
"decision": {
"enum": [
"pending",
"approved",
"rejected"
],
"type": "string"
},
"decision_reason": {
"nullable": true,
"type": "string"
},
"document_required": {
"type": "boolean"
},
"document_requirement": {
"$ref": "#/components/schemas/DocumentRequirement"
},
"environment": {
"enum": [
"hml",
"prod"
],
"type": "string"
},
"expires_at": {
"format": "date-time",
"type": "string"
},
"external_id": {
"nullable": true,
"type": "string"
},
"links": {
"$ref": "#/components/schemas/TenantTransactionLinks"
},
"locale": {
"enum": [
"pt-BR",
"es",
"es-AR",
"es-BO",
"es-CL",
"es-CO",
"es-CR",
"es-CU",
"es-DO",
"es-EC",
"es-SV",
"es-GT",
"es-HN",
"es-MX",
"es-NI",
"es-PA",
"es-PE",
"es-PY",
"es-UY",
"es-VE",
"fr-HT",
"en-US"
],
"type": "string"
},
"location_captured_at": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"manual_review": {
"description": "Resumo tenant-safe quando a transacao foi enviada para mesa manual.",
"oneOf": [
{
"$ref": "#/components/schemas/ManualReviewSummary"
},
{
"type": "null"
}
]
},
"metadata": {
"additionalProperties": true,
"type": "object"
},
"origin": {
"enum": [
"api",
"tenant_portal",
"internal_admin"
],
"type": "string"
},
"result": {
"$ref": "#/components/schemas/TenantTransactionResult"
},
"short_code": {
"nullable": true,
"type": "string"
},
"short_url": {
"format": "uri",
"nullable": true,
"type": "string"
},
"source": {
"$ref": "#/components/schemas/TransactionSource"
},
"status": {
"enum": [
"created",
"terms_accepted",
"liveness_pending",
"liveness_passed",
"document_pending",
"document_passed",
"manual_review_pending",
"approved",
"rejected",
"expired"
],
"type": "string"
},
"subject": {
"$ref": "#/components/schemas/TenantTransactionSubject"
},
"tenant_id": {
"description": "Tenant resolvido pela API key.",
"type": "string"
},
"tenant_subject_id": {
"nullable": true,
"type": "string"
},
"terms_accepted_at": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"terms_version": {
"type": "string"
},
"transaction_id": {
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
},
"webhook_delivery": {
"$ref": "#/components/schemas/TenantWebhookDeliveryStatus"
},
"webhook_events": {
"items": {
"$ref": "#/components/schemas/TenantWebhookEvent"
},
"type": "array"
},
"webview_url": {
"format": "uri",
"nullable": true,
"type": "string"
}
},
"required": [
"transaction_id",
"tenant_id",
"environment",
"country_code",
"locale",
"origin",
"source",
"subject",
"links",
"status",
"current_step",
"decision",
"terms_version",
"metadata",
"document_required",
"document_requirement",
"accepted_evidence_documents",
"created_at",
"updated_at",
"expires_at",
"result",
"webhook_delivery",
"webhook_events"
],
"type": "object"
}TenantTransactionResult
{
"properties": {
"document_expiration_status": {
"enum": [
"unknown",
"not_extracted",
"valid",
"expired"
],
"nullable": true,
"type": "string"
},
"document_match_similarity": {
"nullable": true,
"type": "number"
},
"document_match_status": {
"type": "string"
},
"evidence_document_type": {
"nullable": true,
"type": "string"
},
"liveness_score": {
"nullable": true,
"type": "number"
},
"liveness_status": {
"type": "string"
},
"trusted_identity_backing_created": {
"type": "boolean"
}
},
"type": "object"
}TenantTransactionSubject
{
"properties": {
"email": {
"nullable": true,
"type": "string"
},
"identity": {
"oneOf": [
{
"$ref": "#/components/schemas/SubjectIdentity"
},
{
"type": "null"
}
]
},
"name": {
"nullable": true,
"type": "string"
},
"phone": {
"nullable": true,
"type": "string"
},
"tenant_subject_id": {
"nullable": true,
"type": "string"
}
},
"type": "object"
}TenantWebhookDeliveryStatus
{
"properties": {
"attempts": {
"type": "integer"
},
"last_error": {
"nullable": true,
"type": "string"
},
"last_event_id": {
"nullable": true,
"type": "string"
},
"last_event_type": {
"nullable": true,
"type": "string"
},
"status": {
"type": "string"
},
"updated_at": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
}TenantWebhookEvent
{
"properties": {
"attempts": {
"type": "integer"
},
"callback_configured": {
"type": "boolean"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"delivered_at": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"event_id": {
"type": "string"
},
"event_type": {
"enum": [
"transaction.created",
"terms_accepted",
"location_captured",
"handoff_created",
"handoff_opened",
"handoff_completed",
"handoff_expired",
"liveness_session_created",
"liveness_passed",
"liveness_failed",
"document_uploaded",
"document_passed",
"document_failed",
"manual_review_required",
"approved",
"rejected",
"expired"
],
"type": "string"
},
"failed_at": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"last_error": {
"nullable": true,
"type": "string"
},
"last_http_status": {
"nullable": true,
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"published_at": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"enum": [
"pending",
"queued",
"delivering",
"delivered",
"retry_pending",
"failed",
"skipped_no_callback"
],
"type": "string"
},
"transaction_id": {
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
}TransactionAssetsResponse
{
"properties": {
"assets": {
"items": {
"$ref": "#/components/schemas/BiometricAsset"
},
"type": "array"
},
"blacklist_search_attempts": {
"items": {
"$ref": "#/components/schemas/BlacklistSearchAttemptSummary"
},
"type": "array"
},
"document_captures": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"document_extractions": {
"items": {
"$ref": "#/components/schemas/DocumentExtractionSummary"
},
"type": "array"
},
"face_search_attempts": {
"items": {
"type": "object"
},
"type": "array"
},
"liveness_sessions": {
"items": {
"type": "object"
},
"type": "array"
},
"location_capture_events": {
"items": {
"type": "object"
},
"type": "array"
}
},
"required": [
"assets",
"document_captures"
],
"type": "object"
}TransactionCreate
{
"properties": {
"callback_url": {
"description": "Webhook especifico da transacao. Se ausente, usa o webhook configurado no tenant.",
"format": "uri",
"nullable": true,
"type": "string"
},
"country_code": {
"default": "BR",
"enum": [
"AR",
"BO",
"BR",
"CL",
"CO",
"CR",
"CU",
"DO",
"EC",
"SV",
"GT",
"HT",
"HN",
"MX",
"NI",
"PA",
"PE",
"PY",
"UY",
"US",
"VE"
],
"type": "string"
},
"expires_in_minutes": {
"description": "TTL customizado; ausente usa o padrao do tenant.",
"maximum": 129600,
"minimum": 5,
"nullable": true,
"type": "integer"
},
"external_id": {
"description": "ID do processo no sistema do tenant.",
"maxLength": 128,
"type": "string"
},
"locale": {
"enum": [
"pt-BR",
"es",
"es-AR",
"es-BO",
"es-CL",
"es-CO",
"es-CR",
"es-CU",
"es-DO",
"es-EC",
"es-SV",
"es-GT",
"es-HN",
"es-MX",
"es-NI",
"es-PA",
"es-PE",
"es-PY",
"es-UY",
"es-VE",
"fr-HT",
"en-US"
],
"nullable": true,
"type": "string"
},
"metadata": {
"additionalProperties": true,
"default": {},
"description": "JSON livre tenant-safe, maximo 8KB.",
"type": "object"
},
"source": {
"$ref": "#/components/schemas/TransactionSource"
},
"subject": {
"$ref": "#/components/schemas/Subject"
}
},
"required": [
"country_code",
"subject"
],
"type": "object"
}TransactionSource
{
"properties": {
"channel": {
"maxLength": 80,
"nullable": true,
"type": "string"
},
"integration": {
"maxLength": 120,
"nullable": true,
"type": "string"
},
"system": {
"maxLength": 80,
"nullable": true,
"type": "string"
}
},
"type": "object"
}WebhookPayload
{
"description": "Payload enviado ao callback_url da transacao ou webhook do tenant. Validar usando X-Face-Auth-Timestamp e X-Face-Auth-Signature.",
"properties": {
"api_version": {
"const": "v1",
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"event_id": {
"type": "string"
},
"event_type": {
"enum": [
"transaction.created",
"terms_accepted",
"location_captured",
"handoff_created",
"handoff_opened",
"handoff_completed",
"handoff_expired",
"liveness_session_created",
"liveness_passed",
"liveness_failed",
"document_uploaded",
"document_passed",
"document_failed",
"manual_review_required",
"approved",
"rejected",
"expired"
],
"type": "string"
},
"transaction": {
"$ref": "#/components/schemas/TenantTransactionResponse"
}
},
"required": [
"api_version",
"event_id",
"event_type",
"created_at",
"transaction"
],
"type": "object"
}Creation examples
# Server-side only. Configure KYC_API_BASE_URL with your authorized base (https://api.example.invalid is illustrative), and KYC_API_KEY privately. Never expose credentials in browser code.
set -eu
: "${KYC_API_BASE_URL:?Set authorized base}" "${KYC_API_KEY:?Set API key}"
: "${KYC_IDEMPOTENCY_KEY:?Persist the key for this creation intent}"
curl --fail-with-body --max-time 15 --request POST \
"${KYC_API_BASE_URL%/}/v1/face-auth/transactions" \
--header "X-API-Key: ${KYC_API_KEY}" \
--header "Idempotency-Key: ${KYC_IDEMPOTENCY_KEY}" \
--header 'Content-Type: application/json' \
--data-binary '{"country_code":"BR","external_id":"docs-example-0001","locale":"pt-BR","subject":{"identity":{"country":"BR","number":"00000000000","type":"CPF"}}}'
# Persist transaction_id and business correlation; use the returned links.webview_url. Read status, decision and decision_reason together. Reuse the SAME idempotency key AND original payload only for the same creation intent; never silently bypass a 409 conflict.