API Overview

The HGN External Partner API is a server-to-server REST API for approved agencies and B2B partners. Use it to price trips, register travellers, create orders, and take hosted payments.

All endpoints live under the /api/external/v1 prefix, except the quote: /api/external/v2/reference/quote.

Quote v1 is deprecated — move to v2 by 31 December 2026

POST /api/external/v1/reference/quote stops working after 31 December 2026. Switch to POST /api/external/v2/reference/quote, which takes the traveller's date of birth instead of an age. See Migrating from v1.

Server-to-server only

Partner credentials must never be embedded in a browser, mobile app, or any client you do not control. Call this API from your backend. If you need a front-end booking flow, use the Booking Widget instead.

---

Base URL

Every example in this documentation uses the sandbox host:

https://apitest.himalayanguardian.com/api/external/v1

The production host is issued separately

It is deliberately not published here. Your account manager provides it alongside your live credentials, over WhatsApp or another secure channel.

Keep the base URL in configuration rather than inline in your code, so moving from sandbox to live is a config change and not a code edit. See Environments for every sandbox host.

Payment gateway browser callbacks use a separate path, /api/external/payment/response. That endpoint exists for gateway redirects only — your systems never call it directly. See Payments.

---

The booking flow

A complete booking is five calls. Steps 2 and 3 are independent, so you can run them in parallel.

sequenceDiagram
    autonumber
    participant P as Your backend
    participant A as HGN API
    participant C as Customer

    P->>A: POST /auth/token
    A-->>P: accessToken

    P->>A: POST /v2/reference/quote
    A-->>P: quoteId, ctgId, totalAmount

    P->>A: POST /documents (avatar, passport, signature)
    A-->>P: documentId x3
    P->>A: POST /travellers
    A-->>P: touristId

    P->>A: POST /orders
    A-->>P: orderRef

    P->>A: POST /orders/{orderRef}/pay
    A-->>P: paymentUrl
    P-->>C: redirect to paymentUrl
    C->>A: completes payment
    A-->>C: redirect to your returnUrl
    P->>A: GET /orders/{orderRef}/payment-status
    A-->>P: paymentStatus

#	Step	Call	You get back
1	Authenticate	POST /auth/token	accessToken
2	Price the trip	POST /v2/reference/quote	quoteId, ctgId, totalAmount
3	Register the traveller	POST /documents then POST /travellers	touristId
4	Create the order	POST /orders	orderRef
5	Take payment	POST /orders/{orderRef}/pay	paymentUrl

The quote response carries everything the order needs — ctgId, quoteId, routeId, and the coverage window — so you never need a second catalogue lookup between quoting and ordering.

Skipping the quote

You can browse GET /reference/ctgs and pick a ctgId directly. Quoting first is recommended: it resolves the correct package for the route, ages, and altitude, and returns the price the customer will actually pay.

---

Endpoint summary

Authentication

Method	Endpoint	Description	Auth
POST	/auth/token	Exchange partner credentials for a bearer token	—

Reference data and quoting

Method	Endpoint	Description	Auth
GET	/reference/ctgs	List the active public package catalogue	Required
GET	/reference/routes	List active trekking routes	Required
POST	/v2/reference/quote	Price a trip from a date of birth	Required
POST	/reference/quote	Deprecated, stops 31 Dec 2026. Price a trip from an age	Required

Travellers and orders

Method	Endpoint	Description	Auth
POST	/documents	Upload a draft traveller document	Required
POST	/travellers	Create 1–50 travellers	Required
GET	/travellers	List travellers you have registered	Required
POST	/orders	Create one order or a grouped batch	Required
GET	/orders/{orderIdentifier}	Fetch order details	Required

Fixed-value fields on POST /v2/reference/quote and POST /travellers — nationality, gender, blood group, ID type, and the health self-declaration — are documented on Reference Data, which is not an endpoint itself.

Payments

Method	Endpoint	Description	Auth
POST	/orders/{orderRef}/pay	Start a hosted online payment	Required
GET	/orders/{orderRef}/payment-status	Read the latest payment status	Required

Promo codes

Method	Endpoint	Description	Auth
POST	/orders/{orderRef}/promo/preview	Preview a code against one order	Required
POST	/orders/{orderRef}/promo	Apply a code to one unpaid order	Required
DELETE	/orders/{orderRef}/promo	Remove a code from one unpaid order	Required
POST	/orders/groups/{groupRef}/promo/preview	Preview a code across a batch	Required
POST	/orders/groups/{groupRef}/promo	Apply a code across a batch	Required
DELETE	/orders/groups/{groupRef}/promo	Remove a code across a batch	Required

---

Response format

Successful responses are wrapped in a standard envelope.

