> For the complete documentation index, see [llms.txt](https://docs.biti.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biti.so/guides-1/bulk-send.md).

# bulk send

Send up to 100 payments in one batch from your Payout Wallet: payroll, supplier payments, prizes. Call [`get-payout-methods`](file:///sirihduSQLZLwiPgqdx7/a80ff537-2a32-4162-a9ef-8994fddaca6c/api-reference/bulk-send.md#post-partnerv1get-payout-methods) first. The live mobile money method today is EVC Plus (`evcplus`). More methods appear in the list when Biti turns them on.

## The payroll example

```json
{
  "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET",
  "reference": "PAYROLL-2026-11", "currency": "USD",
  "label": "Salary November", "sms": "{app}: {amount} salary sent to you, ref {ref}",
  "items": [
    { "ref": "emp-001", "method": "evcplus", "number": "+252615551234", "amount": 450.00, "name": "Hodan Ali", "note": "Grade 3" },
    { "ref": "emp-002", "method": "biti", "number": "619990631@biti", "amount": 520.00, "name": "Omar Nur" },
    { "ref": "sup-014", "method": "merchant", "number": "M-0B6D012214AB", "amount": 1200.00, "label": "Invoice 88", "sms": "Invoice 88 paid: {amount}" }
  ]
}
```

## Steps

{% stepper %}
{% step %}

### Get a quote

Call [`quote-bulk-send`](file:///sirihduSQLZLwiPgqdx7/a80ff537-2a32-4162-a9ef-8994fddaca6c/api-reference/bulk-send.md#post-partnerv1quote-bulk-send) first. It moves no money. It returns the fees, whether you can afford the batch and whether it needs approval.
{% endstep %}

{% step %}

### Create the batch

Call [`create-bulk-send`](file:///sirihduSQLZLwiPgqdx7/a80ff537-2a32-4162-a9ef-8994fddaca6c/api-reference/bulk-send.md#post-partnerv1create-bulk-send). The whole batch is refused if your Payout Wallet cannot cover the total plus all fees. Nothing is stored. Every number is checked before any money moves.
{% endstep %}

{% step %}

### Pay fees

You pay the fees. Each receiver gets the exact `amount`.
{% endstep %}

{% step %}

### Wait for approval when required

A total above 1000 in the batch currency gets the status `awaiting_approval`. Nothing moves until Biti approves the batch.
{% endstep %}

{% step %}

### Track item processing

`biti` and `merchant` items are paid at once. Mobile money items are paid by a background job. If the provider refuses, the money returns to your Payout Wallet and the item is `failed`. If the provider does not answer, the item stays `processing` until Biti settles it.
{% endstep %}

{% step %}

### Read progress

Read progress with [`get-bulk-send-status`](file:///sirihduSQLZLwiPgqdx7/a80ff537-2a32-4162-a9ef-8994fddaca6c/api-reference/bulk-send.md#post-partnerv1get-bulk-send-status).
{% endstep %}

{% step %}

### Receive webhooks

You get `payout.done` or `payout.failed` for each item, then `bulk.completed`.
{% endstep %}
{% endstepper %}

## Status values

| Level | Values                                                   |
| ----- | -------------------------------------------------------- |
| Item  | `queued`, `processing`, `done`, `failed`                 |
| Batch | `awaiting_approval`, `processing`, `completed`, `failed` |

## Item text fields

| Field   | Seen by                        | Rules                                                            |
| ------- | ------------------------------ | ---------------------------------------------------------------- |
| `label` | Receiver, as the History title | Up to 40 characters. Falls back to the batch label.              |
| `sms`   | Receiver, by SMS               | Up to 160 characters. Sent after the item is done.               |
| `note`  | You and Biti staff only        | Up to 500 characters. In the status, the statement and webhooks. |

{% hint style="info" %}
An item `ref` is paid once. Send the batch again with the same `reference` after a network error.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.biti.so/guides-1/bulk-send.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
