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