> 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


---

# 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/getting-started.md?ask=<question>&goal=<endgoal>
```

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