Employee Groups are the groups that define how we categorise a set/sets of employees. By using Employee Groups to organise a company in a functional and orderly way, we unlock the potential to specify certain workflows relevant to travellers/arrangers within the Locomote Corporate Travel Platform.

Employee Groups be setup at a company level by the company administrator, to ensure that reflects their own company configuration. For example, we can use role-based employee groups to help separate all Travel Arrangers into one group, all Authorisers into another and all Company Administrators into another. By default, an All Employees group will be set, as an Employee Group is required to book travel via workflows.

Using the API, we can retrieve a list of groups setup for the company via the GET function. We can also create (POST) without requiring a specific code. Using the "find all" function (GET) we can identify a specific group code(s) and either update (PATCH) or remove (DELETE). When specifying a relationship to Employee Groups, PATCH & DELETE options are available for the relationship. And just in case we mistakenly delete the record, we can get it back using a different URL to restore (POST).

Secured by auth_token.

Authorisation via "X-USER-USERNAME" and "X-USER-TOKEN"

All Employee Groups

Get Employee Groups

Get a list of employee_groups resources

GET https://locomotetmp.com/api/employee_groups

Request Parameters

Parameter Name	Description	Required	Valid Values
page[number]	The page number to fetch	No	Any Integer
page[size]	The number of items that appear on each page	No	Any Integer

Example Request

curl -i -H X-USER_TOKEN\:\ [your API key] -H X-USER-USERNAME\:\ [Company Admin email] -H Content-Type\:\ application/json -XGET https\://[your subdomain].locomotetmp.com/api/employee_groups/

No request fields required for GET

Example Response

Status Code: 200 - OK

