Powered by Redocly

Employees

Manage a customer's employees.

Employee

A customer's employee, this can be an employee that doesn't have the ability to log in.

id
string <uuid>

Employee identifier.

contact_point_id
string or null <uuid>

The contact point to use to contact this employee.

correspondence_locale
string <bcp47>

Locale used when sending correspondence (e.g. email) to this employee. Defaults to the locale of the customer. Only supported system locales are allowed.

customer_id
string <uuid>

Reference to the customer to which the employee belongs.

enabled
boolean
Default: true

Whether the employee is enabled. An employee that is not enabled is prohibited from accessing the Customer Portal.

family_name
string <= 255 characters

Family name of the employee.

given_name
string <= 255 characters

Given name of the employee.

username
string or null <email> [ 1 .. 255 ] characters

The username used to authenticate in the Customer Portal. Once set it cannot be unset, only updated.

{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "contact_point_id": "358e50cb-606c-4ce9-bd6a-a72b32481ecc",
  • "correspondence_locale": "en-GB",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "enabled": true,
  • "family_name": "de Jong",
  • "given_name": "Kees",
  • "username": "user@example.com"
}

Retrieve employees

Retrieve a list of all employees.

SecurityOAuth2
Request
query Parameters
customer_id
string <uuid>

Filter employees by customer identifier.

enabled
boolean
Default: true

Filter employees by their enablement status.

limit
integer <int32> [ 0 .. 1000 ]
Default: 25

Limits the amount of resources in result.

offset
integer <int64> >= 0
Default: 0

Offset of resources in result.

Responses
200

Successful response.

Response Schema: application/json
object >= 0 properties

Applied query parameters, including defaults.

enabled
boolean
Default: true

The applied value of the enabled query parameter on the resources in result.

limit
integer <int32> [ 0 .. 1000 ]
Default: 25

The applied value of the limit query parameter on the resources in result.

offset
integer <int64> >= 0
Default: 0

The applied value of the offset query parameter on the resources in result.

property name*
additional property
any
Array of objects (Employee) >= 0 items

List of all employees for all customers.

Array (>= 0 items)
id
string <uuid>

Employee identifier.

contact_point_id
string or null <uuid>

The contact point to use to contact this employee.

correspondence_locale
string <bcp47>

Locale used when sending correspondence (e.g. email) to this employee. Defaults to the locale of the customer. Only supported system locales are allowed.

customer_id
string <uuid>

Reference to the customer to which the employee belongs.

enabled
boolean
Default: true

Whether the employee is enabled. An employee that is not enabled is prohibited from accessing the Customer Portal.

family_name
string <= 255 characters

Family name of the employee.

given_name
string <= 255 characters

Given name of the employee.

username
string or null <email> [ 1 .. 255 ] characters

The username used to authenticate in the Customer Portal. Once set it cannot be unset, only updated.

total
integer <int64>

Total number of resources matching provided query parameters.

default

An error occurred - see status code and problem response for more information.

get/v2/customers/employees
Response samples
application/json
{
  • "query": {
    },
  • "result": [
    ],
  • "total": 3255
}

Add employee

Add a new employee.

SecurityOAuth2
Request
Request Body schema: application/json

The employee you wish to add.

contact_point_id
required
string or null <uuid>

The contact point to use to contact this employee.

correspondence_locale
string <bcp47>

Locale used when sending correspondence (e.g. email) to this employee. Defaults to the locale of the customer. Only supported system locales are allowed.

customer_id
required
string <uuid>

Reference to the customer to which the employee belongs.

family_name
required
string <= 255 characters

Family name of the employee.

given_name
required
string <= 255 characters

Given name of the employee.

username
required
string or null <email> [ 1 .. 255 ] characters

The username used to authenticate in the Customer Portal. Once set it cannot be unset, only updated.

Responses
201

Created.

Response Schema: application/json
id
string <uuid>

Employee identifier.

contact_point_id
string or null <uuid>

The contact point to use to contact this employee.

correspondence_locale
string <bcp47>

Locale used when sending correspondence (e.g. email) to this employee. Defaults to the locale of the customer. Only supported system locales are allowed.

customer_id
string <uuid>

Reference to the customer to which the employee belongs.

enabled
boolean
Default: true

Whether the employee is enabled. An employee that is not enabled is prohibited from accessing the Customer Portal.

family_name
string <= 255 characters

Family name of the employee.

given_name
string <= 255 characters

Given name of the employee.

username
string or null <email> [ 1 .. 255 ] characters

The username used to authenticate in the Customer Portal. Once set it cannot be unset, only updated.

400

Bad request.

default

An error occurred - see status code and problem response for more information.

