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