Compliance Recipients

The Compliance Recipients API allows you manage recipient contacts for compliance reports

The Compliance Recipient Resource

Properties

Name
id
Required
Type
integer
Description
Unique identifier for the recipient record
Name
legal_entity_id
Required
Type
integer | null
Description
ID of the legal entity for the recipient
Name
group_id
Required
Type
integer | null
Description
ID of the group for the recipient
Name
dealer_id
Required
Type
integer | null
Description
ID of the dealer for the recipient
Name
recipient_type
Required
Type
string
Description
Changes to this resource will trigger notifications to the recipient. Available recipient types: consumer-duty
Name
user
Required
Type
object
Description
Name
id
Required
Type
integer
Description
Unique ID of the user
Name
username
Required
Type
string
Description
Unique username for the user
Name
recipient_type
Required
Type
string
Description
The type of recipient for this record.
Name
consent
Required
Type
boolean
Description
Indicates the user has given permission to be contacted
Name
primary
Required
Type
boolean
Description
Indicates the user is a primary contact
Name
contact
Required
Type
object
Description
Name
email
Required
Type
string
Description
Email address to be used to send out communications
Name
mobile
Required
Type
string
Description
Phone number to be used to send out SMS communications
Name
permissions
Required
Type
object
Description
Name
email
Required
Type
boolean
Description
A true value indicates the user has given permission to receive communications via email
Name
sms
Required
Type
boolean
Description
A true value indicates the user has given permission to receive communications via SMS
Name
dates
Required
Type
object
Description
Name
created_at
Required
Type
datetime
Description
The date the recipient record was created, represented in YYYY-MM-DD HH:MM:SS format
Name
updated_at
Required
Type
datetime
Description
The date the recipient record was last updated, represented in YYYY-MM-DD HH:MM:SS format
Name
deleted_at
Required
Type
datetime | null
Description
The date the recipient record was deleted, represented in YYYY-MM-DD HH:MM:SS format. Will be set to null if not deleted.

Recipient Resource

{
  "id": 1,
  "legal_entity_id": 2,
  "group_id": 3,
  "dealer_id": 4,
  "user": {
    "id": 5,
    "username": "MEOSSECM"
  },
  "recipient_type": "consumer-duty",
  "consent": true,
  "primary": true,
  "contact": {
    "email": "john.smith@itccompliance.co.uk",
    "mobile": "07777777777"
  },
  "permissions": {
    "email": true,
    "sms": false
  },
  "dates": {
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-02 12:00:00",
    "deleted_at": null
  }
}

GET/v2/recipients

Search Recipients

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

An array of recipient 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 recipient by ID
Name
filters.id.in
Required
Type
array<integer>
Description
Match recipients by multiple IDs
Name
filters.legal_entity_id.equals
Required
Type
integer
Description
Match recipients by legal entity ID
Name
filters.legal_entity_id.in
Required
Type
array<integer>
Description
Match recipients by multiple legal entity IDs
Name
filters.group_id.equals
Required
Type
integer
Description
Match recipients by group ID
Name
filters.group_id.in
Required
Type
array<integer>
Description
Match recipients by multiple group IDs
Name
filters.dealer_id.equals
Required
Type
integer
Description
Match recipients by dealer ID
Name
filters.dealer_id.in
Required
Type
array<integer>
Description
Match recipients by multiple dealer IDs
Name
filters.recipient_type.equals
Required
Type
string
Description
Match recipients by recipient type
Name
filters.recipient_type.in
Required
Type
array<string>
Description
Match recipients by multiple recipient types
Name
filters.user_id.equals
Required
Type
integer
Description
Match recipients by user ID
Name
filters.user_id.in
Required
Type
array<integer>
Description
Match recipients by multiple user IDs
Name
filters.consent.equals
Required
Type
boolean
Description
Match recipients by if they've given permission to be contacted
Name
filters.primary.equals
Required
Type
boolean
Description
Match recipients by if they're a primary contact
Name
filters.username.contains
Required
Type
string
Description
Match recipients by partial username
Name
filters.username.equals
Required
Type
string
Description
Match recipients by username
Name
filters.username.in
Required
Type
array<string>
Description
Match recipients by multiple usernames
Name
filters.email.contains
Required
Type
string
Description
Match recipients by partial email address
Name
filters.email.equals
Required
Type
string
Description
Match recipients by exact email address
Name
filters.email.in
Required
Type
array<string>
Description
Match recipients by multiple exact email addresses
Name
filters.mobile.contains
Required
Type
string
Description
Match recipients by partial mobile number
Name
filters.mobile.equals
Required
Type
string
Description
Match recipients by exact mobile number
Name
filters.mobile.in
Required
Type
array<string>
Description
Match recipients by multiple exact mobile numbers
Name
filters.email_permission.equals
Required
Type
boolean
Description
Match recipients by whether they have given permission to be contacted via email
Name
filters.sms_permission.equals
Required
Type
boolean
Description
Match recipients by whether they have given permission to be contacted via sms
Name
filters.is_deleted.equals
Required
Type
boolean
Description
Match recipients by whether they're deleted or not

