# Flagstone API Documents

We're the UK leader in savings API integration.

We connect pension providers, wealth managers, and financial institutions to 60+ banks through one integration.

Our APIs have powered our multi-billion pounds savings platform since 2019.

Partners use them every day to open accounts, receive interest, and report client balances in a regulated UK context.

|                                                              |                                                 |
| ------------------------------------------------------------ | ----------------------------------------------- |
| **In production since**                                      | 2019                                            |
| **Instructions processed annually**                          | 100 million+                                    |
| **Capital transferred to date**                              | £100 billion+                                   |
| **Partner bank network**                                     | 60+ banking institutions                        |
| **Sustained throughput**                                     | Up to 50 requests/second                        |
| **Processing window**                                        | 24-hour instruction cycle                       |
| **Regulatory status**                                        | FCA authorised and regulated                    |
| **Client coverage**                                          | Individual, Company                             |
| **FSCS (Financial Services Compensation Scheme) protection** | Per-product, per-institution visibility via API |

Whether you run a large pension scheme or a SIPP (Self-Invested Personal Pension) proposition, the pattern is simple.

You integrate once with a mature, version-stable API suite and scale with confidence.

***

## 🔗 Core Integration Flow

<figure><img src="https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-2d721381217e7fbbd0514140b5d2294113ff4955%2Fintegration-partner-overview.png?alt=media" alt="Core integration flow"><figcaption></figcaption></figure>

1. **Register your client** - Individual or company, via the Client API
2. **Browse available products** - Fixed term, instant access, and notice accounts via the Product Catalog API
3. **Submit instructions** - Deposits, withdrawals, and other operations via the Instruction Request API
4. **Track positions** - View deposit accounts, interest, and pending payments via the Portfolios API

***

## 📚 API Suite

| API                                                   | What it does                                         | Version      |
| ----------------------------------------------------- | ---------------------------------------------------- | ------------ |
| [Client API](/apis/clients)                           | Onboard and manage individual & company clients      | `2020-08-01` |
| [Product Catalog API](/apis/products)                 | Browse savings products, rates, and terms            | `2022-07-01` |
| [Instruction Request API](/apis/instruction-requests) | Submit deposits, withdrawals, and other instructions | `2021-11-01` |
| [Portfolios API](/apis/portfolios)                    | View client portfolios and deposit account positions | `2020-04-01` |
| [Instruction Batches API](/apis/instruction-batches)  | View and manage daily instruction settlement batches | -            |

Each API has a dedicated guide with business context, endpoint reference, and request/response examples. Full OpenAPI 3.0 specifications are available for each:

* [Client API Reference](/api-reference/client-api-ref)
* [Products API Reference](/api-reference/products-api-ref)
* [Instruction Request API Reference](/api-reference/instruction-request-api-ref)
* [Portfolios API Reference](/api-reference/financial-partners-api-ref)
* [Instruction Batches API Reference](/api-reference/instruction-batches-api-ref)

***

## 🏗️ Platform Architecture

| Capability              | Detail                                          |
| ----------------------- | ----------------------------------------------- |
| **Authentication**      | API key via `cdpapi-Subscription-Key` header    |
| **Environments**        | Sandbox and Production                          |
| **Specification**       | OpenAPI 3.0.1 for all APIs                      |
| **Client types**        | Individual and Company                          |
| **Currencies**          | GBP, EUR, USD                                   |
| **Product types**       | Fixed Term, Instant Access, Notice              |
| **FSCS protection**     | Visibility per product and institution          |
| **Concurrency control** | Optimistic versioning on clients and portfolios |
| **Idempotency**         | Built-in                                        |

***

## 🚀 Quick Start

1. [Get your API credentials](/getting-started) - sandbox and production keys
2. [Understand the data model](/core-concepts) - how clients, products, instructions, and portfolios relate
3. [Create your first client](/apis/clients) - start with the Client API
4. [Submit your first deposit](/apis/instruction-requests) - place an instruction against a product


# Getting Started

This guide covers what you need to begin integrating with our API: environments, authentication, rate limits, and a quick-start walkthrough.

***

## 🌐 1. Environments

We provide two environments:

| Environment    | Base URL                              | Purpose                 |
| -------------- | ------------------------------------- | ----------------------- |
| **Sandbox**    | `https://api.sandbox.flagstoneim.com` | Development and testing |
| **Production** | `https://api.flagstoneim.com`         | Live operations         |

All API paths are relative to the environment base URL. For example, to list products in sandbox:

```http
GET https://api.sandbox.flagstoneim.com/products/
```

***

## 🔑 2. Authentication

You'll need both an API key and an OAuth 2.0 access token for every API call.

See [Authentication](/authentication) for full details including token request flows and renewal strategies.

***

## ⚡ 3. Rate Limits

Each API has its own rate limits based on expected usage. Details are available on request.

If you exceed the rate limit, you'll get a `429 Too Many Requests` response. Use exponential backoff in your integration.

***

## 📋 4. API Versioning

Each API is versioned independently using a date-based scheme in the OpenAPI specification:

| API                     | Version      |
| ----------------------- | ------------ |
| Client API              | `2020-08-01` |
| Products API            | `2022-07-01` |
| Instruction Request API | `2021-11-01` |
| Financial Partners API  | `2020-04-01` |
| Instruction Batches API | `-`          |

