> 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/apis/clients.md).

# Clients

**What it is:** The Client API handles onboarding and management of both individual and company clients on our platform.

Every integration starts here - you must register a client before they can browse products, submit instructions, or hold a portfolio.

**How it works:** You submit client details (name, address, bank account, KYC (Know Your Customer) data) and receive a `clientReference` that identifies the client across all our APIs.

Clients can be updated using optimistic concurrency via their `clientVersion`.

**Base URL:** `https://api.sandbox.flagstoneim.com/clients`

**API Version:** `2020-08-01`

***

## 📋 Endpoints

| Method  | Path                                                           | Description                 |
| ------- | -------------------------------------------------------------- | --------------------------- |
| `POST`  | `/financial-partner`                                           | Create an individual client |
| `POST`  | `/financial-partner/company`                                   | Create a company client     |
| `GET`   | `/{clientReference}`                                           | Get an individual client    |
| `GET`   | `/financial-partner/company/{clientReference}`                 | Get a company client        |
| `PATCH` | `/{clientReference}/{clientVersion}`                           | Update an individual client |
| `PATCH` | `/financial-partner/company/{clientReference}/{clientVersion}` | Update a company client     |

***

## 👤 1. Create an Individual Client

**What it is:** Registers a new individual client on our platform.

**How it works:** Submit the client's personal details, address, bank account, and optional tax obligations.

The API returns a unique `clientReference`.

```http
POST /financial-partner
Content-Type: application/json
cdpapi-Subscription-Key: your-api-key-here
```

**Request Body:**

```json
{
  "externalReference": "GSGEHQ342",
  "title": "Mr",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1985-06-15T00:00:00.0000000+00:00",
  "addressLine1": "213 Greenway",
  "addressLine2": "",
  "city": "Portsmouth",
  "county": "Hampshire",
  "postCode": "PO122AB",
  "countryCode": "GBR",
  "phoneNumber": "01980123654",
  "ukResident": true,
  "ukDomicile": true,
  "emailAddress": "john@example.com",
  "nonUkTaxObligations": [
    {
      "countryCode": "USA",
      "taxIdentificationNumber": "53464643"
    }
  ],
  "accounts": [
    {
      "accountName": "John Smith",
      "accountNumber": "01233234",
      "sortCode": "326487",
      "currencyCode": "GBP"
    }
  ]
}
```

**Required Fields:** `externalReference`, `title`, `firstName`, `lastName`, `dateOfBirth`, `addressLine1`, `addressLine2`, `postCode`, `countryCode`, `emailAddress`

**Response** (201 Created):

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

| Status | Meaning                                                                   |
| ------ | ------------------------------------------------------------------------- |
| `200`  | Client with identical details already exists - returns existing reference |
| `201`  | Client created successfully                                               |
| `400`  | Request is malformed                                                      |
| `409`  | Conflict - e.g. external reference already exists                         |

***

## 🏢 2. Create a Company Client

**What it is:** Registers a new company client on the platform.

**How it works:** Similar to individual clients, but includes company-specific fields like company name, FSCS eligibility, FCA number, and evidence declarations.

```http
POST /financial-partner/company
Content-Type: application/json
cdpapi-Subscription-Key: your-api-key-here
```

**Request Body:**

```json
{
  "externalReference": "71d1fd54-0baa-4356-8637-0eea33675123",
  "companyName": "ABC Limited",
  "fscsEligible": true,
  "fcaNumber": "326487",
  "companyNumber": "1234567",
  "hasEvidenceConfirmingHowMoniesAreHeld": true,
  "doesEntityHaveUnderlyingBeneficiariesWhoMayBeEntitledToFund": true,
  "addressLine1": "213 Greenway",
  "addressLine2": "",
  "city": "Portsmouth",
  "county": "Hampshire",
  "postCode": "PO122AB",
  "countryCode": "GBR",
  "phoneNumber": "01980123654",
  "emailAddress": "js@abc.com",
  "accounts": [
    {
      "accountName": "ABC Limited",
      "accountNumber": "01233234",
      "sortCode": "326487",
      "currencyCode": "GBP"
    }
  ]
}
```

**Required Fields:**

* `externalReference`, `companyName`, `fscsEligible`
* `hasEvidenceConfirmingHowMoniesAreHeld`
* `doesEntityHaveUnderlyingBeneficiariesWhoMayBeEntitledToFund`
* `addressLine1`, `addressLine2`, `postCode`, `countryCode`
* `emailAddress`, `phoneNumber`, `accounts`

**Response** (201 Created):

```json
{
  "clientReference": "234256265"
}
```

***

## 🔍 3. Get a Client

**What it is:** Retrieve the full details of an existing individual or company client.

### Individual Client

```http
GET /{clientReference}
cdpapi-Subscription-Key: your-api-key-here
```

**Response** (200 OK):

```json
{
  "clientReference": "1231455",
  "clientVersion": 3,
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1970-10-21T00:00:00.0000000+00:00",
  "addressLine1": "213 Greenway",
  "city": "Portsmouth",
  "county": "Hampshire",
  "postCode": "PO122AB",
  "countryCode": "GBR",
  "phoneNumber": "01980123654",
  "ukResident": true,
  "ukDomicile": true,
  "emailAddress": "john@example.com",
  "documents": [
    {
      "documentUri": "http://anExampleLink/2",
      "documentType": "driving-license"
    }
  ],
  "nonUkTaxObligations": [
    {
      "countryCode": "USA",
      "taxIdentificationNumber": "53464643"
    }
  ],
  "accounts": [
    {
      "accountName": "John Smith",
      "accountNumber": "01233234",
      "sortCode": "326487",
      "currencyCode": "GBP"
    }
  ]
}
```

### Company Client

```http
GET /financial-partner/company/{clientReference}
cdpapi-Subscription-Key: your-api-key-here
```

Returns company-specific fields including `companyName`, `fscsEligible`, `fcaNumber`, `companyNumber`, and evidence flags.

***

## ✏️ 4. Update a Client

**What it is:** Update the details of an existing client.

**How it works:** Supply the current `clientVersion` in the URL path.

If the version doesn't match the server's current version, the API returns `409 Conflict` to prevent concurrent overwrites.

### Update Individual

```http
PATCH /{clientReference}/{clientVersion}
Content-Type: application/json-patch+json
cdpapi-Subscription-Key: your-api-key-here
```

```json
{
  "title": "Mr",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1985-06-15T00:00:00.0000000+00:00",
  "addressLine1": "214 Greenway",
  "addressLine2": "",
  "postCode": "PO122AB",
  "countryCode": "GBR",
  "phoneNumber": "01980123654",
  "ukResident": true,
  "ukDomicile": true,
  "emailAddress": "john.updated@example.com"
}
```

**Response:** `204 No Content` on success.

### Update Company

```http
PATCH /financial-partner/company/{clientReference}/{clientVersion}
Content-Type: application/json
cdpapi-Subscription-Key: your-api-key-here
```

| Status | Meaning                               |
| ------ | ------------------------------------- |
| `204`  | Update successful                     |
| `400`  | Malformed request                     |
| `404`  | Client not found                      |
| `409`  | Version conflict - re-fetch and retry |

***

## 📖 Full API Reference

For the complete OpenAPI specification including all schemas and field descriptions, see the [Client API Reference](/api-reference/client-api-ref.md).


---

# 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/apis/clients.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.