VALIDO
API

API Reference

Uma API. Qualquer identidade. Verifique programaticamente com uma linha de código.

Autenticação

Inclua a sua chave no header X-API-Key em cada pedido. Obtenha a sua chave no Dashboard.

curl -H "X-API-Key: vld_sua_chave_aqui" https://kycvalido.com/api/v1/wallet/balance

Base URL

https://kycvalido.com/api/v1

Endpoints

Seis endpoints. Tudo o que precisa.

POST/api/v1/verify/existence

Verifica se um BI existe. Rápido. Barato.

Request

{
  "bi_number": "003245678LA045",
  "country": "AO"
}

Response

{
  "success": true,
  "status": "verified",
  "data": { "exists": true, "biNumber": "003245678LA045" },
  "fee_charged": "0.50",
  "verification_id": 42
}
curl -X POST https://kycvalido.com/api/v1/verify/existence \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vld_sua_chave_aqui" \
  -d '{"bi_number": "003245678LA045", "country": "AO"}'
POST/api/v1/verify/full

Identidade completa. Nome, foto, filiação, datas. Tudo.

Request

{
  "bi_number": "003245678LA045",
  "country": "AO"
}

Response

{
  "success": true,
  "status": "verified",
  "data": {
    "biNumber": "003245678LA045",
    "fullName": "ERICKSON MVEZI",
    "dateOfBirth": "1990-02-24",
    "gender": "M",
    "nationality": "Angolana",
    "fatherName": "MVEZI MAZIAMO",
    "motherName": "VERÓNICA MBANZIKILO",
    "placeOfBirth": "Luanda",
    "maritalStatus": "Casado",
    "issueDate": "2020-11-09",
    "expiryDate": "2030-11-09",
    "issuer": "MIGMIN",
    "photoUrl": "https://..."
  },
  "fee_charged": "1.50",
  "verification_id": 43
}
curl -X POST https://kycvalido.com/api/v1/verify/full \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vld_sua_chave_aqui" \
  -d '{"bi_number": "003245678LA045", "country": "AO"}'
POST/api/v1/verify/criminal

Registo criminal. Certificado, estado, validade. Directo da fonte.

Request

{
  "bi_number": "003245678LA045",
  "country": "AO"
}

Response

{
  "success": true,
  "status": "verified",
  "data": {
    "has_criminal_records": false,
    "status": "NO_RECORD_FOUND",
    "description": "Nada consta.",
    "certificate_number": "3001534307",
    "issue_date": "2024-11-19",
    "expiry_date": "2025-02-17",
    "issuing_authority": "MJDH"
  },
  "fee_charged": "2.00",
  "verification_id": 44
}
curl -X POST https://kycvalido.com/api/v1/verify/criminal \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vld_sua_chave_aqui" \
  -d '{"bi_number": "003245678LA045", "country": "AO"}'
POST/api/v1/verify/bundle

Identidade + Criminal. Uma chamada. Um preço. Risk score incluído.

Request

{
  "bi_number": "003245678LA045",
  "country": "AO"
}

Response

{
  "success": true,
  "status": "verified",
  "data": {
    "identity": { "fullName": "ERICKSON MVEZI", "dateOfBirth": "1990-02-24", ... },
    "criminalRecord": { "has_criminal_records": false, "status": "NO_RECORD_FOUND" }
  },
  "risk_score": "low",
  "fee_charged": "3.00",
  "verification_id": 45
}
curl -X POST https://kycvalido.com/api/v1/verify/bundle \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vld_sua_chave_aqui" \
  -d '{"bi_number": "003245678LA045", "country": "AO"}'
GET/api/v1/risk/score?bi_number=...&country=AO

Risk score calculado. Baixo, médio, ou alto. Baseado em identidade + criminal.

Response

{
  "success": true,
  "bi_number": "003245678LA045",
  "risk_score": "low",
  "risk_factors": {
    "identity_verified": true,
    "criminal_record": false,
    "identity_valid": true
  },
  "fee_charged": "3.00"
}
curl https://kycvalido.com/api/v1/risk/score?bi_number=003245678LA045&country=AO \
  -H "X-API-Key: vld_sua_chave_aqui"
GET/api/v1/wallet/balance

Saldo actual. Sempre actualizado.

Response

{
  "balance": "150.00",
  "currency": "USD",
  "alert_threshold": "10.00"
}
curl https://kycvalido.com/api/v1/wallet/balance \
  -H "X-API-Key: vld_sua_chave_aqui"
POST/api/v1/verify/batch

Verificação em lote. Até 1000 BIs por chamada. Assíncrono.

Request

{
  "bi_numbers": ["003245678LA045", "003245679LA046"],
  "country": "AO",
  "endpoint_type": "full"
}

Response (202)

{
  "batch_id": 7,
  "total_rows": 2,
  "estimated_cost": "3.00",
  "status": "processing"
}
curl -X POST https://kycvalido.com/api/v1/verify/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vld_sua_chave_aqui" \
  -d '{"bi_numbers": ["003245678LA045"], "country": "AO", "endpoint_type": "full"}'
GET/api/v1/verify/batch/:id

Estado do lote. Resultados quando pronto.

Response

{
  "batch_id": 7,
  "total_rows": 2,
  "processed_rows": 2,
  "status": "completed",
  "results": [
    { "bi_number": "003245678LA045", "status": "verified", "data": { ... } }
  ]
}
EM BREVE

Webhooks

Notificações em tempo real. Lotes concluídos. Saldos baixos. Tudo via POST com assinatura HMAC.

verification.completedbatch.completedwallet.low_balancewallet.topup

Rate Limiting

60 pedidos por minuto por empresa. Headers de resposta incluem o estado do limite.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1701782400

Exceder o limite retorna 429 Too Many Requests.

Erros

CódigoSignificado
400Bad Request
401Unauthorized
402Payment Required
403Forbidden
429Too Many Requests
500Internal Error

Preços (Angola)

Existência

$0.50

por consulta

Identidade

$1.50

por consulta

Criminal

$2.00

por consulta

Bundle

$3.00

por consulta

Preços configuráveis por país. Dedução automática da carteira.