***

## 🏁 5. Quick Start - Your First Integration

Follow these four steps to complete a basic end-to-end integration:

### Step 1: Create a Client

```http
POST https://api.sandbox.flagstoneim.com/clients/financial-partner
cdpapi-Subscription-Key: your-api-key-here
Content-Type: application/json
```

```json
{
  "externalReference": "PARTNER-001",
  "title": "Mr",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1985-06-15T00:00:00.0000000+00:00",
  "addressLine1": "10 Downing Street",
  "addressLine2": "",
  "postCode": "SW1A2AA",
  "countryCode": "GBR",
  "phoneNumber": "02071234567",
  "ukResident": true,
  "ukDomicile": true,
  "emailAddress": "john.smith@example.com",
  "accounts": [
    {
      "accountName": "John Smith",
      "accountNumber": "12345678",
      "sortCode": "200000",
      "currencyCode": "GBP"
    }
  ]
}
```

**Response** (201 Created):

```json
{
  "clientReference": "330825e3-a306-4a0f-b722-a6740ec096e6"
}
```

### Step 2: Browse Products

```http
GET https://api.sandbox.flagstoneim.com/products/
cdpapi-Subscription-Key: your-api-key-here
```

Select a product from the response - note the `productId`, `productIssueNumber`, and `productIssueVersionNumber`.

### Step 3: Submit a Deposit Instruction

```http
POST https://api.sandbox.flagstoneim.com/instruction-request/deposit
cdpapi-Subscription-Key: your-api-key-here
Content-Type: application/json
```

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

**Response** (202 Accepted):

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

### Step 4: Check the Portfolio

```http
GET https://api.sandbox.flagstoneim.com/financial-partners/portfolios?PageNumber=1&PageSize=50
cdpapi-Subscription-Key: your-api-key-here
```

This returns paged portfolio data showing deposit accounts, balances, and interest information for all your clients.

***

## 📖 Next Steps

* [Core Concepts](/core-concepts) - Understand the data model and lifecycle
* [Client API](/apis/clients) - Full client onboarding reference
* [Product Catalog API](/apis/products) - Browse and evaluate products


# Authentication

You'll need both an API key and an OAuth 2.0 access token for every API call.

***

## API Key

Include your subscription key in the `cdpapi-Subscription-Key` header on every request.

```http
GET /products/ HTTP/1.1
Host: api.sandbox.flagstoneim.com
cdpapi-Subscription-Key: your-api-key-here
```

We issue sandbox and production keys separately during onboarding. Keep your key secret and never embed it in client-side code.

***

## OAuth 2.0 Client Credentials

You also authenticate with OAuth 2.0 using the client credentials grant. You exchange a `client_id` and `client_secret` for a short-lived access token, then pass that token as a Bearer header on every API call.

### 1. Get an Access Token

```http
POST /connect/token HTTP/1.1
Host: auth.flagstoneim.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
```

You'll get back an `access_token` and its lifetime in seconds (`expires_in`).

We'll exchange your `client_id` and `client_secret` securely before your integration goes live. Store the secret in a secrets manager or vault. Never log or transmit it beyond this token request.

### 2. Call APIs with the Token

Include the `access_token` as a Bearer token in the `Authorization` header:

```http
POST /example HTTP/1.1
Host: api.flagstoneim.com
Authorization: Bearer {access_token}
Content-Type: application/json
```

### 3. Token Renewal

Access tokens expire. You've got two renewal strategies:

| Strategy        | How                                                                                             |
| --------------- | ----------------------------------------------------------------------------------------------- |
| **Pre-emptive** | Track `expires_in` from the token response. Request a new token before the current one expires. |
| **Reactive**    | If an API call returns `401 Unauthorized`, request a new token and retry the call.              |

Renewing pre-emptively avoids a failed call on every token expiry. We'd recommend combining both: renew ahead of expiry, but handle `401` as a fallback.

### Request Access Token Sequence

<figure><img src="https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-bb03c05f36aa2e5cd5311011c1d81b18b9dc45b5%2Fauth-new-token.png?alt=media" alt="Request new token Flow"><figcaption></figcaption></figure>

### Token Renewal Sequence

<figure><img src="https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-fc4041b6024ae641aa8e624a23d7d5c92fabeb43%2Fauth-refresh-token.png?alt=media" alt="Refresh token Flow"><figcaption></figcaption></figure>

***

## Next Steps

* [Getting Started](/getting-started) - Environments, rate limits, and a quick-start walkthrough
* [Core Concepts](/core-concepts) - Data model and lifecycle


# Core Concepts

This page explains how our key entities relate to each other and how data flows through the system.

***

## 📊 1. Data Model Overview

Our platform is built around six core entities:

