> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bachs.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Money is always a decimal string at the currency's precision (for example "29.00"), paired with an ISO 4217 currency field. Never use minor units.
> Build against the sandbox first: base URL https://sandbox-api.bachs.io with sk_sandbox_ keys. Production is https://api.bachs.io with sk_live_ keys; going live is a key swap.
> Treat webhooks (for example collection.succeeded) as the source of truth for fulfilment, never client-side events or redirects.
> Subscriptions are created by completing a checkout for a recurring product. There is no direct create-subscription endpoint.
> IDs carry resource prefixes (cust_, prod_, sub_, chk_, inv_, ref_) and timestamps are ISO 8601 UTC.

# Requirements

> The information an account provides before its capabilities go live, and why each piece is asked.

**Requirements** are what an account provides before a [capability](https://docs.bachs.io/connect/capabilities.md) goes live. Each capability requires certain fields, and the capability stays off until those fields are provided and pass their checks.

They are computed on every read from what the account's capabilities require against what has been accepted, so they change when you request a capability or when a document is rejected. They resolve by country and entity type: changing either recomputes the whole set.

***

## What an account owes

An account owes only what the capabilities you ask for need. Ask for less, and the person behind it gives less. Each row below adds to the rows above it.

**A person** (`entity_type: "individual"`):

| You ask for | The person gives |
| - | - |
| `payouts`, `transfers` | Name, email, street address, and a payout account in their own name |
| `virtual_accounts`, `conversions` | Also date of birth, phone, address and national ID number. In Nigeria, a BVN, checked against the national register |
| `bank_transfer`, `ngn_card_collection`, `crypto` | First, a selfie video check of their face and ID. Also their occupation and source of funds. In Nigeria, a NIN as well as the BVN |
| `card_collection` | Also a link where we can see what they sell (a social media page is fine) and a short description of it. Outside Nigeria, a tax ID |

We never ask a person for a website, product category or support email.

**A company** (`entity_type: "company"`):

| You ask for | The company gives |
| - | - |
| `payouts`, `transfers` | Its registered legal name, and a payout account in that name |
| `virtual_accounts`, or any way of taking payments except `mobile_money` | Registration number and certificate, registered address, tax ID, and a line on what it does. Its representative, every director, and every owner above the country's share (below), each with name, date of birth and ID number. When it takes payments, the representative also does the selfie video check |
| `card_collection` | Also the representative's ID document, and a link and description of what the company sells |

**Owners we ask about, by country.** Directors are always asked. Owners are asked when they own at least this share, or more than it where it says "over".

| Country | Owners asked |
| - | - |
| Nigeria | over 5% |
| Ghana | 20% |
| Kenya | over 10% |
| Tanzania | 5% |
| South Africa | 5% |
| Côte d'Ivoire | over 25% |
| Cameroon | 25% |
| Egypt | 25% |

In Cameroon, a person who only gets paid out also gives their date of birth, phone and ID number.

The list for `mobile_money` has not changed. Read the account's `requirements` for what it asks.

> [!TIP]
>
> Name every capability you need when you create the account. If you name none, the account is asked for everything its configuration allows.

***

## Where to read them

They live on the account object. `GET /v1/accounts/{account_id}` returns the `requirements` block on every read.

| What | Returns | Use it for |
| - | - | - |
| `requirements` | Four arrays of field keys, plus `errors` and `current_deadline` | A status badge |
| `requirements.entries[]` | Every outstanding field, its status, what it blocks, who can act on it, its deadline, and why it is asked | Building an onboarding interface |
| `?include=requirements.values` | What has been submitted so far, plus a per-person rollup | Prefilling an edit, or a review screen |

All take scope `connected_accounts:read`.

`entries[]` is the one to build a form from when an account holds more than one capability: a flat bucket cannot say that one field blocks `payouts` while another blocks nothing the account has asked for.

***

## Field states

Each entry in `requirements.entries[]` carries a `status`, naming the bucket it is listed under.

| Status | Meaning |
| - | - |
| `currently_due` | Required now. |
| `eventually_due` | Required later, once a threshold or stage is reached. |
| `past_due` | Was required by a date that has passed. |
| `pending_verification` | Provided, and being checked, either automatically or by a reviewer. |

Only outstanding fields become entries. A field that has been provided and accepted is not listed at all, so an empty `entries` means nothing is outstanding. A field awaiting a reviewer is reported as `pending_verification` rather than a status of its own: to a platform, both mean the same thing, which is that the field is with us and re-sending it achieves nothing.

`provided` says whether a value was submitted. A `currently_due` field with `provided: true` was rejected; with `provided: false` it was never filled in. A rejected field carries `error_reason`, written for display to the account holder.

The field key names what the entry is about. `company.*` and `business_profile.*` are the account itself, `persons.per_3a91c0d7.*` a specific person. Read that person at [`/persons/{person_id}`](https://docs.bachs.io/connect/accounts#persons).

![A field becomes required as eventually\_due or currently\_due, moves to past\_due when its deadline passes, to pending\_verification when submitted, then leaves the list once accepted or returns to currently\_due if rejected or if re-verification is required.](https://mintcdn.com/bachs/i6oZIjTXeiFip_9g/images/connect/field-states-light.svg?fit=max\&auto=format\&n=i6oZIjTXeiFip_9g\&q=85\&s=92d8c41661f8b0655ae3bc69848b63a1)

***

## What a field blocks

Each entry carries `restricts_capabilities`, the capabilities that stay off while it is outstanding. An empty array means no capability the account has asked for needs this field.

Read it per entry rather than counting the buckets: an account holding two capabilities can have one fully satisfied while the other is blocked by a single field, which a flat list cannot express.

> [!WARNING]
>
> Nothing outstanding does not mean a capability is on. Gate on the capability's `status` being `active`. See [Capabilities](https://docs.bachs.io/connect/capabilities.md).

***

## Who can act, and by when

Each entry carries a `resolution`.

| Value | Meaning |
| - | - |
| `api` | Yours to supply. Write it through the account update or the persons subresource. |
| `review` | Already provided and sitting with us. Re-sending it achieves nothing; wait for `account.updated`. |

A field with a deadline carries it as `deadline`, and the account's `requirements.current_deadline` is the soonest one across everything outstanding, enough to drive a banner without walking every entry. Both are `null` when no deadline has been set.

***

## Why a field is asked

Each entry carries a `reason`. Show it to the person, so they know why we ask.

| `reason` | Means |
| - | - |
| `law` | The rules in the account's country ask for it. |
| `partner` | A payment partner needs it to move money that way. |

If no law and no partner asks for something, we do not ask for it.

> [!NOTE]
>
> This is not the same as `errors[].reason`, which is a sentence saying why a value was rejected.

***

## When an account is already live

If you ask for a new capability on a live account and it now owes more, the new fields show as `eventually_due`. They do not appear in `restricts_capabilities`, and nothing the account already has is switched off because of them.

***

## The account roll-up

The account object carries a smaller block for a status badge:

```json theme={"dark"}
{
  "currently_due": ["company.registration_number"],
  "eventually_due": [],
  "past_due": [],
  "pending_verification": ["persons.per_3a91c0d7.id_document"],
  "current_deadline": "2026-09-01T00:00:00Z",
  "errors": [
    {
      "field": "persons.per_3a91c0d7.id_document",
      "code": "unreadable",
      "reason": "The document image was too blurry to read."
    }
  ]
}
```

These are field keys, not objects. `errors` carries a field that was provided and then rejected, as distinct from one that is missing.

***

## Submitting

`POST /v1/accounts/{account_id}` · scope `connected_accounts:write`

`fields` is keyed by the field keys the requirements name: `persons`, `company.*`, `business_profile.*`, `payout_destination`. A submission that omits a field leaves it untouched, so you can save an account holder's progress as they fill in a form. But every field you *do* send is validated together, and if any one of them is invalid the submission is refused: none of the fields in that call are saved, not even the ones that were fine. There is no partial save of a rejected submission. Retry with only the corrected fields, or the whole `fields` object again once it is fixed.

This applies to every field class in the payload, not only `payout_destination`: an invalid `company.structure` or a malformed entry in `persons[]` in the same call also refuses the whole submission.

A field that is merely **incomplete** (one you have started but not finished, so a required sub-field is still absent) is not a rejection. The call succeeds and the requirement stays in `currently_due` until you send the rest. You still see it in `errors[]` with the code `required`, alongside any field that was actually rejected.

The refusal covers the `fields` object, not the rest of the request. Contact details, capability requests, profile changes and an entity-type change sent in the same call are applied *before* the fields are validated, and a rejected submission does not undo them. A call that mixes them is not atomic: if the fields are refused, retry the fields; the rest already took effect.

Requirement values ride on the account write, so the same call can set contact details and request capabilities. See [Update an account](https://docs.bachs.io/connect/accounts.md#update-an-account).

The response is the account, with its recomputed `requirements` block.

> [!TIP]
>
> Bank codes and mobile money operators live under `/v1/reference/`, with no account in the path, because the NG bank list is the same for every account. Resolving an account number to its holder's name is an operation rather than a lookup, so it sits at `POST /v1/misc/bank-accounts/resolve`. It allows 20 calls a minute, since each one reaches the banking network and answers about a real account. See [Onboard through the API](https://docs.bachs.io/connect/guides/api-onboarding.md).

### The `persons` shape

`persons` is an array. Each entry is one human, identified across calls by the `persons.<person_id>` prefix its requirements carry once created. Submit a person by including it in the array; omit a field to leave it untouched, so a form can save as it is filled.

| Field | Type | Notes |
| - | - | - |
| `first_name` | string | |
| `last_name` | string | |
| `dob` | string | Date of birth as `YYYY-MM-DD`. |
| `email` | string | |
| `phone` | string | E.164, e.g. `+2348012345678`. |
| `address` | object | `{ line1, city, state, country }`, plus optional `postal_code`. `country` is the 2-letter ISO code. |
| `id_numbers` | array | The identifiers this person holds. Each entry is `{ type, value, issuing_country }`, where `type` names the scheme (`nin`, `passport`, `id_card`, `drivers_license`, `residence_permit`, `bvn`, `tax_id`) and `issuing_country` is the 2-letter ISO code of who issued it. A person can hold several at once: a Nigerian merchant typically sends a `nin` and, once asked, a `bvn`. `nin` and `bvn` are Nigeria-specific; the rest are universal. |
| `relationship` | object | Who this person is to the account: `{ "representative": true }`, and any of `owner`, `director` (booleans), `percent_ownership` (number), `title` (string). The person opening the account is the `representative`. |

```json theme={"dark"}
{
  "fields": {
    "persons": [
      {
        "first_name": "Ada",
        "last_name": "Obi",
        "dob": "1995-06-15",
        "email": "ada@example.com",
        "phone": "+2348012345678",
        "address": {
          "line1": "12 Marina Road",
          "city": "Lagos",
          "state": "Lagos",
          "postal_code": "101001",
          "country": "NG"
        },
        "id_numbers": [
          { "type": "nin", "value": "12345678901", "issuing_country": "NG" }
        ],
        "relationship": { "representative": true }
      }
    ]
  }
}
```

Add a BVN (or any further identifier) as another entry in the same list. It sits **beside** the primary ID rather than replacing it, because a NIN identifies a citizen and a BVN a bank customer, and a reviewer may need both:

```json theme={"dark"}
"id_numbers": [
  { "type": "nin", "value": "12345678901", "issuing_country": "NG" },
  { "type": "bvn", "value": "22345678901", "issuing_country": "NG" }
]
```

A person's requirements (`persons.<id>.name`, `.dob`, `.id_number`, `.nin`, `.bvn`, `.tax_id`, `.identity_check`, …) come from the capabilities the account asks for. See [What an account owes](#what-an-account-owes). The `id_number` requirement is satisfied by any entry in `id_numbers` that is not a BVN or a tax ID. Add a NIN, BVN or tax ID as another entry in the list. Fields that belong to the representative only count once the person has `relationship.representative: true`.

`persons.<id>.identity_check` is the selfie video check. You cannot do it through the API: the person does it on their phone. Send them a hosted link for it. See [Onboarding](https://docs.bachs.io/connect/onboarding.md#the-selfie-video-check).

### The `profile` shape

A person who takes payments (`bank_transfer`, `ngn_card_collection`, `crypto`, `card_collection`) tells us what they do and where their money comes from.

| Field | Type | Notes |
| - | - | - |
| `occupation` | string | What they do, in a few words. |
| `source_of_funds` | string | Where the money they take in comes from, in a few words. |

```json theme={"dark"}
{
  "fields": {
    "profile": {
      "occupation": "Fashion designer",
      "source_of_funds": "Sales of handmade clothes"
    }
  }
}
```

### The `business_profile` shape

An account that takes card payments in USD (`card_collection`) shows us what it sells. Our card partner asks for both fields. No other capability asks for them.

| Field | Type | Notes |
| - | - | - |
| `url` | string | A link where we can see what the account sells. A website or a social media page is fine. |
| `product_description` | string | What the account sells, in a sentence or two. |

```json theme={"dark"}
{
  "fields": {
    "business_profile": {
      "url": "https://instagram.com/adastores",
      "product_description": "Handmade leather bags and belts"
    }
  }
}
```

### Company fields

A registered business (`entity_type: "company"`) also owes `company.*` fields: registration number, structure, and country-specific filings. `company.structure` is an enum whose valid values, and which documents each structure owes, depend on the country; read them from `GET /v1/reference/business-structures`. An individual account (`entity_type: "individual"`) owes none of these.

### Documents (`id_document`, company filings)

A document requirement (a person's `id_document`, a company's certificate of incorporation) is a **file**, not a value, so it is uploaded separately and then referenced. It cannot be sent inline in the `fields` object.

**1. Upload the file**

`POST /v1/files` (multipart), with the bytes and a `purpose` that says what the file is for:

* `identity_document`: a person's government ID or address evidence.
* `account_requirement`: a company filing or supporting evidence.

Send `X-Account-Id` set to the connected account the file is for. A file belongs to the account it was uploaded for, so a file uploaded without the header belongs to your platform account and cannot be attached to a connected account. The attach step then returns `404 NOT_FOUND` with `Attachment not found`.

```bash theme={"dark"}
curl -X POST https://sandbox-api.bachs.io/v1/files \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "X-Account-Id: acct_3Wq8ZfT1yHnJ5sVe" \
  -F "purpose=identity_document" \
  -F "file=@id-front.jpg"
```

The response returns the file `id`. JPEG, PNG and PDF are accepted, up to 10 MB. A PDF identity document is fine.

**2. Attach it**

Attach the uploaded file to the slot it satisfies, passing the file `id` from the previous step as `file`. A **person's** identity document attaches to that person: `POST /v1/accounts/{account_id}/persons/{person_id}/documents` with the file `id` and the document slot. See [Verify an account's identity](https://docs.bachs.io/connect/guides/identity-verification.md). A **company** filing attaches to the account: `POST /v1/accounts/{account_id}/documents`, naming the company document slot.

Documents cannot go through a hosted onboarding link's automatic flow either: whether you onboard by API or by link, the file itself is uploaded through `POST /v1/files`.

### The `payout_destination` shape

`payout_destination` is a tagged union: `type` picks the rail, and the rest of the object is whichever fields that rail needs.

| `type` | Required fields |
| - | - |
| `bank_account` | `account_number`, `account_name`, plus `bank_code` (or the legacy `routing_number`/`bank_name` aliases) |
| `mobile_money` | `phone_number`, `mobile_provider` |
| `crypto_wallet` | `asset`, `wallet_address` |

`currency` is required alongside them (a legacy submission that omits it is inferred from the account's country instead). The currency and destination type must have a configured payout provider.

Local bank destinations in NGN, GHS, KES, TZS and UGX and mobile money destinations in GHS, KES and TZS have configured routes. Payouts are available to all Bachs users; the account still needs to complete its requirements and have a usable destination. See [Payout currencies and methods](https://docs.bachs.io/guides/payouts/global-payouts.md). For stablecoin destinations, use an asset code from the [supported payout networks](https://docs.bachs.io/for-you/supported-currencies.md#withdrawals).

> [!NOTE]
>
> The inline `payout_destination` requirement field does not accept banks that need international routing schemes, such as GBP, EUR, USD and CAD destinations. Add those through `POST /v1/payouts/destinations` with the appropriate routing details. See the [payout destination reference](https://docs.bachs.io/api-reference/payout-destinations/object.md). This is a separate submission path; adding a destination does not replace the account's other onboarding requirements or activate its capabilities.

A bank account's `bank_code` and a mobile money submission's `mobile_provider` are also checked against the account's own country: a Ghanaian account cannot name a Nigerian bank, and vice versa.

**The bank account must be in the account's own name.** We ask the bank for the name on the account and compare it with the person's name, or with a company's registered legal name.

* **The names match**, for example "ADA OKAFOR" for Ada Okafor: the destination is saved. Words like Limited, Ltd and Nig are ignored for companies.
* **Some words match**, for example "Okafor Ventures" for Ada Okafor: the destination is saved, and our team checks it.
* **No words match**: the destination is refused and nothing is saved. You get `INVALID_REQUIREMENT_FIELD` with code `account_name_mismatch`.

Only Nigerian banks return a name today, so other destinations are not compared. The check does not run in the sandbox.

### When a submission is rejected

A rejected requirement-field write can return `400` with `error_code: "INVALID_REQUIREMENT_FIELD"` and an `errors` array. For example, a GBP bank destination is rejected through this inline field because it needs routing details supplied through the payout-destination API. Read the returned field and message before choosing another submission path.

| `code` | Meaning |
| - | - |
| `currency_required` | No `currency` was sent and the account's country has no default settlement currency to fall back to. |
| `currency_not_supported` | The currency has no configured payout provider (or none for the resolved rail). |
| `type_required` | The currency is served by more than one rail, so `type` must be stated rather than inferred. |
| `bank_code_unknown` | `bank_code` is not a bank in the account's country. |
| `mobile_provider_unknown` | `mobile_provider` is not a mobile money provider in the account's country. |
| `asset_not_supported` | `asset` on a `crypto_wallet` is not a supported crypto asset. |
| `account_name_mismatch` | The bank's name for the account shares no words with the person's name, or the company's registered name. Add an account in the account's own name. |
| `required` | A required sub-field for the resolved `type` was not sent. This one does not fail the write: the destination is incomplete rather than rejected, and stays outstanding. |
| `invalid` | Any other shape problem. |

See [Errors](https://docs.bachs.io/errors.md) for the error envelope and [Error Reference](https://docs.bachs.io/api-reference/error-reference.md) for every `error_code`.

**When a check fails.** A failed selfie video check or BVN check is not a refused write. It shows in the account's `requirements.errors`, on `persons.<id>.identity_check` or `persons.<id>.bvn`, with a `reason` you can show the person. A failed selfie video check has code `identity_check_failed`, or a more specific code. To let the person try again, send them a selfie check link. See [Onboarding](https://docs.bachs.io/connect/onboarding.md#the-selfie-video-check).

```json theme={"dark"}
"errors": [
  {
    "field": "persons.per_3a91c0d7.identity_check",
    "code": "identity_check_failed",
    "reason": "The face in the video did not match the photo on the ID."
  }
]
```

***

## Related

* [Onboarding](https://docs.bachs.io/connect/onboarding.md)
* [Capabilities](https://docs.bachs.io/connect/capabilities.md)
* [Onboard through the API](https://docs.bachs.io/connect/guides/api-onboarding.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.