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

# 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.md)                           |
| **Product**             | A savings product offered by a financial institution (fixed term, instant access, or notice)                                                  | [Products API](/apis/products.md)                        |
| **Product Issue**       | A specific version/tranche of a product with its own rate and limits                                                                          | [Products API](/apis/products.md)                        |
| **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.md) |
| **Portfolio**           | A client's collection of deposit accounts and their balances                                                                                  | [Portfolios API](/apis/portfolios.md)                    |
| **InstructionBatch**    | A set of instructions for the next working day. You update once a day to signal settlement                                                    | [Instruction Batches API](/apis/instruction-batches.md)  |

### How They Relate

<figure><img src="/files/VCYc1ekYMXznyz2zMXgs" 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="/files/H2ZbO6pF1IrIUk6yNih9" 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.md) - Create and manage clients
* [Product Catalog API](/apis/products.md) - Browse available products
* [Instruction Request API](/apis/instruction-requests.md) - Submit and track instructions
* [Portfolios API](/apis/portfolios.md) - View client portfolio positions
* [Instruction Batches API](/apis/instruction-batches.md) - View and manage settlement batches