| Entity                  | Description                                                                                                                                   | API                                                   |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| **Client**              | An individual or company registered on the platform                                                                                           | [Client API](/apis/clients)                           |
| **Product**             | A savings product offered by a financial institution (fixed term, instant access, or notice)                                                  | [Products API](/apis/products)                        |
| **Product Issue**       | A specific version/tranche of a product with its own rate and limits                                                                          | [Products API](/apis/products)                        |
| **Instruction Request** | A deposit, withdrawal, or other operation you submit for processing. We create an Instruction in an InstructionBatch once processing succeeds | [Instruction Request API](/apis/instruction-requests) |
| **Portfolio**           | A client's collection of deposit accounts and their balances                                                                                  | [Portfolios API](/apis/portfolios)                    |
| **InstructionBatch**    | A set of instructions for the next working day. You update once a day to signal settlement                                                    | [Instruction Batches API](/apis/instruction-batches)  |

### How They Relate

<figure><img src="https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-ba358559db6df7fe23aef65196959ab94e3cbe04%2FERD.png?alt=media" alt="Entity Relationships"><figcaption></figcaption></figure>

* A **Client** (individual, or company) is onboarded by a financial partner
* Each client has one or more **Portfolios** (one per currency)
* A portfolio contains **Deposit Accounts**, each opened against a specific **Product Issue**
* You submit **Instruction Requests** (deposits, withdrawals, etc.) against products. We process them into instructions asynchronously
* We update **Instruction Batches** (one per partner and instruction type) every bank working day as we process instructions
* Once processed, the instruction creates or modifies a deposit account within the portfolio

***

## 🔄 2. Lifecycle Flow

**What it is:** The typical end-to-end journey from client onboarding through to portfolio tracking.

**How it works:**

<figure><img src="https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-2d721381217e7fbbd0514140b5d2294113ff4955%2Fintegration-partner-overview.png?alt=media" alt="Core integration flow"><figcaption></figcaption></figure>

### Stage-by-Stage

1. **Client Registration** - Register your client with their personal details. You'll receive a `clientReference` that identifies them throughout the platform.
2. **Product Selection** - Browse available products to find suitable savings options. Products include term type (fixed, instant access, notice), interest rates, deposit limits, and FSCS (Financial Services Compensation Scheme) protection status.
3. **Instruction Submission** - Submit a deposit, withdrawal, or other instruction request. You generate a unique `instructionReference` (GUID) for each one. The API returns `202 Accepted` and we process it asynchronously.
4. **Status Tracking** - Poll the status endpoint to check whether your instruction is `Created`, `Processed`, or `Rejected`. The instruction response includes a `statusLocation` URI.
5. **Batch Processing** - Poll the batch endpoint to check whether the batch is `Locked`. When you update the status to `Closed`, we'll make payment and process the instructions.
6. **Portfolio Tracking** - View the client's deposit accounts, current balances, accrued interest, and pending payment batch items through the portfolios endpoint.

***

## 📑 3. Pagination

Paged endpoints use a consistent pattern across the platform:

| Parameter    | Type    | Description                    |
| ------------ | ------- | ------------------------------ |
| `PageNumber` | integer | The page to retrieve (1-based) |
| `PageSize`   | integer | Number of items per page       |

**Example Request:**

```http
GET /financial-partners/portfolios?PageNumber=1&PageSize=50
```

**Paged Response Fields:**

```json
{
  "portfolioInformation": [ ... ],
  "pageNumber": 1,
  "pageCount": 50,
  "sortOrder": "updatedDateDesc"
}
```

* `pageNumber` - Current page
* `pageCount` - Total number of pages
* `sortOrder` - Sort order applied to the results

Iterate through pages by incrementing `PageNumber` until you reach `pageCount`.

***

## 🔑 4. Key Patterns

### Idempotent Instruction Submission

Every instruction request requires a unique `instructionReference` (GUID) that you generate. If you submit the same reference twice, the API returns the existing instruction rather than creating a duplicate. This makes instruction submission safe to retry.

### Optimistic Concurrency

Client and portfolio updates use version numbers (`clientVersion`, `portfolioVersion`). You must supply the current version when updating - if it doesn't match, the API returns `409 Conflict`. This prevents concurrent updates from overwriting each other.

### Asynchronous Processing

Instruction requests return `202 Accepted` immediately. We process the instruction asynchronously within our 24-hour processing window. Use the `statusLocation` endpoint to poll for the final status.

***

## 📖 Next Steps

* [Client API](/apis/clients) - Create and manage clients
* [Product Catalog API](/apis/products) - Browse available products
* [Instruction Request API](/apis/instruction-requests) - Submit and track instructions
* [Portfolios API](/apis/portfolios) - View client portfolio positions
* [Instruction Batches API](/apis/instruction-batches) - View and manage settlement batches


# APIs

We expose five core APIs that together cover the full savings integration lifecycle:

| API                                                   | Purpose                                              | Base Path              |
| ----------------------------------------------------- | ---------------------------------------------------- | ---------------------- |
| [Client API](/apis/clients)                           | Register and manage individual & company clients     | `/clients`             |
| [Product Catalog API](/apis/products)                 | Browse savings products, rates, terms, and capacity  | `/products`            |
| [Instruction Request API](/apis/instruction-requests) | Submit deposits, withdrawals, and other operations   | `/instruction-request` |
| [Portfolios API](/apis/portfolios)                    | View client deposit account positions and interest   | `/financial-partners`  |
| [Instruction Batches API](/apis/instruction-batches)  | View and manage daily instruction settlement batches | `/instruction-batches` |

