Visas are a form of permission for a non-citizen to enter, transit or remain in a particular country for a specified period of time. Like Passports, they are the documents that keep us safe & identifiable outside of our home borders. On the Locomote Corporate Travel Platform, managing these travel documents and ensuring duty of care is as simple as filling out a few fields from your Visa application to your future destination.

In Locomote, you have the ability to upload all of your travel documents (passports, visas) and manage them within the user profile via the Documents tab. A Visa cannot exist without being associated to a user, as it is profile data.

Visas can be uploaded & managed at a profile level by the Traveller, the Arranger or the Company Administrator.

Using the API, we can retrieve a list of visas setup for a specific user via the GET function. We can also create (POST) without requiring a specific visa id/code. Using the "find all" function (GET) we can identify specific visa id(s) and either update (PATCH) or remove (DELETE). However if we mistakenly delete the record, we are unable to get it back as it will permanently remove the record from the database.

Secured by auth_token.

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

All Visas

Get Visas

Returns all "visas" resources belonging to a "users" resource.

GET https://locomotetmp.com/api/users/{work_employee_id}/visas

Need to Know

This can only be done where a specific Employee ID is used within the URL. Using any command (GET, POST, PATCH, DELETE) for Visas is an added function to the Users endpoint.

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

No request fields required for GET

Example Response

Status Code: 200 - OK

{ "data": [ { "id": "5e93ab7d-32bc-46cc-8e67-a7f369c300ec", "type": "visas", "attributes": { "number": "*****4320", "issuing_country": "US", "nationality": "AU", "type": "esta", "expiry_date": "2020-06-30", "effective_date": "2019-01-01" } }, { "id": "bf48fe11-ff6f-4fec-9caf-1bed54fa7b85", "type": "visas", "attributes": { "number": "*****6441", "issuing_country": "JP", "nationality": "AU", "type": "business", "expiry_date": "2019-12-25", "effective_date": "2018-12-25" } } ], ],

Response Fields

Field Name	Description	Valid Values
`id`	Identifier used to reference a given record	Read only
`type`	Type of resource	visas
`number`	User's unique visas document number	Character length: <= 9 Valid characters: A-z 0-9 "_"
`issuing_country`	Country code	Refer to Country Codes. Character length: 2 (eg. XX) Valid characters: A-Z
`nationality`	Country code	Refer to Country Codes. Character length: 2 (eg. XX) Valid characters: A-Z
`type`	Type of Visa document	APEC, Business, Diplomatic, ESTA, Journalist, Other, Private, Tourist or Transit
`expiry_date`	Date of document expiration	YYYY-MM-DD (expiry_date cannot be before effective_date)
`effective_date`	Date of document issue	YYYY-MM-DD (effective_date cannot be after expiry_date)

Create Visas

Create a Visa for a user

POST https://locomotetmp.com/api/users/{work_employee_id}/visas

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

{ "data": { "type": "visas", "attributes": { "number": "M2244880", "issuing_country": "RU", "nationality": "AU", "type": "tourist", "expiry_date": "2019-06-30", "effective_date": "2018-12-30" }, "relationships": { "user": { "data": { "id": "098765", "type": "users" } } } }}

Example Response

Status code 201 - Created

{ "data": { "id": "6e35afbd-c19d-4bff-818e-19f4653bf151", "type": "visas", "attributes": { "number": "****4880", "issuing_country": "RU", "nationality": "AU", "type": "tourist", "expiry_date": "2019-06-30", "effective_date": "2018-12-30" } },

Response Fields

Field Name	Description	Valid Values
`id`	Identifier used to reference a given record	Read only
`type*`	Type of resource	visas
`number*`	User's unique visas document number	Character length: <= 9 Valid characters: A-z 0-9 "_"
`issuing_country*`	Country code	Refer to Country Codes. Character length: 2 (eg. XX) Valid characters: A-Z
`nationality*`	Country code	Refer to Country Codes. Character length: 2 (eg. XX) Valid characters: A-Z
`type*`	Type of Visa document	APEC, Business, Diplomatic, ESTA, Journalist, Other, Private, Tourist or Transit
`expiry_date*`	Date of document expiration	YYYY-MM-DD (expiry_date cannot be before effective_date)
`effective_date`	Date of document issue	YYYY-MM-DD (effective_date cannot be after expiry_date)

Remember

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

Single Visas

Get a Visa

Get a single "visas" resource

GET https://locomotetmp.com/api/users/{work_employee_id}/visas{id}

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/users/{work_employee_id}/visas{id}

No request fields required for GET

Example Response

Status Code: 200 - OK

{ "data": { "id": "5e93ab7d-32bc-46cc-8e67-a7f369c300ec", "type": "visas", "attributes": { "number": "*****4320", "issuing_country": "US", "nationality": "AU", "type": "esta", "expiry_date": "2020-06-30", "effective_date": "2019-01-01" } },

Response Fields

Field Name	Description	Valid Values
`id`	Identifier used to reference a given record	Read only
`type`	Type of resource	visas
`number`	User's unique visas document number	Character length: <= 9 Valid characters: A-z 0-9 "_"
`issuing_country`	Country code	Refer to Country Codes. Character length: 2 (eg. XX) Valid characters: A-Z
`nationality`	Country code	Refer to Country Codes. Character length: 2 (eg. XX) Valid characters: A-Z
`type`	Type of Visa document	APEC, Business, Diplomatic, ESTA, Journalist, Other, Private, Tourist or Transit
`expiry_date`	Date of document expiration	YYYY-MM-DD (expiry_date cannot be before effective_date)
`effective_date`	Date of document issue	YYYY-MM-DD (effective_date cannot be after expiry_date)

Update a Visa

Update a "visas" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/visas{id}

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}/visas{id}

{ "data": { "id": "6e35afbd-c19d-4bff-818e-19f4653bf151", "type": "visas", "attributes": { "issuing_country": "CN", "nationality": "AU", "type": "diplomatic", "expiry_date": "2020-02-15", "effective_date": "2019-01-15" }, "relationships": { "user": { "data": { "id": "098765", "type": "users" } } }}}

Example Response

Status Code: 200 - OK

{ "data": { "id": "6e35afbd-c19d-4bff-818e-19f4653bf151", "type": "visas", "attributes": { "number": "****4880", "issuing_country": "CN", "nationality": "AU", "type": "diplomatic", "expiry_date": "2020-02-15", "effective_date": "2019-01-15" } },

Response Fields

Field Name	Description	Valid Values
`id*`	Identifier used to reference a given record	Read only
`type*`	Type of resource	visas
`number`	User's unique visas document number	Character length: <= 9 Valid characters: A-z 0-9 "_"
`issuing_country*`	Country code	Refer to Country Codes. Character length: 2 (eg. XX) Valid characters: A-Z
`nationality*`	Country code	Refer to Country Codes. Character length: 2 (eg. XX) Valid characters: A-Z
`type*`	Type of Visa document	APEC, Business, Diplomatic, ESTA, Journalist, Other, Private, Tourist or Transit
`expiry_date*`	Date of document expiration	YYYY-MM-DD (expiry_date cannot be before effective_date)
`effective_date`	Date of document issue	YYYY-MM-DD (effective_date cannot be after expiry_date)

Delete a Visa

Delete a "visas" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/visas{id}

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}/visas{id}

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 Visa

Unfortunately you cannot restore a document (passport, visa etc.) Unlike a resource or user where the record is archived, once it has been deleted, it is removed from the database.

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.