Tutorial: Build Document Checklist
Inform travellers about required travel documents like COVID-19 tests and forms.
This guide explains how to present a list of documents required for a trip. This references our v2 API. For v3 please see this guide here.
Create a Trip
To build the checklist, we will use the trips endpoint for retrieving travel restrictions for a given trip. The information in the payload will include all the required documents as well as links for filling them out.
To use the endpoint, we must describe the trip using Segment.
For our use case we will have a traveller flying from USA to Colombia on February 21, 2021 and returning on February 27th, 2021.
Make a POST request to the trips endpoint, requesting including Procedures. You can request localized content by adding a language query parameter to the request.
curl --location --request POST '<<requirementsApiUrl>>/v2/trips?affiliateId=sherpa&key=<<requirementsApiKey>>&language=en&include=procedure' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
"type": "TRip",
"attributes": {
"category": "ROUND_TRIP",
"segments": [
{
"segmentType": "OUTbOUND",
"origin": {
"countryCode": "USA"
},
"destination": {
"countryCode": "COL"
},
"departureDate": "2021-02-21",
"departureTime": "16:00",
"arrivalDate": "2021-02-21",
"arrivalTime": "21:00"
},
{
"segmentType": "RETURN",
"origin": {
"countryCode": "COL"
},
"destination": {
"countryCode": "USA"
},
"departureDate": "2021-02-27",
"departureTime": "16:00",
"arrivalDate": "2021-02-27",
"arrivalTime": "21:00"
}
]
}
}
}'
Get Response
There are two parts of the return payload that we will need to build the checklist.
Data attributes contains useful information and reference links to the content we will use to render our checklist. The data is split by segments, just like we specified in the request.
For the outbound trip(JFK-CUN), we will use the first segment and its documents attribute.
...
"data": {
"id": "2853cf80-716c-11eb-ad6c-51ba7df186f4",
"type": "TRIP",
"attributes": {
"category": "ROUND_TRIP",
"segments": [
{
"segmentType": "OUTBOUND",
"origin": {
"countryCode": "USA",
"countryName": "United States"
},
"destination": {
"countryCode": "COL",
"countryName": "Colombia"
},
"departureDate": "2021-02-21T00:00:00.000Z",
"departureTime": "16:00",
"arrivalDate": "2021-02-21T00:00:00.000Z",
"arrivalTime": "21:00",
"borderCrossing": "INTERNATIONAL",
"entryRestrictions": [
{
"id": "eaba2cd4-52d2-4167-b7b4-b61cee53c597"
}
],
"travelRestrictions": [
{
"id": "401379e8-4fd5-4112-9d8f-5c0f6aae3f93"
},
{
"id": "4a6b020a-e04b-4bb0-8352-a295f72d1d06"
}
],
"documents": [
{
"id": "551eb1b1-2d37-4aaa-b9f7-cb8e56628a5d"
},
{
"id": "ac193706-7f4b-4184-98d6-a866ebf73fc3"
}
],
"exitRestrictions": [],
"summary": {
"headline": "Most travelers from United States can visit Colombia, but there are restrictions.",
"entryStatus": "PARTIALLY_CLOSED"
}
},
...
The content can be found in the included node of the response payload.
...
{
"id": "ac193706-7f4b-4184-98d6-a866ebf73fc3",
"type": "PROCEDURE",
"attributes": {
"country": "COL",
"title": "Mandatory pre-registration form",
"description": "All travelers are required to fill out a pre-registration form prior to their arrival in Colombia and before their departure from Colombia. It must be filled between 48 hours and 1 hour before departure.",
"directionality": "NO_CHANGE",
"enforcement": "MANDATORY",
"documentType": [
"TRAVEL_AUTHORIZATION"
],
"documentLinks": [
{
"type": "LINK",
"title": "Pre-Registration Form",
"url": "https://apps.migracioncolombia.gov.co/pre-registro/public/preregistro.jsf"
}
],
"more": [
"Travelers will be required to show confirmation of registration before boarding."
],
"tags": [
"international",
"air",
"land",
"sea"
],
"source": {
"sourceType": "GOVERNMENT",
"title": "US Embassy for Colombia",
"url": "https://co.usembassy.gov/covid-19-information/"
},
"lastCheckedAt": "2021-02-05T00:00:00Z",
"lastUpdatedAt": "2021-02-05T20:17:00Z",
"stillCurrentAt": "2021-02-05T00:00:00Z",
"createdAt": "2020-05-29T13:32:00Z",
"startDate": "2020-03-15T00:00:00Z",
"endDate": null,
"category": "DOC_REQUIRED",
"subCategory": "BEFORE_ARRIVAL"
}
}
...
Display Required Documents
Iterate over the documents attribute in the response to present each document in the list. The API provides a helpful list of actions the user can take like filling out an online form or downloading a PDF if one is available.
The actions are available under documentLinks with localized titles.
Associate a link with the action type:
LINK - a link to an external document like an online form or insurance.
DOWNLOAD - a link directly to a PDF or iOS/Play store to download an app.
INSTRUCTION - an instruction may not have a url. For example, "Fill out the form at the airport"
Updated 11 months ago