> 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/portfolios.md).

# 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.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/portfolios.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.