Relationships are an integral part of the Locomote Corporate Travel Platform & they work hand-in-hand with Profile (User) data to ensure the platform is used to it's full potential. Some of these relationships are mandatory, whereas others are set up to mirror that of the company setup and help to ensure the administrator(s) can properly report on what is required with accuracy.

A relationships can be any resource that is linked/associated to a user and/or another resource. Some examples of a User Relationship might be the Cost Centre on a profile, a Role or Employee Group tied to the profile or it could be an Authoriser, First or Second Level Authoriser, a Risk Authoriser or Travel Arranger that is associated with a user. An example of a resource-to-resource relationship is the kind that exists between a Department & Cost Centre.

User Relationships can be updated at a company level by the company administrator, or they can be managed by the allocated Travel Arranger. The User themselves can also edit their own Profile & manage some of these relationships.

Using the Profile (JSON) API, because relationships are a sub-section of a resource (Users), only PATCH & DELETE options are available for the relationship. This can only be done after a specific code or work_employee_id has been specified. In order to find out which record you'd like to target, please refer to the User article on how to GET the code/id required.

Secured by auth_token.

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

Cost Centres

Update User relationship to Cost Centres

Assigns "cost_centres" to a "users" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/relationships/cost_centres

For more information about Cost Centres & the API, please refer to this article.

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/users/{work_employee_id}/relationships/cost_centres

{ "data": [ { "id": "Finance", "type": "cost_centres" }, { "id": "IT Department", "type": "cost_centres" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "Finance", "type": "cost_centres" }, { "id": "IT Department", "type": "cost_centres" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	cost_centres

Need to Know

Unlike other requests like GET or POST, there's no need to enter in the entire profile data. Because the URL is specifically set to target the work_employee_id & the resource (ie. cost_centres) the only thing that needs to be specified is the id (or {code}) of the resource that needs updating.

Delete User relationship to Cost Centres

Removes "cost_centres" from a "users" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/relationships/cost_centres

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/users/{work_employee_id}/relationships/cost_centres

{ "data": [ { "id": "Finance" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "IT Department", "type": "cost_centres" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	cost_centres

Remember

You don't need the resource id as the system will assign code as the unique identifier record. For Users this will be the same as the Employee ID.

Roles

Update User relationship to Roles

Assigns "roles" to a "users" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/relationships/roles

For more information about Roles, please refer to this article.

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/users/{work_employee_id}/relationships/roles

{ "data": [ { "id": "travel_arranger" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "travel_arranger", "type": "roles" }, { "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	roles

Need to Know

Delete User relationship to Roles

Removes "roles" from a "users" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/relationships/roles

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/users/{work_employee_id}/relationships/roles

{ "data": [ { "id": "travel_arranger" } ]}

Example Response

Status Code: 200 - OK

{ "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	roles

Remember

You don't need the resource id as the system will assign code as the unique identifier record. For Users this will be the same as the Employee ID.

Authorisers

Update User relationship to Authorisers

Assigns authorisers to a "users" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/relationships/authorisers

For more information about Authorisers & the API, please refer to this article.

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/users/{work_employee_id}/relationships/authorisers

{ "data": [ { "id": "123456" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "123456", "type": "users" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Need to Know

Delete User relationship to Authorisers

Removes authorisers from a "users" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/relationships/authorisers

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/users/{work_employee_id}/relationships/authorisers

{ "data": [ { "id": "123456" } ]}

Example Response

Status Code: 200 - OK

{ "data": [],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Remember

You don't need the resource id as the system will assign code as the unique identifier record. For Users this will be the same as the Employee ID.

First Level Authorisers

Update User relationship to First Level Authorisers

Assigns first_level_authorisers to a "users" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/relationships/first_level_authorisers

For more information about First Level Authorisers & the API, please refer to this article.

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/users/{work_employee_id}/relationships/first_level_authorisers

{ "data": [ { "id": "123456" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "123456", "type": "users" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Need to Know

Delete User relationship to First Level Authorisers

Removes first_level_authorisers from a "users" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/relationships/first_level_authorisers

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/users/{work_employee_id}/relationships/first_level_authorisers

{ "data": [ { "id": "123456" } ]}

Example Response

Status Code: 200 - OK

{ "data": [],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Remember

You don't need the resource id as the system will assign code as the unique identifier record. For Users this will be the same as the Employee ID.

Second Level Authorisers

Update User relationship to Second Level Authorisers

Assigns second_level_authorisers to a "users" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/relationships/second_level_authorisers

For more information about Second Level Authorisers & the API, please refer to this article.

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/users/{work_employee_id}/relationships/second_level_authorisers

{ "data": [ { "id": "222444" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "222444", "type": "users" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Need to Know

Delete User relationship to Second Level Authorisers

Removes second_level_authorisers from a "users" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/relationships/second_level_authorisers

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/users/{work_employee_id}/relationships/second_level_authorisers

{ "data": [ { "id": "222444" } ]}

Example Response

Status Code: 200 - OK

{ "data": [],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Remember

You don't need the resource id as the system will assign code as the unique identifier record. For Users this will be the same as the Employee ID.

Risk Authorisers

Update User relationship to Risk Authorisers

Assigns risk_authorisers to a "users" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/relationships/risk_authorisers

For more information about Risk Authorisers & the API, please refer to this article.

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/users/{work_employee_id}/relationships/risk_authorisers

{ "data": [ { "id": "000111" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "123456", "type": "users" }, { "id": "000111", "type": "users" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Need to Know

Delete User relationship to Risk Authorisers

Removes risk_authorisers from a "users" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/relationships/risk_authorisers

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/users/{work_employee_id}/relationships/risk_authorisers

{ "data": [ { "id": "000111" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "123456", "type": "users" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Remember

You don't need the resource id as the system will assign code as the unique identifier record. For Users this will be the same as the Employee ID.

Travel Arrangers

Update User relationship to Travel Arrangers

Assigns travel_arrangers to a "users" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/relationships/travel_arrangers

For more information about Travel Arrangers & the API, please refer to this article.

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/users/{work_employee_id}/relationships/travel_arrangers

{ "data": [ { "id": "123456" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "123456", "type": "users" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Need to Know

Delete User relationship to Travel Arrangers

Removes travel_arrangers from a "users" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/relationships/travel_arrangers

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/users/{work_employee_id}/relationships/travel_arrangers

{ "data": [ { "id": "123456", "type": "users" }, ]}

Example Response

Status Code: 200 - OK

{ "data": [],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	users

Remember

You don't need the resource id as the system will assign code as the unique identifier record. For Users this will be the same as the Employee ID.

Employee Groups

Update User relationship to Employee Groups

Assigns "employee_groups" to a "users" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/relationships/employee_groups

For more information about Employee Groups & the API, please refer to this article.

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/users/{work_employee_id}/relationships/employee_groups

{ "data": [ { "id": "FIN", "type": "employee_groups" }, { "id": "IT", "type": "employee_groups" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "FIN", "type": "employee_groups" }, { "id": "IT", "type": "employee_groups" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	employee_groups

Need to Know

Delete User relationship to Employee Groups

Removes "employee_groups" from a "users" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/relationships/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 -XDELETE https\://[your subdomain].locomotetmp.com/api/users/{work_employee_id}/relationships/employee_groups

{ "data": [ { "id": "FIN", "type": "employee_groups" } ]}

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "IT", "type": "employee_groups" } ],

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type`	Type of resource	employee_groups

Remember

You don't need the resource id as the system will assign code as the unique identifier record. For Users this will be the same as the Employee ID.

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.