KYC SaaS API

API REST multi-tenant para verificar a identidade dos seus usuários: documento, CPF, biometria facial, liveness, screening e decisão automatizada. O processamento pesado roda de forma assíncrona — você cria a verificação, coleta a selfie por link/QR e acompanha o resultado por polling ou webhook.

Base URL (produção) https://api.pureface.io

Autenticação OAuth2 client_credentials → JWT

Formato JSON · multipart · RFC 3339 (UTC)

Rate limit 120 req/min por tenant

Autenticação

O fluxo recomendado é OAuth2 client_credentials: troque client_id + client_secret por um JWT de curta duração (1h) e envie-o como Bearer em todas as chamadas /v1/*. Não há refresh token — ao expirar (401), basta reautenticar.

1. Obter um token

# Troca a credencial por um JWT
curl -X POST https://api.pureface.io/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"kyc_live_...","client_secret":"..."}'

# 200 OK
{ "access_token": "eyJhbGciOiJIUzI1NiI...", "token_type": "Bearer", "expires_in": 3600 }

2. Chamar a API com o JWT

# Use o token em todas as rotas /v1/*
curl https://api.pureface.io/v1/verifications/<id> \
  -H "Authorization: Bearer <access_token>"

Ciclo de vida da verificação

PENDING PROCESSING AWAITING_FACE PENDING_DECISION APPROVED REJECTED MANUAL_REVIEW

Endpoints

Verificações

POST /v1/auth/token Público

Troca client_id + client_secret por um access_token (JWT).

POST /v1/verifications Bearer

Cria uma verificação com dados do titular + imagem do documento. Retorna id e status PENDING.

GET /v1/verifications/{id} Bearer

Retorna o estado atual e o resultado. Faça polling até um status terminal.

POST /v1/verifications/{id}/face-check Bearer

Gera a sessão de captura facial: capture_url + QR code em PNG base64.

POST /v1/verifications/{id}/erase Bearer

Direito de exclusão (LGPD): anonimiza a PII e remove os binários. Idempotente.

Revalidação facial

POST /v1/verifications/{id}/revalidate Bearer

Re-checa apenas a face (liveness + match) de um cliente já aprovado, sem reenviar documento.

GET /v1/revalidations/{id} Bearer

Consulta o resultado da revalidação (poll até status terminal).

Consumo & faturas

GET /v1/usage Bearer

Consumo agregado no período, por tipo de evento cobrável.

GET /v1/invoices Bearer

Lista suas faturas fechadas. Use /v1/invoices/{id} para o detalhe.

Captura & saúde

GET /s/{token} Sessão

Valida a sessão de captura antes de pedir a câmera.

POST /s/{token}/capture Sessão

Recebe a selfie + frames de liveness e enfileira a análise facial.

GET /healthz Público

Saúde das dependências (PostgreSQL, Redis, MinIO).

Webhooks

Em vez de polling, receba um POST assinado quando a verificação é decidida (evento verification.decided). Cada entrega é assinada com seu hmac_key no header X-KYC-Signature (HMAC-SHA256 do corpo bruto) — sempre valide antes de confiar no payload.

# POST verification.decided · assinado com X-KYC-Signature
{
  "verification_id": "b3f1c2d4-...",
  "outcome": "APPROVED",
  "score": 0.94,
  "risk_score": 0.05,
  "maker_checker_required": false
}

Precisa de credenciais?

Fale com nosso time para provisionar seu tenant e emitir client_id, client_secret e hmac_key.

Fale com nosso time