Bank accounts
POST /v1/vakis/{key}/bank_accounts
Intended contract
Section titled “Intended contract”{ "bank_name": "Bancolombia", "account_type": "savings", "account_number": "…", "owner_name": "Fundación Ejemplo", "owner_document_type": "NIT", "owner_document_number": "…", "certificate_url": "https://example.org/docs/certificacion-bancaria.pdf", "rut_url": "https://example.org/docs/rut.pdf"}202 Accepted:
{ "id": "ba_01J9Z4M2K7QF3B", "object": "bank_account", "verified": false, "verification": { "status": "pending" }, "created_at": "2026-08-17T14:00:00Z"}It will never return verified: true synchronously
Section titled “It will never return verified: true synchronously”Verification is asynchronous — a risk check plus a review of the banking certificate — and it resolves by webhook. An account is created unverified, every time, without exception.
Design for that: your UI needs a “pending verification” state, and any flow that
pays out to an account must gate on verified: true rather than on the account
existing. This is also why this endpoint is sequenced after webhooks; without them
you would be polling a compliance decision.
Why this is the endpoint we are most careful with
Section titled “Why this is the endpoint we are most careful with”It accepts full bank credentials and national identity data over a partner API key. That means it does not ship until it has field-level encryption at rest, redaction in every log line, its own dedicated permission separate from everything else your key can do, and an audit entry per call — and a security review before exposure, not after.
If you need this sooner than the roadmap allows, tell us the use case. The answer may be a human-assisted flow in the meantime; it will not be an early, unreviewed version of this endpoint.