{
  "success": true,
  "message": "Quote generated successfully",
  "data": {},
  "timestamp": "2026-07-07T03:30:00Z"
}

Field	Type	Description
success	Boolean	true on success
message	String	Human-readable summary. Do not branch on this value
data	Object	The endpoint payload — the part you care about
timestamp	String	ISO-8601 instant, UTC

Never branch on message

message is for humans and logs. It is not part of the contract and can change without a version bump. Branch on the HTTP status code, and on fields inside data.

Errors do not always use this envelope — authentication failures, rate-limit (429) responses and validation failures have different shapes. See Errors.

---

Conventions

Dates and times

Kind	Format	Example	Notes
Date	YYYY-MM-DD	2026-10-01	Nepal business dates. Coverage windows are inclusive of both start and end date
Timestamp	ISO-8601 instant, UTC	2026-07-07T03:30:00Z	Returned in timestamp and audit fields

Identifiers

Most resources are identified by UUID. Orders additionally carry human-readable references:

Identifier	Shape	Example
Order reference	ORD-<year>-<seq>	ORD-2026-000058
Order number	ORDN-<year>-<seq>	ORDN-2026-000058
Group reference	GRP-<year>-<seq>	GRP-2026-000012
Payment reference	<orderRef or groupRef>-<epochMillis>	ORD-2026-000247-1786524461302

Endpoints that take an {orderRef} accept an order reference, order number, or the order UUID. The payment endpoints (/pay, /payment-status) also accept a payment reference; other endpoints do not. A group reference is only accepted by the /orders/groups/{groupRef}/... endpoints. A payment reference is not an order reference — see Payments for the one case where the distinction matters.

Pagination

List endpoints share the same query parameters.

Parameter	Type	Default	Notes
page	Integer	0	Zero-based
size	Integer	20	Capped at 100. Larger values are clamped, not rejected
sortBy	String	Varies	See each endpoint
sortDir	String	Varies	asc or desc. Any value other than desc sorts ascending

Every paginated data payload contains a content array plus page metadata. Read the array from content and drive your loop off the returned totals rather than assuming a page count.

Two page envelopes are in use

GET /reference/routes returns a slightly different pagination envelope from the other list endpoints. Both expose content; the surrounding metadata field names differ. Code defensively if you write one shared pagination helper.

Rate limits

Requests are rate limited per credential: by default 300 per minute and 5,000 per hour. POST /auth/token runs before you have a token, so it is limited per IP at half that rate.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 with Retry-After (seconds); wait that long before retrying. See Errors.

---

Versioning

The API version is in the path (/v1). Breaking changes ship as a new path segment; additive changes — new fields, new optional parameters, new endpoints — ship within v1.

The quote is the first endpoint with a new version: /v2/reference/quote. The old version stays available until its announced sunset and returns Deprecation, Sunset and Link headers meanwhile.

Treat every response object as open: ignore fields you do not recognise rather than failing on them.

The changelog below tracks contract changes.

---

Getting started

1. Request partner credentials from the HGN integrations team.
2. Work through Authentication to get your first token.
3. Follow the end-to-end example for a complete working booking.

---

Other ways to integrate

The API is the most powerful of the three HGN integration approaches, and the only one that needs a development project. If that is more than you need:

	Approach	What it gives you
1	Referral Link	A tracked link on your site. No code, set up in minutes
2	Booking Widget	The booking flow embedded in your own pages

Compare all three →

---

Changelog

This table tracks API contract versions. Documentation for the API was first published on 28 August 2026 — see the portal changelog.

Version	Date	Changes
2.5.0	2026-09-23	Added Reference Data, documenting the value sets behind nationality, gender, bloodGroup, idType, emergencyContactRelation, calling codes, and the health self-declaration. Corrected the nationality, gender, and phone-number examples on POST /travellers to match the values HGN's own apps actually send
2.4.0	2026-09-22	Added quote v2 (/v2/reference/quote, dates of birth). Quote v1 deprecated, sunset 2026-12-31. Quotes return deviceSelectionPricing. Orders reject a traveller whose age on the last covered day is outside the package range
2.3.0	2026-08-24	Added promo preview, apply, and removal on partner orders and batches. salesCompanyPromoCode on the create payload is now promoCode and accepts either promo type
2.2.0	2026-08-12	/pay and /payment-status accept order reference, order number, order UUID, or gateway payment reference. /payment-status now enforces order ownership
2.1.0	2026-08-12	Documented path parameters and the 404 case for GET /orders/{orderRef}/payment-status. Clarified that the gateway payment reference is not an order reference
2.0.0	2026-07-24	External order contracts moved to list-only registered and custom agency fields, with a combined maximum of two
1.0.0	2026-07-07	First published release of the external partner API