Search Ordering

id
legal_entity_id
group_id
dealer_id
user_id
username
email
mobile
consent
primary
created_at / created
updated_at / updated
deleted_at / deleted

Request

GET

/v2/recipients

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())
  ->recipients()
  ->search($search);

Response

{
  "data": [
    {
      "id": 1,
      "legal_entity_id": 2,
      "group_id": 3,
      "dealer_id": 4,
      "user": {
        "id": 5,
        "username": "MEOSSECM"
      },
      "recipient_type": "consumer-duty",
      "consent": true,
      "primary": true,
      "contact": {
        "email": "john.smith@itccompliance.co.uk",
        "mobile": "07777777777"
      },
      "permissions": {
        "email": true,
        "sms": false
      },
      "dates": {
        "created_at": "2024-01-01 00:00:00",
        "updated_at": "2024-01-02 12:00:00",
        "deleted_at": null
      }
    }
  ]
}

GET/v2/recipients/:recipient_id

Retrieve Recipient

Will retrieve a specific recipient record by ID

URL Parameters

Name
recipient_id
Required
required
Type
integer
Description
ID of the recipient to retrieve

Error Codes

Status	Description
404	The requested recipient could not be found

Request

GET

/v2/recipients/:recipient_id

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

private ApexV3SdkInterface $sdk;

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

Response

{
  "data": {
    "id": 1,
    "legal_entity_id": 2,
    "group_id": 3,
    "dealer_id": 4,
    "user": {
      "id": 5,
      "username": "MEOSSECM"
    },
    "recipient_type": "consumer-duty",
    "content": true,
    "primary": true,
    "contact": {
      "email": "john.smith@itccompliance.co.uk",
      "mobile": "07777777777"
    },
    "permissions": {
      "email": true,
      "sms": false
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null
    }
  }
}

POST/v2/recipients

Create Recipient

Create a new single recipient

At least one of legal_entity_id, group_id or dealer_id must be provided.

Payload

Name
legal_entity_id
Required
Type
int | null
Description
ID of the legal entity to attach this recipient to
Name
group_id
Required
Type
int | null
Description
ID of the group to attach this recipient to
Name
dealer_id
Required
Type
int | null
Description
ID of the dealer to attach this recipient to
Name
user_id
Required
required
Type
int
Description
ID of the user to attach this recipient to
Name
recipient_type
Required
required
Type
RecipientTypeEnum
Description
Target resource that triggers communications. Available recipient type: consumer-duty
Name
consent
Required
Type
boolean
Description
Indicates the user has consented to contact. Will default to false if not provided.
Name
primary
Required
Type
boolean
Description
Indicates the user is a primary contact. Will default to false if not provided.
Name
contact
Required
required
Type
array<object>
Description
An array of contact objects. At least one contact method must be provided with permission.
Name
method
Required
required
Type
string
Description
Type of contact. Available values: email, sms
Name
value
Required
required
Type
string
Description
The contactable value. For email, this will be the email address. For SMS, this will be a mobile phone number.
Name
permission
Required
required
Type
bool
Description
Indicates whether the user has given permission to be contacted via this method

Error Codes

Status	Description
404	The requested recipient could not be found
422	The data provided in the payload was invalid. See errors for more details.
422	If `legal_entity_id`, `group_id` and `dealer_id` are all provided as null, or none are provided

Request

POST

