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.

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

Request Body:

{
  "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": "[e-mail]",
  "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):

{
  "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.

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

Request Body:

{
  "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": "[e-mail]",
  "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):

{
  "clientReference": "234256265"
}

---

🔍 3. Get a Client

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

Individual Client

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

Response (200 OK):

{
  "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": "[e-mail]",
  "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

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

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

{
  "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": "[e-mail]"
}

Response: 204 No Content on success.

Update Company

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.