> 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/getting-started.md).

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

```http
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](/authentication.md) 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

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

```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": "john.smith@example.com",
  "accounts": [
    {
      "accountName": "John Smith",
      "accountNumber": "12345678",
      "sortCode": "200000",
      "currencyCode": "GBP"
    }
  ]
}
```

**Response** (201 Created):

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

### Step 2: Browse Products

```http
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

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

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

**Response** (202 Accepted):

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

### Step 4: Check the Portfolio

```http
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](/core-concepts.md) - Understand the data model and lifecycle
* [Client API](/apis/clients.md) - Full client onboarding reference
* [Product Catalog API](/apis/products.md) - Browse and evaluate products