> For the complete documentation index, see [llms.txt](https://api-docs.flagstoneim.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.flagstoneim.com/apis/instruction-batches.md).

# Instruction Batches

**What it is:** The Instruction Batches API provides visibility into the daily settlement cycle.

It exposes the batches we create each bank working day as we group instructions for processing and payment.

**How it works:** We group instructions into batches by type (deposit or withdrawal) and currency.

Each batch moves through a lifecycle: `Open` (accepting instructions) → `Locked` (finalised, ready for settlement) → `Closed` (payment confirmed) → `Completed` (fully settled).

You poll batches daily, verify totals, and update the status to `Closed` to trigger payment.

**Base URL:** `https://api.sandbox.flagstoneim.com/instruction-batches`

***

## 📋 Endpoints

| Method | Path                                                                | Description                               |
| ------ | ------------------------------------------------------------------- | ----------------------------------------- |
| `GET`  | `/`                                                                 | List instruction batches for a given date |
| `GET`  | `/{instructionBatchId}/instruction-summary/{instructionFilterType}` | Get instruction summaries within a batch  |
| `GET`  | `/{id}/references`                                                  | Get instruction references for a batch    |
| `POST` | `/batch-update`                                                     | Update the status of one or more batches  |

***

## 📄 1. List Instruction Batches

**What it is:** Returns all instruction batches for a given date, grouped by instruction type and currency.

**How it works:** Supply a `batchDate` query parameter.

The response contains batches with their current status, total amounts, and instruction type.

```http
GET /?batchDate=2024-04-20
cdpapi-Subscription-Key: your-api-key-here
```

| Parameter   | In    | Type     | Required | Description                      |
| ----------- | ----- | -------- | -------- | -------------------------------- |
| `batchDate` | query | DateTime | Yes      | The date to retrieve batches for |

**Response** (200 OK):

```json
{
  "instructionBatches": [
    {
      "instructionType": "deposit",
      "instructionBatchTotalAmount": 300.15,
      "instructionBatchId": "50",
      "instructionBatchStatus": "open",
      "currencyCode": "GBP"
    },
    {
      "instructionType": "withdrawal",
      "instructionBatchTotalAmount": 96.15,
      "instructionBatchId": "49",
      "instructionBatchStatus": "open",
      "currencyCode": "GBP"
    },
    {
      "instructionType": "deposit",
      "instructionBatchTotalAmount": 96472.15,
      "instructionBatchId": "48",
      "instructionBatchStatus": "locked",
      "currencyCode": "GBP"
    }
  ]
}
```

### Batch Fields

| Field                               | Type               | Description                                                       |
| ----------------------------------- | ------------------ | ----------------------------------------------------------------- |
| `instructionBatchId`                | string             | Unique identifier for the batch                                   |
| `instructionType`                   | string             | The type of instructions in the batch (`deposit` or `withdrawal`) |
| `instructionBatchTotalAmount`       | number             | Total monetary value of all instructions in the batch             |
| `instructionBatchTotalNoticeAmount` | number             | Total value of notice-period withdrawal instructions              |
| `instructionBatchStatus`            | string             | Current batch status (see lifecycle below)                        |
| `currencyCode`                      | string             | Three-letter currency code (ISO-4217)                             |
| `dateToBeActioned`                  | string (date-time) | The date the batch will be actioned                               |

### Batch Status Lifecycle

| Status      | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| `Open`      | Batch is accepting instructions for the current processing day    |
| `Locked`    | We've finalised the batch - no more instructions will be added    |
| `Closed`    | You've confirmed the batch and triggered payment                  |
| `Completed` | Settlement is complete and we've fully processed the instructions |

***

## 📝 2. Get Instruction Summaries

**What it is:** Returns a paginated list of instruction summaries within a specific batch.

**How it works:** Specify the batch ID and a filter type (`All` or `Closure`) to retrieve summarised instruction data including amounts and action dates.

```http
GET /{instructionBatchId}/instruction-summary/{instructionFilterType}?pageNumber=1&pageSize=50
cdpapi-Subscription-Key: your-api-key-here
```

| Parameter               | In    | Type    | Required | Description                     |
| ----------------------- | ----- | ------- | -------- | ------------------------------- |
| `instructionBatchId`    | path  | string  | Yes      | The ID of the instruction batch |
| `instructionFilterType` | path  | string  | Yes      | Filter type: `All` or `Closure` |
| `pageNumber`            | query | integer | No       | Page number (default: 1)        |
| `pageSize`              | query | integer | No       | Records per page (default: 50)  |

**Response** (200 OK):

```json
{
  "instructionSummaries": [
    {
      "instructionReference": "5d1abeac-7a8e-4ab9-9ba4-c574a75414aa",
      "instructionAmount": 100.35,
      "currencyCode": "GBP",
      "dateToBeActionedUTC": "2022-04-20"
    }
  ],
  "pageNumber": 1,
  "pageSize": 50,
  "pageCount": 1
}
```

| Response Code | Meaning                        |
| ------------- | ------------------------------ |
| `200`         | Instruction summaries returned |
| `404`         | Instruction batch not found    |

***

## 🔗 3. Get Batch References

**What it is:** Returns a paginated list of instruction reference IDs for a given batch.

**How it works:** Use this to retrieve the individual instruction references contained in a batch.

These references can be used with the Instruction Request API to look up individual instruction details.

Note: this endpoint returns nothing once the batch reaches `Completed`.

```http
GET /{id}/references?pageNumber=1&pageSize=50
cdpapi-Subscription-Key: your-api-key-here
```

| Parameter    | In    | Type    | Required | Description                     |
| ------------ | ----- | ------- | -------- | ------------------------------- |
| `id`         | path  | string  | Yes      | The ID of the instruction batch |
| `pageNumber` | query | integer | Yes      | Page number                     |
| `pageSize`   | query | integer | No       | Records per page                |

**Response** (200 OK):

```json
{
  "references": [
    "5d1abeac-7a8e-4ab9-9ba4-c574a75414aa",
    "5dcc6e14-0fc8-4aef-bb1e-013c41508dc8",
    "a1a0a4ba-1710-4dda-afb3-afbcbf93b799"
  ],
  "pageNumber": 1,
  "pageSize": 50,
  "pageCount": 1
}
```

| Response Code | Meaning                     |
| ------------- | --------------------------- |
| `200`         | References returned         |
| `404`         | Instruction batch not found |

***

## 🔄 4. Update Instruction Batches

**What it is:** Updates the status of one or more instruction batches, typically to mark them as `Closed` to trigger settlement.

**How it works:** Verify the batch totals match your records, then submit a batch update to close them.

You must provide the total amount and total notice amount for each batch as a reconciliation check.

```http
POST /batch-update
Content-Type: application/json
cdpapi-Subscription-Key: your-api-key-here
```

**Request Body:**

```json
{
  "InstructionBatchStatus": "Closed",
  "InstructionBatches": [
    {
      "InstructionBatchId": "4659",
      "TotalAmount": 12650231.02,
      "TotalNoticeAmount": 0
    },
    {
      "InstructionBatchId": "4565",
      "TotalAmount": 567321.27,
      "TotalNoticeAmount": 0
    }
  ]
}
```

| Field                                     | Type   | Description                                       |
| ----------------------------------------- | ------ | ------------------------------------------------- |
| `InstructionBatchStatus`                  | string | The status to update batches to (e.g. `Closed`)   |
| `InstructionBatches`                      | array  | List of batches to update                         |
| `InstructionBatches[].InstructionBatchId` | string | The ID of the batch to update                     |
| `InstructionBatches[].TotalAmount`        | number | The total amount of all instructions in the batch |
| `InstructionBatches[].TotalNoticeAmount`  | number | The total amount of all notice instructions       |

| Response Code | Meaning                                                  |
| ------------- | -------------------------------------------------------- |
| `204`         | Batches updated successfully                             |
| `409`         | Conflict - totals do not match or references are missing |

**Error Response** (409 Conflict):

```json
{
  "Error": "conflict",
  "ErrorDescription": "Missing references conflict when updating batch 7, exception f65645b8-5532-4e0d-8510-9b011f847b81 were not found for InstructionBatch 7."
}
```

***

## 📖 Full API Reference

For the complete OpenAPI specification including all schemas and field descriptions, see the [Instruction Batches API Reference](/api-reference/instruction-batches-api-ref.md).


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://api-docs.flagstoneim.com/apis/instruction-batches.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.