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

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

Response (200 OK):

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

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

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