{
 "data": [
 { 
 "id": "T01234",
 "type": "employee_groups",
 "attributes": {
 "code": "T01234",
 "name": "TEST01"
 },
 "relationships": {
 "role_filter": {
 "data": {
 "id": "traveller",
 "type": "roles"
 }
 }
 }
 },
 {
 "id": "AUTHGROUP",
 "type": "employee_groups",
 "attributes": {
 "code": "AUTHGROUP",
 "name": "authgroup"
 },
 "relationships": {
 "role_filter": {
 "data": {
 "id": "authoriser",
 "type": "roles"
 }
 }
 }
 },

Response Fields

Field Name	Description	Valid Values
`id`	Identifier used to reference a given record	Read only
`type`	Type of resource	employee_groups
`code`	Unique identifier of the Employee Group	Character length: <= 50 Valid characters: A-z 0-9 %&'()[]*,-./\:_ and whitespace
`name`	Name of the Employee Group	Character length: <= 50 Valid characters: A-z 0-9 %&'()[]*,-./\:_ and whitespace
`id`	Identity of the role	Traveller, Authoriser
`type`	Type of resource	roles

Create Employee Groups

Create a new employee_groups resource

POST https://locomotetmp.com/api/employee_groups

Request Parameters

Parameter Name	Description	Required	Valid Values
page[number]	The page number to fetch	No	Any Integer
page[size]	The number of items that appear on each page	No	Any Integer

Example Request

curl -i -H X-USER_TOKEN\:\ [your API key] -H X-USER-USERNAME\:\ [Company Admin email] -H Content-Type\:\ application/json -XPOST https\://[your subdomain].locomotetmp.com/api/employee_groups/

{
 "data": {
 "type": "employee_groups",
 "attributes": {
 "code": "FIN",
 "name": "Finance"
 },
 "data": {
 "id": "traveller",
 "type": "roles"
 }
 }
 }

Example Response

Status code 201 - Created

{
 "data": {
 "id": "FIN",
 "type": "employee_groups",
 "attributes": {
 "code": "FIN",
 "name": "Finance"
 },
 "relationships": {
 "role_filter": {
 "data": {
 "id": "traveller",
 "type": "roles"
 }
 }
 }
 },

Response Fields

Field Name	Description	Valid Values
`id`	Identifier used to reference a given record	Read only
`type*`	Type of resource	employee_groups
`code*`	Identifier of the Employee Group	Character length: <= 50 Valid characters: A-z 0-9
`name*`	Name of the Employee Group	Character length: <= 50 Valid characters: A-z 0-9 %&'()[]*,-./\:_ and whitespace
`id*`	Identity of the role	Traveller, Authoriser
`type*`	Type of resource	roles

Remember

You don't need the resource id as the system will assign code as the unique identifier record.

Single Employee Group

Get an Employee Group

Get a single "employee_groups" resource

GET https://locomotetmp.com/api/employee_groups{code}

Request Parameters

Parameter Name	Description	Required	Valid Values
page[number]	The page number to fetch	No	Any Integer
page[size]	The number of items that appear on each page	No	Any Integer

Example Request

curl -i -H X-USER_TOKEN\:\ [your API key] -H X-USER-USERNAME\:\ [Company Admin email] -H Content-Type\:\ application/json -XGET https\://[your subdomain].locomotetmp.com/api/employee_groups/{code}

No request fields required for GET

Example Response

Status Code: 200 - OK

{
 "data": {
 "id": "FIN",
 "type": "employee_groups",
 "attributes": {
 "code": "FIN",
 "name": "Finance"
 },
 "relationships": {
 "role_filter": {
 "data": {
 "id": "traveller",
 "type": "roles"
 }
 }
 }
 },

Response Fields

Field Name	Description	Valid Values
`id`	Identifier used to reference a given record	Read only
`type`	Type of resource	employee_groups
`code`	Unique identifier of the Employee Group	Character length: <= 50 Valid characters: A-z 0-9 %&'()[]*,-./\:_ and whitespace
`name`	Name of the Employee Group	Character length: <= 50 Valid characters: A-z 0-9 %&'()[]*,-./\:_ and whitespace
`id`	Identity of the role	Traveller, Authoriser
`type`	Type of resource	roles

Update an Employee Group

Update a "employee_groups" resource

PATCH https://locomotetmp.com/api/employee_groups/{code}

Request Parameters

Parameter Name	Description	Required	Valid Values
page[number]	The page number to fetch	No	Any Integer
page[size]	The number of items that appear on each page	No	Any Integer

Example Request

curl -i -H X-USER_TOKEN\:\ [your API key] -H X-USER-USERNAME\:\ [Company Admin email] -H Content-Type\:\ application/json -XPATCH https\://[your subdomain].locomotetmp.com/api/employee_groups/{code}

{
 "data": {
 "id": "FIN",
 "type": "employee_groups",
 "attributes": {
 "code": "FIN",
 "name": "Accounts"
 },
 "data": {
 "id": "traveller",
 "type": "roles"
 }
 }
 }

Example Response

Status Code: 200 - OK

{
 "data": {
 "id": "FIN",
 "type": "employee_groups",
 "attributes": {
 "code": "FIN",
 "name": "Accounts"
 },
 "data": {
 "id": "traveller",
 "type": "roles"
 }
 }
 }

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type*`	Type of resource	employee_groups
`code*`	Unique identifier of the Employee Group	Character length: <= 50 Valid characters: A-z 0-9 %&'()[]*,-./\:_ and whitespace
`name*`	Name of the Employee Group	Character length: <= 50 Valid characters: A-z 0-9 %&'()[]*,-./\:_ and whitespace
`id*`	Identity of the role	Traveller, Authoriser
`type*`	Type of resource	roles

Delete an Employee Group

Delete a "employee_groups" resource

DELETE https://locomotetmp.com/api/employee_groups/{code}

Request Parameters

Parameter Name	Description	Required	Valid Values
page[number]	The page number to fetch	No	Any Integer
page[size]	The number of items that appear on each page	No	Any Integer

Example Request

curl -i -H X-USER_TOKEN\:\ [your API key] -H X-USER-USERNAME\:\ [Company Admin email] -H Content-Type\:\ application/json -XDELETE https\://[your subdomain].locomotetmp.com/api/employee_groups/{code}

No request fields required for DELETE

Example Response

Status Code: 204 - No content

No body returned for response

Response Fields

No response fields required as no content is returned after deletion.

Remember

You don't need any response fields entered (eg. type, code, name) to delete a record. The unique resource id (or {code}) is already identified in the URL, so the API knows which specific record to delete.

Restore an Employee Group

Restore a single resource

POST https://locomotetmp.com/api/employee_groups/{code}/actions/restore

Request Parameters

Parameter Name	Description	Required	Valid Values
page[number]	The page number to fetch	No	Any Integer
page[size]	The number of items that appear on each page	No	Any Integer

Example Request

curl -i -H X-USER_TOKEN\:\ [your API key] -H X-USER-USERNAME\:\ [Company Admin email] -H Content-Type\:\ application/json -XPOST https\://[your subdomain].locomotetmp.com/api/employee_groups/{code}/actions/restore

No request fields required for RESTORE

Example Response

Status Code: 200 - OK

The resource was successfully restored. The updated resource is returned.

{
 "data": {
 "id": "FIN",
 "type": "employee_groups",
 "attributes": {
 "code": "FIN",
 "name": "Accounts"
 },
 "relationships": {
 "role_filter": {
 "data": {
 "id": "traveller",
 "type": "roles"
 }
 }
 }
 },

Response Fields

Field Name	Description	Valid Values
`type*`	Type of resource	employee_groups
`code*`	Identifier of the Employee Group	Character length: <= 50 Valid characters: A-z 0-9

Need to Know

*= Denotes mandatory field.

Troubleshooting

If you got a response code other than the code listed in the article, please refer to this page.

Employee Groups

All Employee Groups

Get Employee Groups

Request Parameters

Example Request

Example Response

Response Fields

Create Employee Groups

Request Parameters

Example Request

Example Response

Response Fields

Remember

Single Employee Group

Get an Employee Group

Request Parameters

Example Request

Example Response

Response Fields

Update an Employee Group

Request Parameters

Example Request

Example Response

Response Fields

Delete an Employee Group

Request Parameters

Example Request

Example Response

Response Fields

Remember

Restore an Employee Group

Request Parameters

Example Request

Example Response

Response Fields

Need to Know

Troubleshooting

Comments

Related articles