Roles

Roles are our way of identifying what role a user plays within a given organisation, whether that's in ITC, or their dealer roles.

The Role Resource

Properties

Name
id
Required
Type
integer
Description
Unique identifier for the role.
Name
name
Required
Type
string
Description
The user friendly name for the role.
Name
slug
Required
Type
string
Description
The machine friendly name for the role.
Name
description
Required
Type
string
Description
A brief description of the function of this role.
Name
dates.created_at
Required
Type
datetime
Description
The date the role was created, represented in YYYY-MM-DD HH:MM:SS format
Name
dates.updated_at
Required
Type
datetime
Description
The date the role was last updated, represented in YYYY-MM-DD HH:MM:SS format
Name
dates.deleted_at
Required
Type
null | datetime
Description
The date the role was deleted, represented in YYYY-MM-DD HH:MM:SS format. If the role is not deleted, this will be null

Role Resource

{
  "id": 1,
  "name": "Complaints Supervisor",
  "slug": "complaints-supervisor",
  "description": "Manages complaints received from customers, and manages staff who have access to complaints"
  "dates": {
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-02 12:00:00",
    "deleted_at": null,
  }
}

GET/v2/roles

Search Roles

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

An array of role 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 role by ID
Name
filters.id.in
Required
Type
array<integer>
Description
Match roles by multiple IDs
Name
filters.name.equals
Required
Type
string
Description
Match a role by their name
Name
filters.name.in
Required
Type
array<string>
Description
Match roles by multiple names
Name
filters.name.contains
Required
Type
string
Description
Match a role by a partial name
Name
filters.slug.equals
Required
Type
string
Description
Match a role by their slug
Name
filters.slug.in
Required
Type
array<string>
Description
Match roles by multiple slugs
Name
filters.created_at.before_or_on
Required
Type
datetime
Description
Match all roles that were created before or on this datetime.
Name
filters.created_at.after_or_on
Required
Type
datetime
Description
Match all roles that were created after or on this datetime.
Name
filters.updated_at.before_or_on
Required
Type
datetime
Description
Match all roles that were last updated before or on this datetime.
Name
filters.updated_at.after_or_on
Required
Type
datetime
Description
Match all roles that were last updated after or on this datetime.
Name
filters.deleted_at.equals
Required
Type
boolean
Description
If you want to only deleted roles from results, provide true. If you only non-deleted roles, provide false

Search Ordering

id
name
created_at
updated_at
deleted_at

Request

GET

/v2/roles

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

Response

{
  "data": [
    {
      "id": 1,
      "name": "Complaints Supervisor",
      "slug": "complaints-supervisor",
      "description": "Manages complaints received from customers, and manages staff who have access to complaints"
      "dates": {
        "created_at": "2024-01-01 00:00:00",
        "updated_at": "2024-01-02 12:00:00",
        "deleted_at": null,
      }
    }
  ]
}

POST/v2/roles

Create Role

Will attempt to create a new role.

Payload

Name
name
Required
required
Type
string
Description
The user friendly name for this role. A machine friendly slug will automatically be generated.
Name
description
Required
required
Type
string
Description
The brief description of this role.
Name
legacy_type
Required
Type
string | null
Description
The legacy_type mapping for the role. This is the value which maps to one of the columns within the lms.cl_user_id table.

Error Codes

Status	Description
422	The data provided in the payload was invalid. See errors for more details.
422	If the automatically generated slug for that name is already registered, a 422 will be returned.

Request

POST

/v2/roles

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

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->roles()
  ->create([
    'name' => 'New Role Name',
    'description' = 'A new description for this role',
  ]);

Response

{
  "data": {
    "id": 1,
    "name": "New Role Name",
    "slug": "new-role-name",
    "description": "A new description for this role",
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null,
    }
  }
}

GET/v2/roles/:role_id

Retrieve Role

Will retrieve a single role by its ID.

URL Parameters

Name
role_id
Required
required
Type
integer
Description
ID of the role to retrieve

Error Codes

Status	Description
404	The requested role could not be found.

Request

GET

/v2/roles/:role_id

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

private ApexV3SdkInterface $sdk;

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

Response

{
  "data": {
    "id": 1,
    "name": "Complaints Supervisor",
    "slug": "complaints-supervisor",
    "description": "Manages complaints received from customers, and manages staff who have access to complaints"
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null,
    }
  }
}

PUT/v2/roles/:role_id

Update Role

Will attempt to update the roles details.

Only values provided in the request payload will be updated.

URL Parameters

Name
role_id
Required
required
Type
integer
Description
ID of the role to update

Payload

Name
name
Required
Type
string
Description
The updated name for the role. By changing the name, the slug will also be regenerated.
Name
description
Required
Type
string
Description
The updated description for the role
Name
legacy_type
Required
Type
string
Description
The updated legacy_type mapping for the role. This is the value which maps to one of the columns within the lms.cl_user_id table.

Error Codes

Status	Description
404	The requested role could not be found.
422	The data provided in the payload was invalid. See errors for more details.
422	If a new role name is entered, and the slug for that name is already registered, a 422 will be returned.

Request

PUT

/v2/roles/:role_id

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

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->role(1)
  ->update([
    'name' => 'New Role Name',
    'description' = 'A new description for this role',
  ]);

Response

{
  "data": {
    "id": 1,
    "name": "New Role Name",
    "slug": "new-role-name",
    "description": "A new description for this role",
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null,
    }
  }
}

DELETE/v2/roles/:role_id

Delete Role

Will attempt to delete the role. This endpoint will only affect non-deleted roles.

The API will return a successful response if the role is already deleted, but won't update the deleted_at timestamp.

URL Parameters

Name
role_id
Required
required
Type
integer
Description
ID of the role to delete

Error Codes

Status	Description
404	The requested role could not be found.

Request

DELETE

/v2/roles/:role_id

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

private ApexV3SdkInterface $sdk;

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

Response

{
  "data": {
    "id": 1,
    "name": "Complaints Supervisor",
    "slug": "complaints-supervisor",
    "description": "Manages complaints received from customers, and manages staff who have access to complaints"
    "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"
    }
  }
}