> For the complete documentation index, see [llms.txt](https://tembo.gitbook.io/tembo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tembo.gitbook.io/tembo/merchant-accounts-api/api-reference/allocate-account.md).

# Allocate Account

### Endpoint

```
POST /account/allocate
```

### Request

#### **Headers**

* **`Content-Type`**<mark style="color:red;">\*</mark> — Must be `application/json`
* **`Authorization`**<mark style="color:red;">\*</mark> — Bearer token (`Bearer YOUR_API_TOKEN`)
* **`x-request-id`**<mark style="color:red;">\*</mark> — Unique UUID per request for tracing

#### **Body Parameters**

* **`merchantName`**<mark style="color:red;">\*</mark> *(string)* —The merchant’s registered legal name. This field must not be empty.
* **`merchantReference`**<mark style="color:red;">\*</mark> *(string)* — A unique identifier assigned to the merchant by the partner. Along with the `accountNo`, it is included in webhook notifications as an additional identifier, helping the partner determine which merchant a payment belongs to.
* **`tag`**<mark style="color:red;">\*</mark>*(string)* — Identifies the pool of accounts from which an account should be allocated. Check below for more details.

{% hint style="info" %}
Accounts are limited and are made available in predefined pools. Each pool is associated with a specific tag. When requesting an account, the supplied tag determines which pool TemboPlus should use.

For example, a partner managing two merchants could organize the accounts as follows:

* `merchant-a` tag → accounts reserved for Merchant A
* `merchant-b` tag → accounts reserved for Merchant B

This allows the partner to separate and manage account availability for each merchant.
{% endhint %}

### Responses

<details>

<summary><code>201</code> OK</summary>

#### **Response Format:**

```json
{
  "id": "e8820cc4-a2e1-444c-9f48-ef2f77367e3f",
  "accountName": "TEMBOPLUS COMPANY LIMITED",
  "accountNo": "XXXXXXXXXX",
  "bankId": "ECOBANK",
  "bankName": "ECOBANK TANZANIA",
  "swiftCode": "ECOCTZTZ",
  "tag": "TM"
}
```

#### **Response Fields:**

* **`id`** *(string)* — Unique UUID for the allocated collection account
* **`accountName`** *(string)* — Registered name associated with the collection account
* **`accountNo`** *(string)* — Bank account number assigned for payment collection
* **`bankId`** *(string)* — Short bank identifier
* **`bankName`** *(string)* — Bank name
* **`swiftCode`** *(string)* — SWIFT/BIC code of the bank
* **`tag`** *(string)* — Tag associated with the account

</details>

<details>

<summary><code>400</code> BAD REQUEST</summary>

This error occurs when the request contains missing or invalid parameters. The API validates all required fields and data formats before processing your request.

#### **Common Causes:**

* `merchantName` field is empty or missing
* Required fields like `merchantReference` are not provided
* Invalid JSON syntax in the request body
* Missing `Content-Type: application/json` header

#### **Error Format:**

```json
{
  "merchantName": "\"merchantName\" cannot be empty"
}
```

Or with detailed validation information:

```json
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Validation Error",
  "details": {
    "merchantName": "\"merchantName\" is required"
  }
}
```

#### **Resolution**

Verify all required fields (`merchantName`, `merchantReference`) are included and properly formatted before sending the request.

</details>

<details>

<summary><code>401</code> UNAUTHORIZED</summary>

This error indicates authentication failure. The API could not verify your identity using the provided credentials.

#### **Common Causes:**

* Missing `Authorization` header in the request
* Invalid bearer token format (should be `Bearer YOUR_TOKEN`)
* Expired or revoked API token
* Incorrect API token value

#### **Error Format**

```json
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Invalid or missing authentication token"
}
```

#### **Resolution**

Ensure your request includes the correct authorization header:\
`Authorization: Bearer YOUR_API_TOKEN`&#x20;

</details>

<details>

<summary><code>409</code> CONFLICT</summary>

This error occurs when the request conflicts with the current state of a resource or violates system constraints.

***

#### Duplicate Merchant Reference

You're attempting to use a reference that has already been used for another account allocation. Each reference must be unique across all your account allocations.

**Error Format**

```json
{
  "message": "DUPLICATE_MERCHANT_REFERENCE",
  "error": "Conflict",
  "statusCode": 409
}
```

**Resolution**\
Generate a new unique reference and retry the request.

***

#### No Available Accounts

There are currently no bank accounts available in the selected account pool.

**Why this happens**

* The account pool for this tag has been exhausted. A new account cannot be allocated until additional accounts are added to the pool.

**Error Format**

```json
{
  "message": "NO_AVAILABLE_ACCOUNTS",
  "error": "Conflict",
  "statusCode": 409
}
```

**Immediate Action Required**\
Contact [**operations@temboplus.com**](mailto:operations@temboplus.com) to request additional accounts be added to your pool. Include your expected usage volume.

**For Planning**\
Monitor your account usage regularly and request pool expansions before running out to avoid service interruptions.

</details>

<details>

<summary><code>500</code> INTERNAL SERVER ERROR</summary>

This error indicates a temporary server-side issue that prevented the request from being processed. These are typically transient problems that resolve automatically.

#### **Common causes:**

* Temporary banking system connectivity issues
* Server maintenance or updates in progress
* Third-party service temporary unavailability

#### **Error format**

```json
{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Something went wrong"
}
```

#### **Resolution:**

* Wait 1-2 minutes and retry the request
* Contact support with your `x-request-id` if the issue persists beyond 10 minutes

**Note:** These errors are usually temporary and resolve within a few minutes.

</details>