post/v2/customers/employees
Request samples
application/json
{
  • "contact_point_id": "358e50cb-606c-4ce9-bd6a-a72b32481ecc",
  • "correspondence_locale": "en-GB",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "enabled": true,
  • "family_name": "de Jong",
  • "given_name": "Kees",
  • "username": "user@example.com"
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "contact_point_id": "358e50cb-606c-4ce9-bd6a-a72b32481ecc",
  • "correspondence_locale": "en-GB",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "enabled": true,
  • "family_name": "de Jong",
  • "given_name": "Kees",
  • "username": "user@example.com"
}

Retrieve an employee

Retrieves an employee by its identifier.

SecurityOAuth2
Request
path Parameters
employee-id
required
string <uuid>

The identifier of the employee.

Responses
200

Successful response.

Response Schema: application/json
id
string <uuid>

Employee identifier.

contact_point_id
string or null <uuid>

The contact point to use to contact this employee.

correspondence_locale
string <bcp47>

Locale used when sending correspondence (e.g. email) to this employee. Defaults to the locale of the customer. Only supported system locales are allowed.

customer_id
string <uuid>

Reference to the customer to which the employee belongs.

enabled
boolean
Default: true

Whether the employee is enabled. An employee that is not enabled is prohibited from accessing the Customer Portal.

family_name
string <= 255 characters

Family name of the employee.

given_name
string <= 255 characters

Given name of the employee.

username
string or null <email> [ 1 .. 255 ] characters

The username used to authenticate in the Customer Portal. Once set it cannot be unset, only updated.

default

An error occurred - see status code and problem response for more information.

get/v2/customers/employees/{employee-id}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "contact_point_id": "358e50cb-606c-4ce9-bd6a-a72b32481ecc",
  • "correspondence_locale": "en-GB",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "enabled": true,
  • "family_name": "de Jong",
  • "given_name": "Kees",
  • "username": "user@example.com"
}

Update employee

Update an employee by its identifier.

SecurityOAuth2
Request
path Parameters
employee-id
required
string <uuid>

The identifier of the employee.

Request Body schema: application/json
required

The updated employee.

contact_point_id
required
string or null <uuid>

The contact point to use to contact this employee.

correspondence_locale
string <bcp47>

Locale used when sending correspondence (e.g. email) to this employee. Defaults to the locale of the customer. Only supported system locales are allowed.

enabled
required
boolean
Default: true

Whether the employee is enabled. An employee that is not enabled is prohibited from accessing the Customer Portal.

family_name
required
string <= 255 characters

Family name of the employee.

given_name
required
string <= 255 characters

Given name of the employee.

username
required
string or null <email> [ 1 .. 255 ] characters

The username used to authenticate in the Customer Portal. Once set it cannot be unset, only updated.

Responses
200

Successful response.

Response Schema: application/json
id
string <uuid>

Employee identifier.

contact_point_id
string or null <uuid>

The contact point to use to contact this employee.

correspondence_locale
string <bcp47>

Locale used when sending correspondence (e.g. email) to this employee. Defaults to the locale of the customer. Only supported system locales are allowed.

customer_id
string <uuid>

Reference to the customer to which the employee belongs.

enabled
boolean
Default: true

Whether the employee is enabled. An employee that is not enabled is prohibited from accessing the Customer Portal.

family_name
string <= 255 characters

Family name of the employee.

given_name
string <= 255 characters

Given name of the employee.

username
string or null <email> [ 1 .. 255 ] characters

The username used to authenticate in the Customer Portal. Once set it cannot be unset, only updated.

400

Bad request.

default

An error occurred - see status code and problem response for more information.

put/v2/customers/employees/{employee-id}
Request samples
application/json
{
  • "contact_point_id": "358e50cb-606c-4ce9-bd6a-a72b32481ecc",
  • "correspondence_locale": "en-GB",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "enabled": true,
  • "family_name": "de Jong",
  • "given_name": "Kees",
  • "username": "user@example.com"
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "contact_point_id": "358e50cb-606c-4ce9-bd6a-a72b32481ecc",
  • "correspondence_locale": "en-GB",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "enabled": true,
  • "family_name": "de Jong",
  • "given_name": "Kees",
  • "username": "user@example.com"
}

Remove employee

Remove an employee by its identifier. You can only remove employees without a username.

SecurityOAuth2
Request
path Parameters
employee-id
required
string <uuid>

The identifier of the employee.

Responses
204

Successfully removed.

403

Forbidden.

default

An error occurred - see status code and problem response for more information.

delete/v2/customers/employees/{employee-id}
Response samples
application/problem+json
{
  • "status": 403,
  • "type": "about:blank",
  • "title": "Forbidden",
  • "detail": "You are not authorized to access this resource."
}
➔ Next to Locations