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

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:

GET /financial-partners/portfolios?PageNumber=1&PageSize=50

Paged Response Fields:

{
  "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 - Create and manage clients

• Product Catalog API - Browse available products

• Instruction Request API - Submit and track instructions

• Portfolios API - View client portfolio positions

• Instruction Batches API - View and manage settlement batches