Customer Details

The Customer API allows you to search, retrieve and manage customers that use our platforms.

The Customer Resource

Properties

Name
id
Required
Type
integer
Description
Unique identifier for the customer.
Name
deal_id
Required
Type
integer
Description
The ID of the deal this customer is assigned to. Each new deal will create a new customer record, so the same person may have several customer records.
Name
licence_id
Required
Type
integer | null
Description
ID of their driving licence, if a scan has taken place and has been attached to the deal.
Name
name
Required
Type
object
Description
Name
title
Required
Type
string
Description
The customers title. Can be one of Mr, Ms, Miss, Mrs, Madame, Dr, Sir, Lord, Lady, Prof, Rev
Name
forename
Required
Type
string
Description
The customers forename
Name
surname
Required
Type
string
Description
The customers surname
Name
contact_methods
Required
Type
object
Description
Name
email
Required
Type
string | null
Description
The customers contactable email address. The Contact Preferences endpoint should be used to ensure contact is only made via email if the intent is allowed.
Name
home_telephone
Required
Type
string | null
Description
The customers contactable home telephone number. The Contact Preferences endpoint should be used to ensure contact is only made via telephone if the intent is allowed.
Name
mobile_telephone
Required
Type
string | null
Description
The customers contactable mobile telephone number. The Contact Preferences endpoint should be used to ensure contact is only made via telephone or SMS if the intent is allowed.
Name
date_of_birth
Required
Type
date | null
Description
The customers date of birth, if provided. Will be in YYYY-MM-DD format.
Name
portal_confirmed
Required
Type
bool
Description
If true, the customer has been made aware if they have provided a valid email address, they will receive an email with instructions of how to access deal documentation through the Communication portal.
Name
created_at
Required
Type
datetime
Description
The date the role was created, represented in YYYY-MM-DD HH:MM:SS format
Name
updated_at
Required
Type
datetime
Description
The date the role was last updated, represented in YYYY-MM-DD HH:MM:SS format
Name
email_bounced_at
Required
Type
null | datetime
Description
If a valid datetime is returned, communications sent to the customers email address have bounced, and the customer will need to update their email address.

Customer Resource

{
  "id": 1,
  "deal_id": 123456,
  "licence_id": 4492,
  "name": {
    "title": "Miss",
    "forename": "Jane",
    "surname": "Doe"
  },
  "contact_methods": {
    "email": "jane.doe@itccompliance.co.uk",
    "home_telephone": "01234 567890",
    "mobile_telephone": "07777777777",
  },
  "date_of_birth": "1987-11-01",
  "portal_confirmed": true,
  "dates": {
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-02 12:00:00",
    "email_bounced_at": null,
  }
}

GET/v2/customers

Search Customers

The search customers endpoint uses the standard Search package from the SDK.

An array of customer resources are returned. If no results are found, an empty collection is returned.

Search Filters

Name
filters.id.equals
Required
Type
integer
Description
Match a single customer by ID
Name
filters.id.in
Required
Type
array<integer>
Description
Match customers by multiple IDs
Name
filters.deal.equals
Required
Type
integer
Description
Match customer by a deal ID
Name
filters.deal.in
Required
Type
array<integer>
Description
Match customers by multiple deal IDs
Name
filters.licence.equals
Required
Type
integer
Description
Match customer by a licence ID
Name
filters.licence.in
Required
Type
array<integer>
Description
Match customers by multiple licence IDs
Name
filters.first_name.equals
Required
Type
string
Description
Match customers by their first name
Name
filters.first_name.in
Required
Type
array<string>
Description
Match customers by multiple forenames
Name
filters.last_name.equals
Required
Type
string
Description
Match customer by their last name
Name
filters.last_name.in
Required
Type
array<string>
Description
Match customers by multiple surnames
Name
filters.dob.equals
Required
Type
date
Description
Match customers by their date of birth. Must be provided in YYYY-MM-DD format.
Name
filters.telephone.equals
Required
Type
string
Description
Match customers by exact phone number. This can be mobile or home telephone.
Name
filters.email.equals
Required
Type
string
Description
Match customers by an exact email. This may return multiple customers if the customer reuses the same email for multiple deals.
Name
filters.email.in
Required
Type
array<string>
Description
Match customers by multiple email addresses.
Name
filters.email.contains
Required
Type
string
Description
Match customers by a partial email address.
Name
filters.company.equals
Required
Type
string
Description
Match customers by exact company name
Name
filters.company.contains
Required
Type
string
Description
Match customers by partial company name
Name
filters.type.equals
Required
Type
string
Description
Match customers by company type. Can be one of the following values: undefined, private, sole-trader, limited-company, llp, partnership, plc, charity, local-authority. To match explicit non-commercial customers, search for type private.
Name
filters.type.in
Required
Type
array<string>
Description
Match customers by multiple company types.
Name
filters.type.not_equal
Required
Type
string
Description
Match customers, excluding a specific company type.
Name
filters.type.not_in
Required
Type
array<string>
Description
Match customers, excluding a range of company types.

