🚀Getting Started

This guide covers what you need to begin integrating with our API: environments, authentication, rate limits, and a quick-start walkthrough.

---

🌐 1. Environments

We provide two environments:

Environment	Base URL	Purpose
Sandbox	https://api.sandbox.flagstoneim.com	Development and testing
Production	https://api.flagstoneim.com	Live operations

All API paths are relative to the environment base URL. For example, to list products in sandbox:

GET https://api.sandbox.flagstoneim.com/products/

---

🔑 2. Authentication

You'll need both an API key and an OAuth 2.0 access token for every API call.

See Authentication for full details including token request flows and renewal strategies.

---

⚡ 3. Rate Limits

Each API has its own rate limits based on expected usage. Details are available on request.

If you exceed the rate limit, you'll get a 429 Too Many Requests response. Use exponential backoff in your integration.

---

📋 4. API Versioning

Each API is versioned independently using a date-based scheme in the OpenAPI specification:

API	Version
Client API	2020-08-01
Products API	2022-07-01
Instruction Request API	2021-11-01
Financial Partners API	2020-04-01
Instruction Batches API	-

---

🏁 5. Quick Start - Your First Integration

Follow these four steps to complete a basic end-to-end integration:

Step 1: Create a Client

POST https://api.sandbox.flagstoneim.com/clients/financial-partner
cdpapi-Subscription-Key: your-api-key-here
Content-Type: application/json

{
  "externalReference": "PARTNER-001",
  "title": "Mr",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1985-06-15T00:00:00.0000000+00:00",
  "addressLine1": "10 Downing Street",
  "addressLine2": "",
  "postCode": "SW1A2AA",
  "countryCode": "GBR",
  "phoneNumber": "02071234567",
  "ukResident": true,
  "ukDomicile": true,
  "emailAddress": "[e-mail]",
  "accounts": [
    {
      "accountName": "John Smith",
      "accountNumber": "12345678",
      "sortCode": "200000",
      "currencyCode": "GBP"
    }
  ]
}

Response (201 Created):

{
  "clientReference": "330825e3-a306-4a0f-b722-a6740ec096e6"
}

Step 2: Browse Products

GET https://api.sandbox.flagstoneim.com/products/
cdpapi-Subscription-Key: your-api-key-here

Select a product from the response - note the productId, productIssueNumber, and productIssueVersionNumber.

Step 3: Submit a Deposit Instruction

POST https://api.sandbox.flagstoneim.com/instruction-request/deposit
cdpapi-Subscription-Key: your-api-key-here
Content-Type: application/json

{
  "productReference": "256",
  "productIssueNumber": "1",
  "productIssueVersionNumber": "2",
  "accountReference": "FL1456",
  "amount": 10000,
  "instructionReference": "1429ddc3-987f-4bff-9f34-77d1b98fca21"
}

Response (202 Accepted):

{
  "instructionReference": "1429ddc3-987f-4bff-9f34-77d1b98fca21",
  "statusLocation": "/instruction-request/status/1429ddc3-987f-4bff-9f34-77d1b98fca21"
}

Step 4: Check the Portfolio

GET https://api.sandbox.flagstoneim.com/financial-partners/portfolios?PageNumber=1&PageSize=50
cdpapi-Subscription-Key: your-api-key-here

This returns paged portfolio data showing deposit accounts, balances, and interest information for all your clients.

---

📖 Next Steps

• Core Concepts - Understand the data model and lifecycle

• Client API - Full client onboarding reference

• Product Catalog API - Browse and evaluate products