Onboard through the API

In this guide you’ll read an account’s requirements, resolve the reference data some fields need, submit values and documents, and watch the account move to review. By the end onboarding lives entirely inside your own product. A recipient-only account’s requirements are short: identity and a payout destination, little else. An account that also holds a merchant capability has a longer list, since accepting payments carries its own set of fields. Building this interface once means rendering whichever list a given account actually has, not assuming the short one.

This is a standing commitment. Requirements change as regulation changes, and a new requirement arrives as a field your interface does not render, so accounts stall with nothing visibly wrong. The hosted link picks those changes up on its own.

Before you start

An account with capabilities requested. See Create an account.
An API key with connected_accounts:read and connected_accounts:write.

Steps

Read the account's requirements

Read the account. requirements.entries[] is the field-level view: every outstanding field, its state, and the capabilities it holds up.

curl https://sandbox-api.bachs.io/v1/accounts/acct_3Wq8ZfT1yHnJ5sVe \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

{
  "id": "acct_3Wq8ZfT1yHnJ5sVe",
  "country": "NG",
  "capabilities": {
    "payouts": { "status": "restricted", "requested": true }
  },
  "requirements": {
    "currently_due": ["persons.per_3a91c0d7.first_name", "payout_destination"],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": [],
    "errors": [],
    "entries": [
      {
        "field": "persons.per_3a91c0d7.first_name",
        "status": "currently_due",
        "restricts_capabilities": ["payouts"],
        "resolution": "api",
        "deadline": null,
        "errors": []
      }
    ]
  }
}

Render entries as your form, and use restricts_capabilities to tell the account holder what each remaining field unlocks. See Requirements for every state.Add ?include=requirements.values to read back what has already been submitted. This is useful for prefilling an edit, and for resolving a person index like persons.0 to a name.

Resolve the reference data

Some fields cannot be typed freely. Fetch the valid values first.

curl "https://sandbox-api.bachs.io/v1/reference/banks?country=NG" \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

momo returns mobile money operators the same way. Before you submit a bank account, confirm it resolves to a real account name:

curl -X POST https://sandbox-api.bachs.io/v1/misc/bank-accounts/resolve \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{ "account_number": "0123456789", "bank_code": "058" }'

These are not account-scoped (the NG bank list is the same for every account), so there is no account in the path. country falls back to your own.

Resolving before submission turns a rejected requirement days later into an inline error while the account holder is still on the page.

Hand off the documents

Files are not part of this flow. A document requirement (a person’s identity document, a certificate of incorporation) is collected through an account link: mint one, send the account holder to it, and they upload in the hosted flow. The upload lands against the account and satisfies the requirement without passing through you.

curl -X POST https://sandbox-api.bachs.io/v1/accounts/acct_3Wq8ZfT1yHnJ5sVe/account-links \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "update",
    "refresh_url": "https://yourapp.example/onboarding/refresh",
    "return_url": "https://yourapp.example/onboarding/done"
  }'

Everything else on this page stays server-to-server; only the files need the account holder present. See Hosted onboarding.

Submit

Submitting is an account write: POST /v1/accounts/{account_id} with a fields body, keyed by the same field keys requirements.entries[] returned. Omitting a field leaves it untouched, so you can build up a submission over several calls. But every field you do send is validated together, and if any one of them is rejected the call fails with 400 INVALID_REQUIREMENT_FIELD and none of the fields in it are saved, not even the ones that were fine. Contact details and capability requests in the same call are applied before the fields are validated, so a rejection does not undo them. A field that is only incomplete does not fail the call: it stays outstanding in requirements. See Requirements for the payout_destination shape and its rejection codes.The same call can set contact details and request capabilities, so a form submit is one round trip.

curl -X POST https://sandbox-api.bachs.io/v1/accounts/acct_3Wq8ZfT1yHnJ5sVe \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "persons": [
        {
          "first_name": "Ada",
          "last_name": "Obi",
          "relationship": { "representative": true }
        }
      ],
      "payout_destination": {
        "currency": "NGN",
        "account_number": "0123456789",
        "account_name": "Ada Obi",
        "bank_code": "058"
      }
    }
  }'

{
  "id": "acct_3Wq8ZfT1yHnJ5sVe",
  "requirements": {
    "currently_due": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": ["persons.per_3a91c0d7.name", "payout_destination"],
    "errors": []
  }
}

An empty currently_due does not mean the account is finished. What was submitted sits in pending_verification until it is checked, so read every bucket, not only currently_due, before you tell the account holder there is nothing left to do.

Re-read the account

Submitted fields move to pending_verification, and each entry’s own status can further become pending_review once an automated check hands it to a reviewer. Anything rejected comes back as currently_due with an entry in errors, whose reason is written for display to the account holder. See Requirements for the full state diagram.

What happens next

Once every requirement bucket is empty, a reviewer enables each capability, which arrives as capability.updated. Do not poll for it. See Monitor onboarding.

Errors

Submitting requirement values returns the standard error envelope.

Cause	Resolution
A submitted value is rejected, for example a bank code that is not a real code in the account’s country (`INVALID_REQUIREMENT_FIELD`, 400).	Inspect `errors[]` (each entry has `field`, `message`, and `code`), fix the named fields, and resend the whole `fields` object again. No field from a rejected submission is saved; anything else in the same call (contact details, capability requests, profile changes) was applied before the fields were validated and stays applied. A field that is merely absent or incomplete does not cause this: it comes back as still outstanding in `requirements`.

Get started

Core concepts

Reversals and risk

Onboard an account

Build with Connect

Go live

Onboard through the API

Before you start

Steps

What happens next

Errors

Next steps

​Before you start

​Steps

​What happens next

​Errors

​Next steps

Before you start

Steps

What happens next

Errors

Next steps