Trips Endpoint Request Reference

Example Request

Below you will find an example request to the Trips endpoint of the Sherpa Requirements API.

A request can be separated into two parts. The query and the body. See the Query and Body sections for more information about how they should look and what parameters must be included in each.

Query Parameters

Below is an example query using the Trips endpoint:
https://requirements-api.sandbox.joinsherpa.com/v2/trips?affiliateId=YOUR_AFFILIATE_ID&key=YOUR_API_KEY&language=en-US&include=restriction,procedure

❗️

Note:

This example uses the Sherpa Sandbox.

When using a Production API key, please use the following URL instead:
https://requirements-api.joinsherpa.com

Parameter

Type

Description

affiliateId

string

Your organization’s unique affiliate ID as provided by Sherpa.

key

string

Your organization’s unique API key as provided by Sherpa.

language

string

The desired language for the response data.

See Language Support for a list of supported languages and their respective codes.

include

string

Comma-separated list of desired results to include in the response.

Possible values:
restriction
procedure

We recommend including both for the most complete picture of the travel requirements for a given trip.

Body Parameters

The body of the request is the JSON payload containing the specifics of the trip you are defining. Use the following format to ensure the request is able to be interpreted correctly.

{
    "data": {
        "type": "TRIP",
        "attributes": {
            "category": "ROUND_TRIP",
            "travellers": [{
                "vaccinations": [{
                    "type": "COVID-19",
                    "status": "FULLY_VACCINATED"
                }],
                "nationality": "CAN"
            }],
            "segments": [
                {
                    "segmentType": "OUTBOUND",
                    "segmentSubType": "TRANSIT",// <---- only the segment travelling to the connection 
                    "origin": {                 //       location gets the segementSubType of TRANSIT
                        "countryCode": "CAN",
                        "regionCode": "CA-ON",// <---- all 3 parameter can be included but only the 
                        "airportCode": "YYZ"  //       most specific is technically necessary 
                    },
                    "destination": {
                        "countryCode": "USA"
                    },
                    "travelMode": "AIR",
                    "departureDate": "2022-07-22",
                    "departureTime": "12:59",
                    "arrivalDate": "2022-07-22",
                    "arrivalTime": "12:59"
                },
                {
                    "segmentType": "OUTBOUND",
                    "origin": {
                        "countryCode": "USA"
                    },
                    "destination": {
                        "countryCode": "MEX"
                    },
                    "travelMode": "AIR",
                    "departureDate": "2022-07-22",
                    "departureTime": "12:59",
                    "arrivalDate": "2022-07-22",
                    "arrivalTime": "12:59"
                }
                {
                    "segmentType": "RETURN",
                    "origin": {
                        "countryCode": "MEX"
                    },
                    "destination": {
                        "airportCode": "YYZ"// <---- countryCode and/or regionCode not necessary if 
                    },                     //        if airportCode us used 
                    "travelMode": "AIR",
                    "departureDate": "2022-07-27",
                    "departureTime": "12:59",
                    "arrivalDate": "2022-07-27",
                    "arrivalTime": "12:59"
                }
            ]
        }
    }
}

Parameter

Type

Description

type

string

TRIP

category

string

Describes the type of trip being created.

Possible values:
ROUND_TRIP
: Includes both OUTBOUND and RETURN segments.
ONE_WAY_TRIP:
Includes only OUTBOUND segments.

travellers

array

A list of travellers. See Traveller Model.

segments

array

A list of segments. See Segment Model.

Segment Model

Each Segment of a trip can be described using the following model.

Parameter

Type

Description

segmentType

string

Describes the type of the trip segment.

Possible values:
OUTBOUND:
Travelling towards the final destination.
RETURN:
Travelling back from the final destination.

segmentSubType

string

Only used for the segment where the connecting location is the destination.

The segment from the connecting location to the final destination does not need this parameter.

Possible values:
TRANSIT: Used for layovers/connections.

origin

object

Describes the origin location for this segment. See Location Model.

destination

object

Describes the destination location for this segment. See Location Model.

travelMode

string

Possible values:
AIR
LAND
SEA

departureDate

string

Date of departure from the segment origin in YYYY-MM-DD format.

departureTime

string

Time of departure from the segment origin in HH:MM format.

arrivalDate

string

Date of arrival at the segment destination in YYYY-MM-DD format.

arrivalTime

string

Time of arrival at the segment destination in HH:MM format.

Traveller Model

Each traveller on a trip can be described using the following model.

Parameter

Type

Description

vaccinations

string

Describes the traveller’s current vaccinations. See Vaccination Model.

nationality

string

The ISO-3 country code for the traveller’s passport.

Vaccination Model

A traveller’s vaccinations can be described using the following model.

Parameter

Type

Description

type

string

The type of vaccination.

Possible values:
COVID-19

status

string

The status of the vaccination.

Possible values:
FULLY_VACCINATED
NOT_VACCINATED

Location Model

Segment origin or destination locations can be described using the following model.

Parameter

Type

Description

countryCode

string

The ISO-3 code for the desired country (e.g. CAN, USA).

regionCode

string

The code for the desired region (e.g. CA-ON, US-NY).

airportCode

string

The code for the desired airport (e.g. YYZ, JFK).

❗️

Note:

Only the most specific parameter is necessary when defining a location.

If you want to define a segment origin as a particular airport, you do not need to include the countryCode or regionCode, only the airportCode as it is the most specific parameter.


Did this page help you?