Partner API manual

Show our live departures on your websites, and earn on every booking they send. Register a website in your partner dashboard to get started.

1. What you can build

The partner API gives your website live access to our fixed departures: dates, prices, seats left and a link to book. Every link already carries your referral code, so any booking that starts on your website is yours.

There are two ways in, and you can use both on the same website:

  • The widget is a ready-made block you paste into a page. No programming. It runs in your visitors' browsers.
  • The JSON API is for developers. Your server (or your CMS) asks us for the departures and shows them in its own design.

Each of your websites gets its own credentials. If one is lost or leaked, you replace that one and every other website carries on.

2. Quick start

  1. Add the website. In your dashboard, open Websites & API and enter the website address, for example mysite.com. Write only the domain, no page path.
  2. Copy the secret key. It is shown once. We keep only a fingerprint, so we cannot show it again. Lost it? Make a new one (see "Rotating a key").
  3. Prove the website is yours. Do one of the three checks in section 3, then press Check now.
  4. Use it. Paste the widget snippet into a page, or call the API with your key.

Until step 3 is done the website is unverified: nothing is served to it.

3. Proving the website is yours

Each website has its own code. Use any one of these three. Replace CODE with the code shown for your website in the dashboard.

A. A tag on your home page (easiest)

<meta name="hunza-site-verification" content="CODE">

Put it inside the <head> of your home page. Most site builders have a "custom code in head" or "verification tag" box for this.

B. A small file

Make a text file that contains only the code, and make it open at:

https://mysite.com/.well-known/hunza-verify.txt

C. A DNS record

Add a TXT record on your domain (on the domain itself, or on _hunza.mysite.com) with this value:

hunza-site-verification=CODE

DNS can take minutes to hours to spread; the tag and the file are checked at once. You can check up to six times an hour. We only ever look at your public home page and that one file, and only over https.

A domain can be active for one partner at a time. If someone else registered it first, write to us and we will sort it out.

4. Authentication

Send the secret key as a bearer token in the Authorization header. Always call from a server, never from the visitor's browser, so the key stays private. Use https only.

curl "https://hunzaexplorers.com/api/v1/fixed-departures?limit=12" \
  -H "Authorization: Bearer hxk_YOUR_SECRET_KEY"

Some hosts remove the Authorization header before it reaches PHP. If you are one of them, send the same key as X-API-Key: hxk_YOUR_SECRET_KEY instead.

What the domain does

For the widget, the domain is enforced on every request: it only answers when the page is served from your website (or a subdomain of it). The browser itself reports which site the page is on, so another site cannot borrow your widget.

For server calls, a server sends no web address with the request, so the domain cannot be checked each time. Instead, it is proven once (section 3) and the key belongs to that website. For stronger protection, lock the key to your server's IP addresses in the website's settings; a stolen key is then useless anywhere else.

5. The widget (no code needed)

Paste this where the departures should appear. The designer in Website widget builds it for you and shows a live preview.

<div data-hunza-departures data-site="hxs_0123456789abcdef" data-layout="grid" data-limit="6"></div>
<script src="https://hunzaexplorers.com/api/v1/widget.js?v=1794427530" async></script>
AttributeValuesDefault
data-siteYour website's public id (starts with hxs_). Safe to publish.required
data-layoutgrid, list, compact, carousel, featured, grouped (one card per trip with a chip for every date)grid
data-limit1 to 12 trips (grouped: up to 40 dates)6
The widget shows each trip name as a normal link to its page and adds a small "Tours by Hunza Explorers" link in your page's own HTML. These are ordinary followed links (no nofollow), which is the kind of link that helps both of us in search. Please leave them in place.
data-compact1, with the grouped design: leaves out the route line and the booking noteoff
data-themelight, dark, autolight
data-toura tour's slug, to show only that tourall trips
data-accenta colour such as #0d9488teal
data-widgetA saved widget from the dashboard (starts with wgt_). Its design is read from your dashboard each time, so changing it there changes every page that shows it, with nothing to paste again. Use it instead of the other design attributes.none
data-templateYour own design: a selector such as #trip-card for a <template> on your page (see below).none

Saved widgets: change it once, every page updates

In Website widget, design a widget, give it a name and press Save widget. You get a snippet that holds only an id, for example <div data-hunza-departures data-widget="wgt_..."></div>. Save as many as you like and use a different one on each page. Edit a saved widget later and every page that shows it follows within a couple of minutes, with nothing to paste again. Each saved widget shows its live preview in the dashboard once its website is verified. A saved widget works only on the website it was made for.

Your own design

Write the HTML and CSS you want, put it in a <template>, and the widget pours the live departures into it on your page, so your own styles apply. Mark the places with {{names}}; every value is made safe, and addresses are only ever web links.

