Requirements API FAQs

The following pages contain some of the frequently asked questions and standard troubleshooting guides for issues around integrating the Sherpa° API.

What are all your endpoints and what methods do they use?

Sherpa° currently as part of our Requirements API currently have below endpoints available to use with methods listed below

EndPoint NameMethod UtilizedDescription
TripsPOSTThe trips endpoint is our most up to date and is a starting area we highly recommend for all customers to review. This endpoint has been developed from a traveler's journey perspective.
RestrictionsGETOur restrictions endpoint allows customers to dive deeper into our dataset. It is possible to get restrictions that apply for vaccinated or unvaccinated traveller's, restrictions filtered based on countries or categories.
ProceduresGETOur procedures endpoint allows customers to dive deeper into our dataset. It is possible to get procedures that apply for vaccinated or unvaccinated traveller's, restrictions filtered based on countries or categories. Our VISA information is also displayed as procedures in our data.
CountriesGETOur Countries endpoint presents data from a country overview, data based on specific countries as an example can be reviewed using this.
RegionsGET
PlacesGETPlaces endpoint provides PCR testing and testing location information.

Restrictions / Procedures Severity Ratings

The list below clarifies the different severity ratings across Sherpa°'s Restrictions and Procedures.

🚧

Severity Ranking

Severity ratings are primarily used for our Map Element to colour countries based on the originating country

We look primarily at the categories only for restrictions and include in procedures the enforcement.

Restrictions
No Entry/Exit → 5
Restricted → 1
No Restrictions → 0

Procedures
No Quarantine/Covid test → 0
Everything else goes by enforcement
Mandatory → 3
May Be Required/Optional → 1
Recommended/Not Required → 0
Quarantine procedure (May Be Required) → 0

API Rate Limit and Response Size Limitation

All our API endpoints currently impose a rate limit of 100 requests/second. In a scenario where the rate limit will hinder a particular business case, please get in touch with our support team to review and partner with you in creating a solution. We have a hard physical limit of 10 MB for response size. We highly recommend at present to chunk data where possible.

Below is an example scenario :

Use Case: I want to utilize the /restriction endpoint to get all available restrictions on your database for review, but I get a 500 error when making the request.

Solution: It would be advisable to utilize the filter[countries] to chunk the data and, for each request, get restrictions for a set of 25-50 countries.

Sherpa API HTTP Error Codes

While trying out the Sherpa API endpoints, there are scenarios where errors could come up due to misplaced keywords, typos and/or wrong keys. We have collected a few common errors related to the Sherpa API platform below.

Error CodesDescription
400Validation error, bad request, likely due to missing expected input, misspelled keyword or invalid token/key.
401Unauthorized, likely when you attempt to access the endpoint without a registered id/key.
403Permission denied, probably due to (incorrect) affiliate ID / Key used on the wrong platform
404Not found. The current request is not defined by this API. Likely due to a wrong or misspelled endpoint address.
500Internal Server Error, usually due to missing internal parameters
502Bad gateway, usually happens when the server connection is terminated due to timeout or very large size of response data.

Can Sherpa data be cached via API?

Yes, data via our API is cachable. Our /Trips endpoint utilizes the POST method and has cache-control set in our headers with value as public, max-age =3600 seconds

843

Can we request multiple languages in one API request?

Our API at present does not support this. Our supported languages are available here, we will display only the requested language in the response.

How can I get a list of countries supported by Sherpa for the API?

If a country code is passed that we do not support, an error response with the status code 400 Bad Request is returned. The list of errors contains a list of valid alpha2 and alpha3 country codes, below is an example of the code sample returned

