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