Welcome! How can we help?
Open navigation

Passports

Avatar
Locomote Support
Follow

Passports are the key to travel, especially internationally. Without a valid identification record, you won't get far and within the Locomote Corporate Travel Platform, this is no different.

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 Passport cannot exist without being associated to a user, as this it is profile data. 

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

Using the API, we can retrieve a list of passports setup for a specific user via the GET function. We can also create (POST) without requiring a specific passport id/code. Using the "find all" function (GET) we can identify specific passport 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 Passports

Get Passports

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

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

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 Passports 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}/passports
No request fields required for GET

Example Response

Status Code: 200 - OK

{
 "data": [
 {
 "id": "147797b9-c5b2-402c-b4f0-3c774db0b446",
 "type": "passports",
 "attributes": {
 "number": "*****5432",
 "issuing_country": "AU",
 "nationality": "AU",
 "expiry_date": "2027-06-01",
 "effective_date": "2017-06-01",
 "date_of_birth": "1988-10-30"
 }
 },
 {
 "id": "13b4170c-f8b5-497d-ba87-c93a912fecf2",
 "type": "passports",
 "attributes": {
 "number": "*****233A",
 "issuing_country": "NZ",
 "nationality": "NZ",
 "expiry_date": "2026-09-25",
 "effective_date": "2016-09-25",
 "date_of_birth": "1987-06-30"
 }
 }
 ],

Response Fields

Field Name Description Valid Values
id Identifier used to reference a given record Read only 
type Type of resource passports
number User's unique passport 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
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)
date_of_birth Date of user's birth YYYY-MM-DD

 

Create Passports

Create a new passports resource

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

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}/passports
{
 "data": {
 "type": "passports",
 "attributes": {
 "number": "22244678M",
 "issuing_country": "US",
 "nationality": "US",
 "expiry_date": "2028-03-09",
 "effective_date": "2018-03-09",
 "date_of_birth": "1988-10-30"
 }
 }
}

Example Response

Status code 201 - Created

{
 "data": {
 "id": "d1f4d10a-1fa9-40ef-9355-cac8f4bb3733",
 "type": "passports",
 "attributes": {
 "number": "*****678M",
 "issuing_country": "US",
 "nationality": "US",
 "expiry_date": "2028-03-09",
 "effective_date": "2018-03-09",
 "date_of_birth": "1988-10-30"
 }
 },

Response Fields

Field Name Description Valid Values
id Identifier used to reference a given record Read only 
type* Type of resource passports
number* User's unique passport 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
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)
date_of_birth* Date of user's birth YYYY-MM-DD

Remember

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

 

 

Single Passports

Get a Passport

Get a single "passports" resource

GET https://locomotetmp.com/api/users/{work_employee_id}/passports{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}/passports{id}
No request fields required for GET

Example Response

Status Code: 200 - OK

{
 "data": {
 "id": "13b4170c-f8b5-497d-ba87-c93a912fecf2",
 "type": "passports",
 "attributes": {
 "number": "*****233A",
 "issuing_country": "NZ",
 "nationality": "NZ",
 "expiry_date": "2026-09-25",
 "effective_date": "2016-09-25",
 "date_of_birth": "1987-06-30"
 }
 },

Response Fields

Field Name Description Valid Values
id Identifier used to reference a given record Read only 
type Type of resource passports
number User's unique passport 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
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)
date_of_birth Date of user's birth YYYY-MM-DD

 

Update a Passport

Update a "passports" resource

PATCH https://locomotetmp.com/api/users/{work_employee_id}/passports{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}/passports{id}
{
 "data": {
 "id": "13b4170c-f8b5-497d-ba87-c93a912fecf2",
 "type": "passports",
 "attributes": {
 "issuing_country": "GB",
 "nationality": "GB",
 "expiry_date": "2029-01-01",
 "effective_date": "2019-01-01"
 }
 }
}

Example Response

Status Code: 200 - OK

{
 "data": {
 "id": "13b4170c-f8b5-497d-ba87-c93a912fecf2",
 "type": "passports",
 "attributes": {
 "number": "*****233A",
 "issuing_country": "GB",
 "nationality": "GB",
 "expiry_date": "2029-01-01",
 "effective_date": "2019-01-01",
 "date_of_birth": "1987-06-30"
 }
 },

Response Fields

Field Name Description Valid Values
id* Identifier used to reference a given record Read only 
type* Type of resource passports
number User's unique passport 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
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)
date_of_birth Date of user's birth YYYY-MM-DD

 

Delete a Passport

Delete a "passports" resource

DELETE https://locomotetmp.com/api/users/{work_employee_id}/passports{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}/passports{id}
No request fields required for GET

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 Passport

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. 

 

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.

Related articles