/v2/recipients

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

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->recipients()
  ->create([
    'legal_entity_id' => 1,
    'group_id' => 2,
    'dealer_id' => 3,
    'user_id' => 4,
    'recipient_type' => 'consumer-duty',
    'content' => true,
    'primary' => true,
    'contact' => [
      [
        'method' => 'email',
        'value' => 'jane.doe@itccompliance.co.uk',
        'permission' => true,
      ]
    ]
  ]);

Response

{
  "data": {
    "id": 1,
    "legal_entity_id": 2,
    "group_id": 3,
    "dealer_id": 4,
    "user": {
      "id": 5,
      "username": "MEOSSECM"
    },
    "recipient_type": "consumer-duty",
    "contact": {
      "email": "john.smith@itccompliance.co.uk",
      "mobile": "07777777777"
    },
    "permissions": {
      "email": true,
      "sms": false
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null
    }
  }
}

PUT/v2/recipients/:recipient_id

Update Recipient

Updates an existing recipient

Only fields passed in the request will be updated. If a field is not provided, its value will remain unchanged.

URL Parameters

Name
recipient_id
Required
required
Type
integer
Description
ID of the recipient to update

Payload

Name
legal_entity_id
Required
Type
int | null
Description
ID of the legal entity to attach this recipient to
Name
group_id
Required
Type
int | null
Description
ID of the group to attach this recipient to
Name
dealer_id
Required
Type
int | null
Description
ID of the dealer to attach this recipient to
Name
user_id
Required
Type
int
Description
ID of the user to attach this recipient to
Name
consent
Required
Type
boolean
Description
Indicates the user has consented to contact
Name
primary
Required
Type
boolean
Description
Indicates the user is a primary contact
Name
contact
Required
Type
array<object>
Description
An array of contact objects. At least one contact method must be provided with permission if this key is provided in the request.
All existing contact methods will be replaced if the contact key is provided.
Name
method
Required
Type
string
Description
Type of contact. Available values: email, sms
Name
value
Required
Type
string
Description
The contactable value. For email, this will be the email address. For SMS, this will be a mobile phone number.
Name
permission
Required
Type
bool
Description
Indicates whether the user has given permission to be contacted via this method
Name
restore
Required
Type
boolean
Description
If this recipient has been deleted, passing restore: true will restore the recipient. Passing restore: false on an active recipient will not delete them. This property should only be used to restore a previously deleted recipient.

Error Codes

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

Request

PUT

/v2/recipients/:recipient_id

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

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->recipient(1)
  ->update([
    'legal_entity_id' => 1,
    'group_id' => 2,
    'dealer_id' => 3,
    'user_id' => 4,
    'recipient_type' => 'consumer-duty',
    'content' => true,
    'primary' => true,
    'restore' => false,
    'contact' => [
      [
        'method' => 'email',
        'value' => 'jane.doe@itccompliance.co.uk',
        'permission' => true,
      ]
    ]
  ]);

Response

{
  "data": {
    "id": 1,
    "legal_entity_id": 2,
    "group_id": 3,
    "dealer_id": 4,
    "user": {
      "id": 5,
      "username": "MEOSSECM"
    },
    "recipient_type": "consumer-duty",
    "contact": {
      "email": "john.smith@itccompliance.co.uk",
      "mobile": "07777777777"
    },
    "permissions": {
      "email": true,
      "sms": false
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null
    }
  }
}

DELETE/v2/recipients/:recipient_id

Delete Recipient

Deletes an existing recipient

URL Parameters

Name
recipient_id
Required
required
Type
integer
Description
ID of the recipient to delete

Error Codes

Status	Description
404	The requested recipient could not be found

Request

DELETE

/v2/recipients/:recipient_id

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

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->recipient(1)
  ->delete();

Response

{
  "data": {
    "id": 1,
    "legal_entity_id": 2,
    "group_id": 3,
    "dealer_id": 4,
    "user": {
      "id": 5,
      "username": "MEOSSECM"
    },
    "recipient_type": "consumer-duty",
    "contact": {
      "email": "john.smith@itccompliance.co.uk",
      "mobile": "07777777777"
    },
    "permissions": {
      "email": true,
      "sms": false
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": "2024-01-03 00:00:00"
    }
  }
}