You can use all APIs in both sandbox and production environments. See [Authentication](/authentication) for API key and OAuth 2.0 details.


# Clients

**What it is:** The Client API handles onboarding and management of both individual and company clients on our platform.

Every integration starts here - you must register a client before they can browse products, submit instructions, or hold a portfolio.

**How it works:** You submit client details (name, address, bank account, KYC (Know Your Customer) data) and receive a `clientReference` that identifies the client across all our APIs.

Clients can be updated using optimistic concurrency via their `clientVersion`.

**Base URL:** `https://api.sandbox.flagstoneim.com/clients`

**API Version:** `2020-08-01`

***

## 📋 Endpoints

| Method  | Path                                                           | Description                 |
| ------- | -------------------------------------------------------------- | --------------------------- |
| `POST`  | `/financial-partner`                                           | Create an individual client |
| `POST`  | `/financial-partner/company`                                   | Create a company client     |
| `GET`   | `/{clientReference}`                                           | Get an individual client    |
| `GET`   | `/financial-partner/company/{clientReference}`                 | Get a company client        |
| `PATCH` | `/{clientReference}/{clientVersion}`                           | Update an individual client |
| `PATCH` | `/financial-partner/company/{clientReference}/{clientVersion}` | Update a company client     |

***

## 👤 1. Create an Individual Client

**What it is:** Registers a new individual client on our platform.

**How it works:** Submit the client's personal details, address, bank account, and optional tax obligations.

The API returns a unique `clientReference`.

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

**Request Body:**

```json
{
  "externalReference": "GSGEHQ342",
  "title": "Mr",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1985-06-15T00:00:00.0000000+00:00",
  "addressLine1": "213 Greenway",
  "addressLine2": "",
  "city": "Portsmouth",
  "county": "Hampshire",
  "postCode": "PO122AB",
  "countryCode": "GBR",
  "phoneNumber": "01980123654",
  "ukResident": true,
  "ukDomicile": true,
  "emailAddress": "john@example.com",
  "nonUkTaxObligations": [
    {
      "countryCode": "USA",
      "taxIdentificationNumber": "53464643"
    }
  ],
  "accounts": [
    {
      "accountName": "John Smith",
      "accountNumber": "01233234",
      "sortCode": "326487",
      "currencyCode": "GBP"
    }
  ]
}
```

**Required Fields:** `externalReference`, `title`, `firstName`, `lastName`, `dateOfBirth`, `addressLine1`, `addressLine2`, `postCode`, `countryCode`, `emailAddress`

**Response** (201 Created):

```json
{
  "clientReference": "330825e3-a306-4a0f-b722-a6740ec096e6"
}
```

| Status | Meaning                                                                   |
| ------ | ------------------------------------------------------------------------- |
| `200`  | Client with identical details already exists - returns existing reference |
| `201`  | Client created successfully                                               |
| `400`  | Request is malformed                                                      |
| `409`  | Conflict - e.g. external reference already exists                         |

***

## 🏢 2. Create a Company Client

**What it is:** Registers a new company client on the platform.

**How it works:** Similar to individual clients, but includes company-specific fields like company name, FSCS eligibility, FCA number, and evidence declarations.

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

**Request Body:**

```json
{
  "externalReference": "71d1fd54-0baa-4356-8637-0eea33675123",
  "companyName": "ABC Limited",
  "fscsEligible": true,
  "fcaNumber": "326487",
  "companyNumber": "1234567",
  "hasEvidenceConfirmingHowMoniesAreHeld": true,
  "doesEntityHaveUnderlyingBeneficiariesWhoMayBeEntitledToFund": true,
  "addressLine1": "213 Greenway",
  "addressLine2": "",
  "city": "Portsmouth",
  "county": "Hampshire",
  "postCode": "PO122AB",
  "countryCode": "GBR",
  "phoneNumber": "01980123654",
  "emailAddress": "js@abc.com",
  "accounts": [
    {
      "accountName": "ABC Limited",
      "accountNumber": "01233234",
      "sortCode": "326487",
      "currencyCode": "GBP"
    }
  ]
}
```

**Required Fields:**

* `externalReference`, `companyName`, `fscsEligible`
* `hasEvidenceConfirmingHowMoniesAreHeld`
* `doesEntityHaveUnderlyingBeneficiariesWhoMayBeEntitledToFund`
* `addressLine1`, `addressLine2`, `postCode`, `countryCode`
* `emailAddress`, `phoneNumber`, `accounts`

**Response** (201 Created):

```json
{
  "clientReference": "234256265"
}
```

***

## 🔍 3. Get a Client

**What it is:** Retrieve the full details of an existing individual or company client.

### Individual Client

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

**Response** (200 OK):

```json
{
  "clientReference": "1231455",
  "clientVersion": 3,
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1970-10-21T00:00:00.0000000+00:00",
  "addressLine1": "213 Greenway",
  "city": "Portsmouth",
  "county": "Hampshire",
  "postCode": "PO122AB",
  "countryCode": "GBR",
  "phoneNumber": "01980123654",
  "ukResident": true,
  "ukDomicile": true,
  "emailAddress": "john@example.com",
  "documents": [
    {
      "documentUri": "http://anExampleLink/2",
      "documentType": "driving-license"
    }
  ],
  "nonUkTaxObligations": [
    {
      "countryCode": "USA",
      "taxIdentificationNumber": "53464643"
    }
  ],
  "accounts": [
    {
      "accountName": "John Smith",
      "accountNumber": "01233234",
      "sortCode": "326487",
      "currencyCode": "GBP"
    }
  ]
}
```

