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
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.
batchDate
query
DateTime
Yes
The date to retrieve batches for
Response (200 OK):
Batch Fields
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
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.
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):
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.
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):
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.
Request Body:
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
204
Batches updated successfully
409
Conflict - totals do not match or references are missing
Error Response (409 Conflict):
📖 Full API Reference
For the complete OpenAPI specification including all schemas and field descriptions, see the Instruction Batches API Reference.
Last updated