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

# Instruction Requests

**What it is:** The Instruction Request API is the engine of our platform.

It handles all savings instructions - deposits, withdrawals, account closures, and reverts.

**How it works:** You submit an instruction with a unique `instructionReference` (GUID) that you generate.

The API accepts the instruction asynchronously (`202 Accepted`) and we process it within the 24-hour processing window.

Poll the status endpoint to track progress: `Created` → `Processed` or `Rejected`.

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

**API Version:** `2021-11-01`

***

## 📋 Endpoints

| Method | Path                             | Description                     |
| ------ | -------------------------------- | ------------------------------- |
| `POST` | `/deposit`                       | Create a deposit instruction    |
| `POST` | `/withdraw`                      | Create a withdrawal instruction |
| `GET`  | `/status/{instructionReference}` | Check instruction status        |
| `POST` | `/close-account`                 | Request deposit account closure |
| `POST` | `/revert`                        | Revert a previous instruction   |

***

## 💰 1. Create Deposit Instruction

**What it is:** Submits a request to deposit funds into a savings product on behalf of a client.

**How it works:** Specify the product, issue, version, account reference, amount, and a unique instruction reference.

We validate and queue the instruction for processing.

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

**Request Body:**

```json
{
  "productReference": "256",
  "productIssueNumber": "1",
  "productIssueVersionNumber": "2",
  "accountReference": "FL1456",
  "amount": 10000,
  "instructionReference": "1429ddc3-987f-4bff-9f34-77d1b98fca21"
}
```

| Field                       | Type   | Description                           |
| --------------------------- | ------ | ------------------------------------- |
| `productReference`          | string | The ID of the target product          |
| `productIssueNumber`        | string | The issue number of the product       |
| `productIssueVersionNumber` | string | The version of the product issue      |
| `accountReference`          | string | The client's account reference        |
| `amount`                    | number | Deposit amount (to 2 decimal places)  |
| `instructionReference`      | string | Your unique GUID for this instruction |

**Response** (202 Accepted):

```json
{
  "instructionReference": "1429ddc3-987f-4bff-9f34-77d1b98fca21",
  "statusLocation": "/instruction-request/status/1429ddc3-987f-4bff-9f34-77d1b98fca21"
}
```

***

## 💸 2. Create Withdrawal Instruction

**What it is:** Submits a request to withdraw funds from an existing deposit account.

**How it works:** Specify the account, currency, deposit account reference, amount, and a unique instruction reference.

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

**Request Body:**

```json
{
  "accountReference": "FL12345",
  "currencyIsoCode": "GBP",
  "depositAccountReference": "123454565",
  "amount": 500,
  "instructionReference": "1429ddc3-987f-4bff-9f34-77d1b98fca21"
}
```

| Field                     | Type   | Description                             |
| ------------------------- | ------ | --------------------------------------- |
| `accountReference`        | string | The client's account reference          |
| `currencyIsoCode`         | string | Three-letter currency code (ISO-4217)   |
| `depositAccountReference` | string | The deposit account to withdraw from    |
| `amount`                  | number | Withdrawal amount (to 2 decimal places) |
| `instructionReference`    | string | Your unique GUID for this instruction   |

**Response** (202 Accepted):

```json
{
  "instructionReference": "1429ddc3-987f-4bff-9f34-77d1b98fca21",
  "statusLocation": "/instruction-request/status/1429ddc3-987f-4bff-9f34-77d1b98fca21"
}
```

***

## 🔍 3. Check Instruction Status

**What it is:** Returns the current processing status of an instruction.

**How it works:** Poll this endpoint after submitting an instruction to track whether it has been processed or rejected.

```http
GET /status/{instructionReference}
cdpapi-Subscription-Key: your-api-key-here
```

**Response** (200 OK):

```json
{
  "status": "Processed",
  "instructionReference": "1429ddc3-987f-4bff-9f34-77d1b98fca21",
  "statusReason": ""
}
```

### Status Values

| Status      | Meaning                                               |
| ----------- | ----------------------------------------------------- |
| `Created`   | Instruction received and queued for processing        |
| `Processed` | Instruction successfully completed                    |
| `Rejected`  | Instruction failed - check `statusReason` for details |

| Response Code | Meaning                         |
| ------------- | ------------------------------- |
| `200`         | Status returned                 |
| `404`         | Instruction reference not found |

***

## 🗑️ 4. Deposit Account Closure

**What it is:** Request closure of a deposit account at its natural maturity or for an instant access/notice account.

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

```json
{
  "accountReference": "FL12345",
  "currencyIsoCode": "GBP",
  "depositAccountReference": "123454565",
  "instructionReference": "1429ddc3-987f-4bff-9f34-77d1b98fca21"
}
```

***

## ↩️ 5. Revert Instruction

**What it is:** Request to revert a previously submitted instruction.

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

```json
{
  "instructionReference": "1429ddc3-987f-4bff-9f34-77d1b98fca21",
  "instructionToRevertReference": "616aa3f5-3b22-445e-8d34-2b4c5f71844e"
}
```

***

## 📖 Full API Reference

For the complete OpenAPI specification including all schemas and field descriptions, see the [Instruction Request API Reference](/api-reference/instruction-request-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-requests.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.