### Company Client

```http
GET /financial-partner/company/{clientReference}
cdpapi-Subscription-Key: your-api-key-here
```

Returns company-specific fields including `companyName`, `fscsEligible`, `fcaNumber`, `companyNumber`, and evidence flags.

***

## ✏️ 4. Update a Client

**What it is:** Update the details of an existing client.

**How it works:** Supply the current `clientVersion` in the URL path.

If the version doesn't match the server's current version, the API returns `409 Conflict` to prevent concurrent overwrites.

### Update Individual

```http
PATCH /{clientReference}/{clientVersion}
Content-Type: application/json-patch+json
cdpapi-Subscription-Key: your-api-key-here
```

```json
{
  "title": "Mr",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1985-06-15T00:00:00.0000000+00:00",
  "addressLine1": "214 Greenway",
  "addressLine2": "",
  "postCode": "PO122AB",
  "countryCode": "GBR",
  "phoneNumber": "01980123654",
  "ukResident": true,
  "ukDomicile": true,
  "emailAddress": "john.updated@example.com"
}
```

**Response:** `204 No Content` on success.

### Update Company

```http
PATCH /financial-partner/company/{clientReference}/{clientVersion}
Content-Type: application/json
cdpapi-Subscription-Key: your-api-key-here
```

| Status | Meaning                               |
| ------ | ------------------------------------- |
| `204`  | Update successful                     |
| `400`  | Malformed request                     |
| `404`  | Client not found                      |
| `409`  | Version conflict - re-fetch and retry |

***

## 📖 Full API Reference

For the complete OpenAPI specification including all schemas and field descriptions, see the [Client API Reference](/api-reference/client-api-ref).


# Product Catalog

**What it is:** The Product Catalog API lets you browse the savings products available on our platform.

Products are offered by financial institutions and include fixed term deposits, instant access accounts, and notice accounts - each with specific rates, terms, and deposit limits.

**How it works:** Query the products endpoint to get a list of all available products with their current issues (rate tranches).

Each product includes the financial institution details, FSCS protection status, and associated documents.

Use the product issue endpoint to get specific rates and issue details.

**Base URL:** `https://api.sandbox.flagstoneim.com/products`

**API Version:** `2022-07-01`

***

## 📋 Endpoints

| Method | Path                                                                               | Description                           |
| ------ | ---------------------------------------------------------------------------------- | ------------------------------------- |
| `GET`  | `/`                                                                                | List all available products           |
| `GET`  | `/{productId}`                                                                     | Get full detail of a specific product |
| `GET`  | `/{productId}/{issueNumber}/summary`                                               | Get product issue details with rates  |
| `GET`  | `/{productId}/issue/{issueNumber}/version/{versionNumber}/document/{documentType}` | Download product document             |

***

## 📦 1. List All Products

**What it is:** Returns all products available to your financial partner, including their current issues and rates.

**How it works:** Call the root endpoint to get the full product catalog. Each product includes one or more issues (rate tranches), financial institution details, and term information.

```http
GET /
cdpapi-Subscription-Key: your-api-key-here
```

**Response** (200 OK):

```json
{
  "productItems": [
    {
      "productId": "1",
      "productTermType": "FixedTerm",
      "termLengthUnit": "Month",
      "termLength": 1,
      "noticeLengthUnit": "NoNotice",
      "noticeLength": 0,
      "productIssues": [
        {
          "productIssueNumber": 1,
          "productIssueVersionNumber": 1,
          "isClosedToNewAccounts": false,
          "ratePercent": 2.5,
          "depositPerAccountMinimum": 1000,
          "depositPerAccountMaximum": 10000,
          "aer": 2.9,
          "documents": [
            {
              "documentId": "2",
              "documentVersion": 2,
              "documentType": "FlagstoneTerms",
              "contentTypes": ["text/html"],
              "uri": "api.flagstoneim.com/products/6/issue/1/version/1/document/FlagstoneTerms"
            }
          ]
        }
      ],
      "financialInstitution": {
        "financialInstitutionId": "2",
        "financialInstitutionVersion": 1,
        "isFscsProtected": false,
        "isSharia": false,
        "financialInstitutionName": "Aldmore Bank",
        "financialInstitutionShortName": "ALD",
        "financialInstitutionType": "Bank",
        "countryCode": "GBR"
      },
      "currencyCode": "GBP",
      "interestPaidType": "AtMaturity",
      "interestPaysFrequency": "Month",
      "dateLastUpdatedUTC": "2022-01-02T14:50:09.0000000+00:00"
    }
  ]
}
```

### Understanding the Product Model

