Departments are a division of an organisation or company that deal with a specific area of activity. As a follow on from Offices & Employee Groups, this can help to organise how a company operates, how employees (or travellers in this case) are managed and how it can be reported on.

Within the Locomote Corporate Travel Platform, a department might be Finance, Travel, Facilities, IT; any department structure that is already utilised within your own company configuration can be replicated in Locomote.

Departments are setup at a company level by the company administrator, to ensure that reflects their own company configuration. By default, a Department is required to be set for a profile to be considered complete & valid.

Departments are a Dependency for Users and share a relationship with Cost Centres.

Using the API, we can retrieve a list of departments 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 specific department code(s) and either update (PATCH) or remove (DELETE). When specifying a relationship to Departments, 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 Departments

Get Departments

Get a list of departments resources

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

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/departments/

No request fields required for GET

Example Response

Status Code: 200 - OK

 { "data": [ { "id": "DEPARTMENT_1", "type": "departments", "attributes": { "code": "DEPARTMENT_1", "name": "Example Department 1" } }, { "id": "DEPARTMENT_2", "type": "departments", "attributes": { "code": "DEPARTMENT_2", "name": "Example Department 2" } } ],

Response Fields

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

Create Departments

Create a new departments resource

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

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/departments/

{ "data": { "type": "departments", "attributes": { "code": "IT", "name": "Technology Department" } } }

Example Response

Status code 201 - Created

{ "data": { "id": "IT", "type": "departments", "attributes": { "code": "IT", "name": "Technology Department" } },

Response Fields

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

Remember

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

Single Departments

Get a Department

Get a single "departments" resource

GET https://locomotetmp.com/api/departments{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/departments/{code}

No request fields required for GET

Example Response

Status Code: 200 - OK

{ "data": { "id": "IT", "type": "departments", "attributes": { "code": "IT", "name": "Technology Department" } },

Response Fields

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

Update a Department

Update a "departments" resource

PATCH https://locomotetmp.com/api/departments/{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/departments/{code}

{ "data": { "id": "IT", "type": "departments", "attributes": { "code": "IT", "name": "Technology & Systems" } }}

Example Response

Status Code: 200 - OK

{ "data": { "id": "IT", "type": "departments", "attributes": { "code": "IT", "name": "Technology & Systems" } },

Response Fields

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

Delete a Department

Delete a "departments" resource

DELETE https://locomotetmp.com/api/departments/{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/departments/{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 a Department

Restore a single resource

POST https://locomotetmp.com/api/departments/{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/departments/{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": "IT", "type": "departments", "attributes": { "code": "IT", "name": "Technology & Systems" } },

Response Fields

Field Name	Description	Valid Values
`type*`	Type of resource	departments
`code*`	Identifier of the Departments	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.