<div data-hunza-departures data-site="hxs_0123456789abcdef" data-template="#trip-card" data-group="tour"></div>

<template id="trip-card">
  <article class="my-card">
    <img src="{{tour.image}}" alt="{{tour.title}}">
    <h3><a href="{{tour.url}}">{{tour.title}}</a></h3>
    {{#departures}}
      <a class="my-date" href="{{booking_url}}">{{start_date_fmt}} - {{price_fmt}}</a>
    {{/departures}}
  </article>
</template>

<script src="https://hunzaexplorers.com/api/v1/widget.js?v=1794427530" async></script>

Names: title, route, image, url, booking_url, price_from, price, original_price, currency, status, seats_left, start_date, end_date. Add _fmt to a price or date for a ready-to-read form ({{price_fmt}}, {{start_date_fmt}}). With data-group="tour" each entry has {{tour.title}}, {{tour.image}}, {{tour.url}}, {{tour.days}} and a {{#departures}}...{{/departures}} block for its dates. data-limit, data-tour and data-empty (text to show when nothing is open) work too. When the page is drawn the element sends a hunza:rendered event.

Full control in JavaScript

Fetch the data yourself and draw it however you like. The widget script gives you a ready call, or you can read the same JSON straight from the browser (it works from your verified website only; no key is needed, and the key must never go in a web page):

HunzaDepartures.load({ site: "hxs_0123456789abcdef", limit: 12, group: true })
  .then(function (body) { console.log(body.data); });

// or without the script:
fetch("https://hunzaexplorers.com/api/v1/widget/departures?site=hxs_0123456789abcdef&limit=12&group=tour")
  .then(function (r) { return r.json(); });

Calls from your own server use your secret key and the /fixed-departures endpoint below.

The widget draws inside its own sealed box, so your site's styles cannot break it. It never uses cookies. Some builders (for example Wix's "Embed HTML") run code in a separate frame that we cannot match to your website; use their "add custom code to the page" option.

6. Endpoints

Base address: https://hunzaexplorers.com/api/v1. Every endpoint is a GET and answers JSON.

GET /fixed-departures — permission "departures"

ParameterMeaning
limitHow many, 1 to 50. Default 24.
fromOnly departures on or after this date, YYYY-MM-DD.
tourA tour's slug, for one tour only.
grouptour returns one entry per tour with all its dates inside (see below). limit still counts departures. Leave it out for the flat list.
{
  "data": [{
    "id": "fd-2026-12-05-winter-hunza",
    "title": "Winter Hunza",
    "route": "Islamabad to Hunza",
    "start_date": "2026-12-05",
    "end_date": "2026-12-11",
    "duration_days": 7,
    "price_from": 899.0,
    "original_price": 999.0,
    "discount_percent": 10,
    "discount_label": "Early bird",
    "currency": "USD",
    "seats_left": 4,
    "status": "limited",
    "url": "https://hunzaexplorers.com/tour/winter-hunza/?ref=yourcode",
    "image": "https://hunzaexplorers.com/...jpg"
  }],
  "meta": { "updated_at": "2026-11-10T09:00:00Z", "count": 1 }
}

Grouped by tour: ?group=tour

One entry per tour, soonest first, with every date inside. Each date has its own booking_url, already carrying your referral code, so send the traveller to the link of the date they chose.

{
  "data": [{
    "tour": { "slug": "winter-hunza", "title": "Winter Hunza", "image": "https://...jpg", "route": "Islamabad to Hunza", "days": 7, "currency": "USD", "url": "https://hunzaexplorers.com/tour/winter-hunza/?ref=yourcode" },
    "departures": [{
      "id": "fd-2026-12-05-winter-hunza", "start_date": "2026-12-05", "end_date": "2026-12-11",
      "price": 899.0, "original_price": 999.0, "discount_percent": 10, "discount_label": "Early bird",
      "seats_left": 4, "status": "limited",
      "booking_url": "https://hunzaexplorers.com/tour/winter-hunza/?ref=yourcode&date=2026-12-05"
    }]
  }],
  "meta": { "count": 1, "grouped_by": "tour", "updated_at": "2026-11-10T09:00:00Z" }
}

status is open, limited (a few seats left) or full. Prices are the price a traveller really pays for that departure. Private and cancelled departures are never listed. Some fields are null when they do not apply. Read fields by name and ignore any you do not know: we may add more over time.

GET /referrals — permission "referrals"

Your own bookings and what they earned: booking value, rate, commission and status. Never who booked.

GET /me — any key

Tells you which website a key belongs to, what it may do, when it expires and its rate limit. A good first call to test a connection.

{ "data": {
  "site": { "id": "hxs_...", "label": "My blog", "domain": "mysite.com", "status": "active", "verified": true },
  "scopes": ["widget", "departures", "referrals"],
  "rate_limit": { "per_minute": 60 } } }

GET /openapi.json — public

This whole API as an OpenAPI 3 file. Import it into Postman or Insomnia, or generate a client library in your language.

7. Limits, caching and good manners

A website can make 60 requests a minute by default. Every answer says where you stand:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1762768860   (unix time when the minute ends)
X-Request-Id: req_3f9c2a1b7d4e5a60

Over the limit you get 429 and a Retry-After header (seconds). Departures are live: every answer reflects the seats and dates at that moment, and nothing is held back for you. Send the ETag you last received back as If-None-Match, and an unchanged list costs a tiny 304 with no body, so asking on every page view is fine. If you do keep a copy, keep it for a minute or two at most. The browser widget refreshes itself every minute while a page is open

8. Errors

Errors are JSON with a stable code to program against, a human error message, and a request_id to quote to us.

HTTP/1.1 403 Forbidden
{ "error": "This key is not allowed to use \"referrals\".", "code": "insufficient_scope", "request_id": "req_3f9c2a1b7d4e5a60" }
HTTPcodeMeaningWhat to do
400bad_requestA parameter is malformed (a date, a tour slug, a limit).Read the message; it names the parameter.
401invalid_keyThe key is missing, wrong, or revoked. We answer the same way for all three on purpose.Check the Authorization header. Rotate the key if you lost it.
401key_replacedThis key was switched off (a new one was made, or it was published by mistake). The message says when.Copy the current key from Websites & API.
401key_expiredThe key reached its expiry date.Rotate the key in your dashboard.
403site_not_activeThe website is still unverified, or was suspended.Finish the ownership check in your dashboard, or write to us.
403ip_not_allowedThe key is locked to server addresses and this request came from another one.Call from the registered server, or edit the allowed addresses.
403insufficient_scopeThe key may not use this endpoint.Tick the permission for the website in your dashboard.
429rate_limitedToo many requests this minute.Wait for the Retry-After seconds, and reuse the last answer meanwhile.
500server_errorSomething failed on our side.Retry after a moment. If it persists, quote the request_id to us.

9. Code examples

PHP

<?php
$ch = curl_init('https://hunzaexplorers.com/api/v1/fixed-departures?limit=12');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('HUNZA_KEY')],
]);
$body = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) === 200) {
    foreach (json_decode($body, true)['data'] as $d) {
        echo $d['title'], ' ', $d['start_date'], ' ', $d['url'], "\n";
    }
}