| Field              | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `productTermType`  | `FixedTerm`, `InstantAccess`, or `Notice`             |
| `termLengthUnit`   | `Day`, `Month`, `Year`, or `NoTerm` (instant access)  |
| `termLength`       | Duration in the unit specified (0 for instant access) |
| `noticeLengthUnit` | `Day`, `Month`, `Year`, or `NoNotice`                 |
| `noticeLength`     | Notice period required for withdrawals                |
| `interestPaidType` | When interest is paid - `AtMaturity`, `Daily`, etc.   |
| `currencyCode`     | Three-letter ISO-4217 currency code (GBP, EUR, USD)   |

### Product Issues

Each product has one or more **issues** - these represent rate tranches:

| Field                       | Description                             |
| --------------------------- | --------------------------------------- |
| `productIssueNumber`        | The issue number of this tranche        |
| `productIssueVersionNumber` | The version within the issue            |
| `ratePercent`               | The headline interest rate              |
| `aer`                       | Annual Equivalent Rate                  |
| `depositPerAccountMinimum`  | Minimum deposit amount                  |
| `depositPerAccountMaximum`  | Maximum deposit amount                  |
| `isClosedToNewAccounts`     | Whether this issue accepts new deposits |

### Financial Institution

Each product is offered by a financial institution:

| Field                         | Description                                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------- |
| `financialInstitutionName`    | Full name of the bank/building society                                                   |
| `isFscsProtected`             | Whether deposits are covered by FSCS (Financial Services Compensation Scheme) protection |
| `isSharia`                    | Whether this is a Sharia-compliant institution                                           |
| `countryCode`                 | Country of the institution (ISO-3166)                                                    |
| `financialInstitutionGroupId` | Institutions in the same group share FSCS limits                                         |

***

## 🔍 2. Get Product Detail

**What it is:** Returns the full detail of a specific product, including all issues and their version history.

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

**Response** (200 OK): Returns the same product structure as the list endpoint, but for a single product with full issue version history.

| Status | Meaning           |
| ------ | ----------------- |
| `200`  | Product found     |
| `404`  | Product not found |

***

## 📊 3. Get Product Summary

**What it is:** Returns a summary of a specific product issue, including projected returns for a proposed deposit amount.

**How it works:** Supply the product ID, issue number, and optionally a proposed deposit amount to see estimated balance and net rate.

```http
GET /{productId}/{issueNumber}/summary?proposedDepositAmount=10000
cdpapi-Subscription-Key: your-api-key-here
```

**Response** (200 OK):

```json
{
  "productId": 11,
  "productIssueNumber": 1,
  "netRate": 0.55,
  "estimatedBalance": 10055,
  "dateOfAccountOpen": "2021-10-18T00:00:00.0000000+00:00",
  "termsAndConditionsUrl": "https://api.flagstoneim.com/products/11/issue/1/version/1/document/FlagstoneTerms"
}
```

***

## 📄 4. Get Product Document

**What it is:** Download product documents such as terms and conditions, deposit information, or Flagstone terms.

```http
GET /{productId}/issue/{issueNumber}/version/{versionNumber}/document/{documentType}
Accept: application/pdf
cdpapi-Subscription-Key: your-api-key-here
```

**Document Types:**

* `ProductTermsAndConditions`
* `DepositInformation`
* `FlagstoneTerms`

**Response:** Returns the document as a binary file stream.

***

## 📖 Full API Reference

For the complete OpenAPI specification including all schemas and field descriptions, see the [Products API Reference](/api-reference/products-api-ref).


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


# Portfolios

**What it is:** The Portfolios API provides a view of your clients' savings positions.

It shows all deposit accounts, balances, accrued interest, and pending payment batch items.

This is the primary endpoint for tracking the outcome of instructions and reporting to clients.

**How it works:** Query the portfolios endpoint with pagination to retrieve all client positions, or use the client-specific endpoint to get portfolios for a single client.

Portfolios are versioned.

**Base URL:** `https://api.sandbox.flagstoneim.com/financial-partners`

**API Version:** `2020-04-01`

***

## 📋 Endpoints

| Method | Path                                    | Description                          |
| ------ | --------------------------------------- | ------------------------------------ |
| `GET`  | `/portfolios`                           | Get paged portfolios for all clients |
| `GET`  | `/clients/{clientReference}/portfolios` | Get portfolios for a specific client |

***

## 📦 1. Get All Portfolios (Paged)

**What it is:** Returns a paged list of all client portfolios under your financial partner.

**How it works:** Use `PageNumber` and `PageSize` query parameters to paginate through the full portfolio set. Results are sorted by last updated date (descending).

```http
GET /portfolios?PageNumber=1&PageSize=50
cdpapi-Subscription-Key: your-api-key-here
```

**Response** (200 OK):

