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.

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¶

ProductionStaging

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

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

Your staging host is issued with your partner credentials.

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 /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 /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`	`/reference/quote`	Price a trip	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

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

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 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`
Payment reference	`<orderRef>-<epochMillis>`	`ORD-2026-000247-1786524461302`

Endpoints that take an {orderRef} accept any of these, plus the order UUID. 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`

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.

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.

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¶

Request partner credentials from the HGN integrations team.
Work through Authentication to get your first token.
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.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