> 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
* 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:**
### 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
---
# 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/core-concepts.md?ask=&goal=
```
`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.