Sherpa - Visa and Travel Restrictions API

Sherpa Developer Hub

Welcome to the Sherpa developer hub. We offer a suite of solutions that guides travellers from planning to a safe return home. Take a look at the integration guides, specific use cases and an interactive API Reference. Ready? Let's go.

Guides    API Reference

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.

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 SegmentSegment - A part of a trip between two successive stops. A return trip consists of two segments..

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 ProcedureProcedure - A process imposed by a government, airline or another stakeholder including Quarantine, COVID Testing, Health Declaration and others.s. 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 about a month ago


Document Checklist


Inform travellers about required travel documents like COVID-19 tests and forms.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.