Search Ordering

id
first_name
last_name
email
support_required
deal
licence
created
updated
company
type

Request

GET

/v2/customers

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;
use Compliance\Sdk\Search\Search;

private ApexV3SdkInterface $sdk;

$search = new Search();

$response = $this->sdk
  ->v2(new Machine())
  ->customers()
  ->search($search);

Response

{
  "data": [
    {
      "id": 1,
      "deal_id": 123456,
      "licence_id": 4492,
      "name": {
        "title": "Miss",
        "forename": "Jane",
        "surname": "Doe"
      },
      "contact_methods": {
        "email": "jane.doe@itccompliance.co.uk",
        "home_telephone": "01234 567890",
        "mobile_telephone": "07777777777",
      },
      "date_of_birth": "1987-11-01",
      "portal_confirmed": true,
      "dates": {
        "created_at": "2024-01-01 00:00:00",
        "updated_at": "2024-01-02 12:00:00",
        "email_bounced_at": null,
      }
    }
  ]
}

GET/v2/customers/:customer_id

Retrieve Customer

Will retrieve a single customer by their ID

URL Parameters

Name
customer_id
Required
required
Type
integer
Description
ID of the customer to retrieve

Error Codes

Status	Description
404	The requested customer could not be found.

Request

GET

/v2/customers/:customer_id

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->customer(1)
  ->get();

Response

{
  "data": {
    "id": 1,
    "deal_id": 123456,
    "licence_id": 4492,
    "name": {
      "title": "Miss",
      "forename": "Jane",
      "surname": "Doe"
    },
    "contact_methods": {
      "email": "jane.doe@itccompliance.co.uk",
      "home_telephone": "01234 567890",
      "mobile_telephone": "07777777777",
    },
    "date_of_birth": "1987-11-01",
    "portal_confirmed": true,
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "email_bounced_at": null,
    }
  }
}

PUT/v2/customers/:customer_id

Update Customer

Will attempt to update the customers core details.

Only values provided in the request payload will be updated.

URL Parameters

Name
customer_id
Required
required
Type
integer
Description
ID of the customer to update

Payload

Name
name
Required
Type
object
Description
Name
title
Required
Type
string
Description
Title of the customer. Must be one of Mr, Ms, Miss, Mrs, Madame, Dr, Sir, Lord, Lady, Prof, Rev.
Name
forename
Required
Type
string
Description
The customers forename
Name
surname
Required
Type
string
Description
The customers surname
Name
date_of_birth
Required
Type
date | null
Description
The customers date of birth. If provided, should be in YYYY-MM-DD format.
Name
contact_methods
Required
Type
object
Description
Name
email
Required
Type
string | null
Description
The customers email address.
Name
mobile_telephone
Required
Type
string | null
Description
The customers mobile telephone
Name
home_telephone
Required
Type
string | null
Description
The customers home telephone

Error Codes

Status	Description
404	The requested customer could not be found.
422	The data provided in the payload was invalid. See errors for more details.

Request

PUT

/v2/customers/:customer_id

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->customer(1)
  ->update([
    'name' => [
      'title' => 'Mr',
      'forename' => 'John',
      'surname' => 'Smith',
    ],
    'date_of_birth' => '1987-11-01',
    'contact_methods' => [
      'email' => 'john.smith@itccompliance.co.uk',
      'mobile_telephone' => '07777777777',
      'home_telephone' => '01234 567890',
    ],
  ]);

Response

{
  "data": {
    "id": 1,
    "deal_id": 123456,
    "licence_id": 4492,
    "name": {
      "title": "Miss",
      "forename": "Jane",
      "surname": "Doe"
    },
    "contact_methods": {
      "email": "jane.doe@itccompliance.co.uk",
      "home_telephone": "01234 567890",
      "mobile_telephone": "07777777777",
    },
    "date_of_birth": "1987-11-01",
    "portal_confirmed": true,
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "email_bounced_at": null,
    }
  }
}