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.

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

Request Body:

{
  "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):

{
  "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.

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

Request Body:

{
  "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):

{
  "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.

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

Response (200 OK):

{
  "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.

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

{
  "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.

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

{
  "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.