{
    "meta": {
        "copyright": "Sherpa",
        "version": "2.7.1"
    },
    "errors": [
        {
            "status": "400",
            "title": "ValidationError",
            "detail": "child \"countryId\" fails because [\"countryId\" must be one of [AF, AFG, AL, ALB, AQ, ATA, DZ, DZA, AS, ASM, AD, AND, AO, AGO, AG, ATG, AZ, AZE, AR, ARG, AU, AUS, AT, AUT, BS, BHS, BH, BHR, BD, BGD, AM, ARM, BB, BRB, BE, BEL, BM, BMU, BT, BTN, BO, BOL, BA, BIH, BW, BWA, BV, BVT, BR, BRA, BZ, BLZ, IO, IOT, SB, SLB, VG, VGB, BN, BRN, BG, BGR, MM, MMR, BI, BDI, BY, BLR, KH, KHM, CM, CMR, CA, CAN, CV, CPV, KY, CYM, CF, CAF, LK, LKA, TD, TCD, CL, CHL, CN, CHN, TW, TWN, CX, CXR, CC, CCK, CO, COL, KM, COM, YT, MYT, CG, COG, CD, COD, CK, COK, CR, CRI, HR, HRV, CU, CUB, CY, CYP, CZ, CZE, BJ, BEN, DK, DNK, DM, DMA, DO, DOM, EC, ECU, SV, SLV, GQ, GNQ, ET, ETH, ER, ERI, EE, EST, FO, FRO, FK, FLK, GS, SGS, FJ, FJI, FI, FIN, AX, ALA, FR, FRA, GF, GUF, PF, PYF, TF, ATF, DJ, DJI, GA, GAB, GE, GEO, GM, GMB, PS, PSE, DE, DEU, GH, GHA, GI, GIB, KI, KIR, GR, GRC, GL, GRL, GD, GRD, GP, GLP, GU, GUM, GT, GTM, GN, GIN, GY, GUY, HT, HTI, HM, HMD, VA, VAT, HN, HND, HK, HKG, HU, HUN, IS, ISL, IN, IND, ID, IDN, IR, IRN, IQ, IRQ, IE, IRL, IL, ISR, IT, ITA, CI, CIV, JM, JAM, JP, JPN, KZ, KAZ, RK, RKS, JO, JOR, KE, KEN, KP, PRK, KR, KOR, KW, KWT, KG, KGZ, LA, LAO, LB, LBN, LS, LSO, LV, LVA, LR, LBR, LY, LBY, LI, LIE, LT, LTU, LU, LUX, MO, MAC, MG, MDG, MW, MWI, MY, MYS, MV, MDV, ML, MLI, MT, MLT, MQ, MTQ, MR, MRT, MU, MUS, MX, MEX, MC, MCO, MN, MNG, MD, MDA, ME, MNE, MS, MSR, MA, MAR, MZ, MOZ, OM, OMN, NA, NAM, NR, NRU, NP, NPL, NL, NLD, CW, CUW, AW, ABW, SX, SXM, BQ, BES, NC, NCL, VU, VUT, NZ, NZL, NI, NIC, NE, NER, NG, NGA, NU, NIU, NF, NFK, NO, NOR, MP, MNP, UM, UMI, FM, FSM, MH, MHL, PW, PLW, PK, PAK, PA, PAN, PG, PNG, PY, PRY, PE, PER, PH, PHL, PN, PCN, PL, POL, PT, PRT, GW, GNB, TL, TLS, PR, PRI, QA, QAT, RE, REU, RO, ROU, RU, RUS, RW, RWA, BL, BLM, SH, SHN, KN, KNA, AI, AIA, LC, LCA, MF, MAF, PM, SPM, VC, VCT, SM, SMR, ST, STP, SA, SAU, SN, SEN, RS, SRB, SC, SYC, SL, SLE, SG, SGP, SK, SVK, VN, VNM, SI, SVN, SO, SOM, ZA, ZAF, ZW, ZWE, ES, ESP, SS, SSD, SD, SDN, EH, ESH, SR, SUR, SJ, SJM, SZ, SWZ, SE, SWE, CH, CHE, SY, SYR, TJ, TJK, TH, THA, TG, TGO, TK, TKL, TO, TON, TT, TTO, AE, ARE, TN, TUN, TR, TUR, TM, TKM, TC, TCA, TV, TUV, UG, UGA, UA, UKR, MK, MKD, EG, EGY, GB, GBR, GG, GGY, JE, JEY, IM, IMN, TZ, TZA, US, USA, VI, VIR, BF, BFA, UY, URY, UZ, UZB, VE, VEN, WF, WLF, WS, WSM, YE, YEM, ZM, ZMB]]"
        }
    ]
}

What timezone are restrictions/procedures stored in for your API?

All restrictions and procedure data are stored in UTC in our database.

Is there a list of countries for which you do not have travel restriction information?

You can find this list by visiting our WebApp map here, where you can select the Unknown filter in the bottom right of the page. This filter will open a window that shows you the names of all countries for which we do not currently have travel restriction information.

Below is the current list

743 743 748

Why are country attributes different? Why is the country's code sometimes in isoAlpha3 or countryCode, and sometimes just code?

323

The keys differ between procedures depending on what entities are being described. If you look at the TYPE, you will see we use "isoAlpha3" for the COUNTRY entities, "countryCode" within REGION entities (states, provinces, etc.), and "code" for NATIONALITY entities. The plan is to bring these all in line with each other in version 3 of the product.

Certain airports are not on your list. What is the process to get these airports added in for us?

We highly suggest passing country code instead of airport code where possible. The end-users will receive the exact travel requirements. If the passing of country code does not meet your business requirements, we add airports to our database on a bi-monthly basis. If there is a list of airports your traveller's visit that isn't supported by sherpa°, please reach out to your account lead with a list and the airport three-letter codes with some traffic data for review by our product team.

For our API solution, if Sherpa° does not support an airport code, the below error message is displayed

859

Please note the segment points to the entry in the request which is not supported.

What are your supported headers for API request?

Our WebApp and trip element solutions utilize our /trips endpoint. Our /trips endpoint followed the POST method and below is a list of headers in the options message:

access-control-allow-headers: x-sherpa-deviceId,DNT,User-Agent,X-User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,sfdc_stack_depth

A CORS error will be visible in the console and network tabs if any custom headers are added to the request. It is recommended to remove any custom headers.

Can you provide a list of possible documentTypes for Sherpa visa procedures?

For documentTypes available documentTypes are

documentTypes
E_VISA
VISA
ETA
EMBASSY_VISA

For visa procedures below list applies

Visa Procedures
Electronic travel authorization
Electronic visitor visa
Visitor visa
ESTA
Visa on arrival
Visa not required

What regions do sherpa° cover with COVID-19 test providers for /Providers endpoint?

We have partnerships with test providers covering >100 countries across Africa, Asia, Europe, Oceania, North America, and South America. Based on their trip, we can serve provider recommendations to 95% of sherpa° users.

Which COVID-19 test providers do sherpa° partner with for /Providers endpoint?

As of April 19, 2022, sherpa°’s COVID-19 testing partners include Collinson, Cue Health, Eurofins, and Test for Travel. If you have a relationship with a test provider that you want to be added to our platform, let us know!

What if I want to add another COVID-19 test provider for /Providers endpoint?

We are always open to adding new providers to our platform. Sherpa° cares that providers are reputable, and will deliver a positive experience for all travellers. If you have a provider in mind, let us know!

Can I pick and choose which providers are shown for /Providers endpoint?

At this time, we do not allow partners to pick and choose which providers are shown. For each search, we offer all providers that service the relevant region for that trip. On the API side, additional business logic can be introduced by partners not to show specific provider data.