```json
{
  "portfolioInformation": [
    {
      "clientReference": "8836442",
      "portfolio": {
        "portfolioId": "23533",
        "portfolioVersion": 2,
        "currencyCode": "GBP",
        "depositAccounts": [
          {
            "depositAccountId": "67",
            "productId": "6",
            "productVersionOnAccountOpen": 1,
            "dateAccountOpenedUTC": "2025-10-01T16:00:00.0000000+00:00",
            "dateAccountMaturesUTC": "2025-10-01T16:00:00.0000000+00:00",
            "amount": 50013.14,
            "interestPaidAmount": 11.02
          }
        ]
      },
      "pendingPaymentBatchItems": [
        {
          "pendingBatchItemId": "75692cd8-c74f-4a1d-a9fb-6ff9998be905",
          "pendingBatchType": "deposit",
          "depositAccountId": "2233",
          "productId": "6",
          "productVersion": "6",
          "dateAddedUTC": "2025-10-01T16:00:00.0000000+00:00",
          "amount": 100
        },
        {
          "instructionReference": "cd0533ba-5225-4520-9ac0-e85659db6938",
          "pendingBatchType": "withdrawal",
          "depositAccountId": "67",
          "productId": "6",
          "productVersion": "6",
          "dateAddedUTC": "2025-10-01T16:00:00.0000000+00:00",
          "dateToBeActionedUTC": "2025-10-01T16:00:00.0000000+00:00",
          "amount": 100
        }
      ]
    }
  ],
  "pageNumber": 1,
  "pageCount": 50,
  "sortOrder": "updatedDateDesc"
}
```

### Pagination

| Parameter    | Type    | Description                    |
| ------------ | ------- | ------------------------------ |
| `PageNumber` | integer | The page to retrieve (1-based) |
| `PageSize`   | integer | Number of portfolios per page  |

**Pagination Example:**

```
Page 1: GET /portfolios?PageNumber=1&PageSize=50
Page 2: GET /portfolios?PageNumber=2&PageSize=50
...continue until PageNumber reaches pageCount
```

***

## 👤 2. Get Portfolios for a Client

**What it is:** Returns all portfolios for a specific client (one per currency).

**How it works:** Supply the client reference in the URL path. Optionally include `If-Modified-Since` header to check for changes since a given date.

```http
GET /clients/{clientReference}/portfolios
cdpapi-Subscription-Key: your-api-key-here
```

**Optional Header:**

| Header              | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `If-Modified-Since` | ISO-8601 datetime - returns `304 Not Modified` if unchanged |

**Response** (200 OK):

```json
{
  "portfolioInformation": [
    {
      "clientReference": "8836442",
      "portfolio": {
        "portfolioId": "23533",
        "portfolioVersion": 2,
        "currencyCode": "GBP",
        "depositAccounts": [
          {
            "depositAccountId": "67",
            "productId": "6",
            "productVersionOnAccountOpen": 1,
            "dateAccountOpenedUTC": "2025-10-01T16:00:00.0000000+00:00",
            "dateAccountMaturesUTC": "2025-10-01T16:00:00.0000000+00:00",
            "amount": 50013.14,
            "interestAccruedAmount": 33.06,
            "interestPaidAmount": 11.02,
            "interestExpectedAmount": 1001.02
          }
        ]
      },
      "links": [
        {
          "rel": "pendingInstructions",
          "href": "https://api.flagstoneim.com/instructions?clientReference=8836442&status=pending"
        }
      ]
    }
  ]
}
```

| Status | Meaning                                         |
| ------ | ----------------------------------------------- |
| `200`  | Portfolios returned                             |
| `304`  | Not modified since the `If-Modified-Since` date |

> **Note:** The client-specific endpoint returns additional interest fields (`interestAccruedAmount`, `interestExpectedAmount`) and hypermedia `links` for related resources. These aren't present in the paged portfolio endpoint.

***

## 📊 Understanding the Portfolio Model

### Portfolio

| Field              | Description                                      |
| ------------------ | ------------------------------------------------ |
| `portfolioId`      | Unique identifier for the portfolio              |
| `portfolioVersion` | Version number (used for optimistic concurrency) |
| `currencyCode`     | ISO-4217 currency code (GBP, EUR, USD)           |
| `depositAccounts`  | Array of deposit accounts within this portfolio  |

### Deposit Account

| Field                    | Description                                 |
| ------------------------ | ------------------------------------------- |
| `depositAccountId`       | Unique identifier of the deposit account    |
| `productId`              | The product this account was opened against |
| `dateAccountOpenedUTC`   | When the account was opened                 |
| `dateAccountMaturesUTC`  | Maturity date (for fixed term products)     |
| `amount`                 | Current balance                             |
| `interestAccruedAmount`  | Interest accrued but not yet paid           |
| `interestPaidAmount`     | Interest already paid out                   |
| `interestExpectedAmount` | Total expected interest over the term       |

### Pending Payment Batch Items

These represent instructions that have been accepted but not yet settled:

| Field                 | Description                                     |
| --------------------- | ----------------------------------------------- |
| `pendingBatchType`    | `deposit` or `withdrawal`                       |
| `depositAccountId`    | Target deposit account (empty for new deposits) |
| `productId`           | Product the instruction relates to              |
| `amount`              | Amount of the pending instruction               |
| `dateToBeActionedUTC` | When the instruction will be processed          |

***

## 📖 Full API Reference

For the complete OpenAPI specification including all schemas and field descriptions, see the [Financial Partners API Reference](/api-reference/financial-partners-api-ref).


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


# Client API Reference

