> 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).