Node.js (18 or later)

const res = await fetch('https://hunzaexplorers.com/api/v1/fixed-departures?limit=12', {
  headers: { Authorization: `Bearer ${process.env.HUNZA_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).code);
const { data } = await res.json();
data.forEach(d => console.log(d.title, d.start_date, d.url));

Python

import os, requests

r = requests.get('https://hunzaexplorers.com/api/v1/fixed-departures', params={'limit': 12},
                 headers={'Authorization': 'Bearer ' + os.environ['HUNZA_KEY']}, timeout=10)
r.raise_for_status()
for d in r.json()['data']:
    print(d['title'], d['start_date'], d['url'])

Keep the key in an environment variable or your host's secrets, never in the page source or in a public code repository.

10. Connecting a CMS or booking system

Systems that ask for an "API address" and a "token" (for example another tour operator's admin) take these two values:

API addresshttps://hunzaexplorers.com/api/v1/fixed-departures
TokenThe secret key of that website (starts with hxk_)
Refresh15 minutes is plenty

Use a separate website entry, and so a separate key, for every system you connect. You can then see which one is busy, and switch one off without touching the others.

11. Looking after your keys

  • Rotating. "Make a new key" gives a new secret. The old one keeps working for 24 hours, so you can change it over without downtime. After that it stops.
  • Revoking. "Remove website" stops that website's key and widget at once. Other websites are not affected.
  • Lock to servers. Add your server's IP addresses and the key only works from them.
  • Permissions. Give each website only what it needs. A public page needs only "widget"; an accounting tool only "referrals".
  • Leaked? Make a new key, then remove the old one straight away from the website's page.

12. Troubleshooting

The widget shows nothing
Open your dashboard: each website shows the last address that was refused. If it is not your domain (for example a staging copy, or a site builder's preview address), add it as an extra address of the website.
401 invalid_key
The key is wrong or was removed. Check for a space or line break pasted with it.
403 site_not_active
The ownership check is not finished. Press "Check now" after adding the tag, file or DNS record.
Check keeps failing
Open the tag or file address in a private browser window. It must open without a login, over https, and the code must match exactly.
429 rate_limited
You ask too often. Reuse the last answer for a minute and send If-None-Match.
Still stuck
Write to us and include the request_id from the answer.