Provider onboarding

POST /v1/providers

Intended contract

A composite operation: it creates the provider, attaches a bank account, runs a risk check, and returns a case that resolves by webhook.

{
  "legal_name": "Distribuciones Ejemplo S.A.S.",
  "tax_id": "…",
  "country": "CO",
  "contact": { "name": "…", "email": "…", "phone": "+57…" },
  "bank_account": {
    "bank_name": "Bancolombia",
    "account_type": "savings",
    "account_number": "…",
    "owner_name": "Distribuciones Ejemplo S.A.S.",
    "owner_document_type": "NIT",
    "owner_document_number": "…"
  }
}

202 Accepted:

{
  "id": "prv_01J9Z4M2K7QF3B",
  "object": "provider",
  "status": "in_review",
  "checks": {
    "datariesgos": { "status": "pending" },
    "bank_account": { "status": "pending" }
  },
  "created_at": "2026-08-17T14:00:00Z"
}

status: in_review → approved | rejected | manual_review.

What is actually being built

The risk-check integration already exists inside Vaki. What does not exist is a provider as a first-class object — today a supplier is, in effect, a bank account hanging off a cause. Modelling it properly is most of the work, and it is worth doing: “we attach vetted suppliers to causes and pay them from the cause’s funds” is a real operating model, not a feature request.

The endpoint also cannot ship without a decision that is not an engineering one: which risk scores auto-approve, which auto-reject, and which land in a human queue. A published contract with no threshold behind it would be a coin flip with an HTTP interface.