{% openapi src="/files/dwJ49YBFu4YGF1n6AH94" path="/financial-partner" method="post" %}
[client-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-23c6f5aa13aa625efccd2267c9df918e0783f9df%2Fclient-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/dwJ49YBFu4YGF1n6AH94" path="/financial-partner/company" method="post" %}
[client-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-23c6f5aa13aa625efccd2267c9df918e0783f9df%2Fclient-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/dwJ49YBFu4YGF1n6AH94" path="/{clientReference}" method="get" %}
[client-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-23c6f5aa13aa625efccd2267c9df918e0783f9df%2Fclient-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/dwJ49YBFu4YGF1n6AH94" path="/financial-partner/company/{clientReference}" method="get" %}
[client-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-23c6f5aa13aa625efccd2267c9df918e0783f9df%2Fclient-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/dwJ49YBFu4YGF1n6AH94" path="/{clientReference}/{clientVersion}" method="patch" %}
[client-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-23c6f5aa13aa625efccd2267c9df918e0783f9df%2Fclient-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/dwJ49YBFu4YGF1n6AH94" path="/financial-partner/company/{clientReference}/{clientVersion}" method="patch" %}
[client-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-23c6f5aa13aa625efccd2267c9df918e0783f9df%2Fclient-api.json?alt=media)
{% endopenapi %}


# Products API Reference

{% openapi src="/files/GJFiiMKqrL8zGAISjmhY" path="/" method="get" %}
[products-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-c615c4a56873054e1cdf73050e2ebec44a3524f9%2Fproducts-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/GJFiiMKqrL8zGAISjmhY" path="/{productId}" method="get" %}
[products-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-c615c4a56873054e1cdf73050e2ebec44a3524f9%2Fproducts-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/GJFiiMKqrL8zGAISjmhY" path="/{productId}/{issueNumber}/summary" method="get" %}
[products-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-c615c4a56873054e1cdf73050e2ebec44a3524f9%2Fproducts-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/GJFiiMKqrL8zGAISjmhY" path="/{productId}/issue/{productIssueNumber}/version/{productIssueVersionNumber}/document/{documentType}" method="get" %}
[products-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-c615c4a56873054e1cdf73050e2ebec44a3524f9%2Fproducts-api.json?alt=media)
{% endopenapi %}


# Instruction Request API Reference

{% openapi src="/files/H2ZQsQu57Jw14VHhdOwv" path="/deposit" method="post" %}
[instruction-request-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-7344c47c219fb9dc77dc4aff178564aa3e5c189e%2Finstruction-request-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/H2ZQsQu57Jw14VHhdOwv" path="/withdraw" method="post" %}
[instruction-request-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-7344c47c219fb9dc77dc4aff178564aa3e5c189e%2Finstruction-request-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/H2ZQsQu57Jw14VHhdOwv" path="/status/{instructionReference}" method="get" %}
[instruction-request-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-7344c47c219fb9dc77dc4aff178564aa3e5c189e%2Finstruction-request-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/H2ZQsQu57Jw14VHhdOwv" path="/close-account" method="post" %}
[instruction-request-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-7344c47c219fb9dc77dc4aff178564aa3e5c189e%2Finstruction-request-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/H2ZQsQu57Jw14VHhdOwv" path="/revert" method="post" %}
[instruction-request-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-7344c47c219fb9dc77dc4aff178564aa3e5c189e%2Finstruction-request-api.json?alt=media)
{% endopenapi %}


# Portfolios API Reference

{% openapi src="/files/GVivPGdSW1FYuMOX0I1a" path="/portfolios" method="get" %}
[financial-partners-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-eff446c2c0094ee59446cf8819d991ce4c1a04a5%2Ffinancial-partners-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/GVivPGdSW1FYuMOX0I1a" path="/clients/{clientreference}/portfolios" method="get" %}
[financial-partners-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-eff446c2c0094ee59446cf8819d991ce4c1a04a5%2Ffinancial-partners-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/GVivPGdSW1FYuMOX0I1a" path="/{financialPartnerId}/introducers/{introducerId}" method="get" %}
[financial-partners-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-eff446c2c0094ee59446cf8819d991ce4c1a04a5%2Ffinancial-partners-api.json?alt=media)
{% endopenapi %}


# Instruction Batches API Reference

{% openapi src="/files/pCk5uhZ2ni15xTqOIMsr" path="/" method="get" %}
[instruction-batches-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-82c8da25b5ea9a0d98ac1afae8138f267dbd4d1d%2Finstruction-batches-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/pCk5uhZ2ni15xTqOIMsr" path="/{instructionBatchId}/instruction-summary/{instructionFilterType}" method="get" %}
[instruction-batches-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-82c8da25b5ea9a0d98ac1afae8138f267dbd4d1d%2Finstruction-batches-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/pCk5uhZ2ni15xTqOIMsr" path="/{id}/references" method="get" %}
[instruction-batches-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-82c8da25b5ea9a0d98ac1afae8138f267dbd4d1d%2Finstruction-batches-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/pCk5uhZ2ni15xTqOIMsr" path="/batch-update" method="post" %}
[instruction-batches-api.json](https://1771998892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxHwWt7yUAWkmDzwqMjoW%2Fuploads%2Fgit-blob-82c8da25b5ea9a0d98ac1afae8138f267dbd4d1d%2Finstruction-batches-api.json?alt=media)
{% endopenapi %}