GAMAN API

Ship Updates. Not Headaches.

GAMAN is the travel-booking API platform built for agents and OTAs who move fast. One API for authentication, organization management, and flight search & booking — with hotels on the way.

🚀

Deploy with confidence

A single, consistent REST API for authentication, org management, and flight booking — no juggling multiple systems.

🔒

Secure by default

Every request is authenticated with a Bearer token, and wallet operations are validated against your organization's balance in real time.

🎯

Full organization control

Manage sub-agents, wallets, markup packages, and audit logs — all scoped cleanly to your organization.

📊

Clear, predictable responses

Every endpoint returns the same success / data / error shape, so integration stays simple from day one.

Get Started → Explore Flights API ⬡ Import Postman Collection

Base URL: https://staging.gaman.co.in

How to read this documentation: the left sidebar is organized by section (Organization, Flights, Hotels, etc.). Each endpoint shows its HTTP method and path, a plain-English explanation of every field, and a real JSON example for both the request and the response.

Authentication

All endpoints (except login) require a Bearer token in the header:

Authorization: Bearer <access_token>

Login (Org User)

POST /api/v1/auth/login Request:

{
  "agent_id": "GAMDEMO0001",
  "username": "admin",
  "password": "OrgAdmin@123"
}

Success Response (200):

{
  "success": true,
  "message": "login successful",
  "data": {
    "user": {
      "id": "11111111-1111-1111-1111-111111111111",
      "username": "admin",
      "email": "admin@demo.com",
      "name": "Demo Admin",
      "role": "org_admin",
      "status": "active",
      "org_id": "9551fa77-16ad-4df5-9284-dc23cb95c237",
      "sub_agent_id": "GAMDEMO0002"
    },
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
      "expires_in_seconds": 3600
    },
    "agent_id": "GAMDEMO0001"
  }
}

Field Reference:

Field	Description
`user.id`	Unique ID of the logged-in user.
`user.role`	Permission level: `org_admin` (full org access) or `agent` (restricted, self-scoped access).
`user.org_id`	ID of the organization this user belongs to.
`user.sub_agent_id`	Human-readable agent code used in some org endpoints (e.g. wallet topup).
`tokens.access_token`	Short-lived JWT. Send it as `Authorization: Bearer <access_token>` on every subsequent request.
`tokens.refresh_token`	Long-lived token used to obtain a new access token once it expires.
`tokens.expires_in_seconds`	How long the access token stays valid, in seconds (3600 = 1 hour).
`agent_id`	Public-facing agency code for the organization (e.g. shown on invoices).

Error Response (401):

{
  "success": false,
  "error": "invalid credentials"
}

Organization Profile

Get Organization Profile

GET /api/v1/org/profile Success Response (200):

{
  "success": true,
  "message": "profile retrieved",
  "data": {
    "id": "9551fa77-16ad-4df5-9284-dc23cb95c237",
    "agent_id": "GAMDEMO0001",
    "name": "Demo Travel Agency",
    "slug": "demo-travel",
    "email": "org@demo.com",
    "phone": "+91 9876543210",
    "address": "123 Main Street, Mumbai",
    "country": "IN",
    "subscription_type": "full",
    "status": "active",
    "ip_whitelist_enabled": false,
    "wallet": {
      "id": "11111111-1111-1111-1111-111111111110",
      "balance": 100000,
      "currency": "INR",
      "credit_limit": 0,
      "is_active": true
    }
  }
}

Field Reference:

Field	Description
`agent_id`	Public agency/organization code (e.g. shown to sub-agents and on documents).
`slug`	URL-friendly identifier for the organization.
`subscription_type`	Plan tier the org is on (e.g. `full`).
`status`	Organization state — `active` or `suspended`.
`ip_whitelist_enabled`	If `true`, only requests from whitelisted IPs are accepted for this org.
`wallet.balance`	Current available wallet balance for the organization.
`wallet.credit_limit`	Additional credit the org can spend beyond its balance (0 = no credit line).
`wallet.is_active`	Whether the wallet can currently be used for transactions.

Update Organization Profile

PUT /api/v1/org/profile Request:

{
  "name": "Demo Travel Agency",
  "email": "org@demo.com",
  "phone": "+91 9876543210",
  "address": "123 Main Street, Mumbai",
  "country": "IN"
}

Success Response (200):

{
  "success": true,
  "message": "profile updated"
}

Organization Settings

Get Settings

GET /api/v1/org/settings Success Response (200):

{
  "success": true,
  "message": "settings retrieved",
  "data": [
    {
      "key": "allow_agent_registration",
      "value": "true",
      "org_id": "9551fa77-16ad-4df5-9284-dc23cb95c237"
    }
  ]
}

Update Setting

PUT /api/v1/org/settings Request:

{
  "key": "allow_agent_registration",
  "value": "true"
}

Success Response (200):

{
  "success": true,
  "message": "setting updated"
}

Users Management

List Users

GET /api/v1/org/users

Query Parameters: page, per_page, role (org_admin | agent), status (active | suspended).

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": "5b920162-500f-474f-8e7a-5f131053a7d5",
      "username": "testagent",
      "email": "agent@demo.com",
      "name": "Test Agent",
      "role": "agent",
      "status": "active",
      "created_at": "2026-04-10T14:47:58.251295+05:30"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1
  }
}

Field Reference:

Field	Description
`role`	`org_admin` can manage the whole org (users, wallet, packages, audit logs); `agent` is limited to their own bookings, wallet, and profile.
`status`	`active` or `suspended`. Suspended users cannot log in.
`meta.page` / `per_page`	Current page number and page size used for pagination.
`meta.total` / `total_pages`	Total matching records, and total number of pages available.

Create User

POST /api/v1/org/users Request:

{
  "email": "agent@demo.com",
  "name": "Test Agent",
  "username": "testagent",
  "password": "Agent@123",
  "role": "agent"
}

Valid Roles: org_admin, agent. Optional field: phone.

Success Response (200):

{
  "success": true,
  "message": "user created",
  "data": {
    "id": "5b920162-500f-474f-8e7a-5f131053a7d5",
    "username": "testagent",
    "email": "agent@demo.com",
    "name": "Test Agent",
    "role": "agent",
    "status": "active",
    "org_id": "9551fa77-16ad-4df5-9284-dc23cb95c237",
    "sub_agent_id": "GAMWE0VFZSA"
  }
}

Get User by ID

GET /api/v1/org/users/:id Success Response (200):

{
  "success": true,
  "data": {
    "id": "5b920162-500f-474f-8e7a-5f131053a7d5",
    "username": "testagent",
    "email": "agent@demo.com",
    "name": "Test Agent",
    "role": "agent",
    "status": "active",
    "created_at": "2026-04-10T14:47:58.251295+05:30"
  }
}

Update User

PUT /api/v1/org/users/:id Request:

{
  "name": "Updated Name",
  "phone": "+919999999999",
  "status": "active"
}

All fields optional. Valid status values: active, suspended.

Success Response (200):

{
  "success": true,
  "message": "user updated",
  "data": {
    "id": "5b920162-500f-474f-8e7a-5f131053a7d5",
    "username": "testagent",
    "email": "new@demo.com",
    "name": "Updated Name",
    "phone": "+919999999999",
    "role": "agent",
    "status": "active"
  }
}

Delete User

DELETE /api/v1/org/users/:id Success Response (200):

{
  "success": true,
  "message": "user deleted"
}

Suspend User

PUT /api/v1/org/users/:id/suspend Success Response (200):

{
  "success": true,
  "message": "user suspended"
}

Activate User

PUT /api/v1/org/users/:id/activate Success Response (200):

{
  "success": true,
  "message": "user activated"
}

Organization Wallet

Get Organization Wallet

GET /api/v1/org/wallet Success Response (200):

{
  "success": true,
  "message": "wallet retrieved",
  "data": {
    "id": "11111111-1111-1111-1111-111111111110",
    "owner_id": "9551fa77-16ad-4df5-9284-dc23cb95c237",
    "owner_type": "org",
    "balance": 100000,
    "currency": "INR",
    "credit_limit": 0,
    "is_active": true
  }
}

Field Reference:

Field	Description
`owner_type`	Who owns this wallet — `org` (the organization) or `user` (an individual agent).
`balance`	Current spendable funds in the wallet's currency.
`credit_limit`	Extra credit allowed beyond the balance before bookings are blocked (0 = none).
`is_active`	If `false`, the wallet cannot be used to pay for bookings.

Get Wallet Transactions

GET /api/v1/org/wallet/transactions?page=1&per_page=20

Returns the org wallet's transaction history with optional filters. Each entry records a debit when the admin allocated funds to an agent, or a credit when the super admin topped up.

Query Parameters:

Parameter	Type	Description
`page`	int	Page number (default: 1).
`per_page`	int	Results per page, max 100 (default: 20).
`type`	string	Filter by transaction type — `credit` or `debit`.
`ref_type`	string	Filter by reference type — `topup`, `booking`, `refund`, `deduction`.
`from`	date	Start date filter (YYYY-MM-DD).
`to`	date	End date filter (YYYY-MM-DD).
`min_amount`	float	Minimum transaction amount.
`max_amount`	float	Maximum transaction amount.
`search`	string	Search keyword in description (case-insensitive).

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": "c5f3a2b1-1111-2222-3333-444444444444",
      "created_at": "2026-04-15T10:00:00.000000+05:30",
      "updated_at": "2026-04-15T10:00:00.000000+05:30",
      "wallet_id": "11111111-1111-1111-1111-111111111110",
      "type": "debit",
      "amount": 5000,
      "balance_before": 105000,
      "balance_after": 100000,
      "ref_type": "topup",
      "ref_id": "550e8400-e29b-41d4-a716-446655440001",
      "description": "allocated to agent: flight testing credits",
      "performed_by": "5b920162-500f-474f-8e7a-5f131053a7d5",
      "agent_id": "550e8400-e29b-41d4-a716-446655440001",
      "agent_name": "John Smith"
    },
    {
      "id": "d6e4b3c2-2222-3333-4444-555555555555",
      "created_at": "2026-04-14T15:30:00.000000+05:30",
      "updated_at": "2026-04-14T15:30:00.000000+05:30",
      "wallet_id": "11111111-1111-1111-1111-111111111110",
      "type": "credit",
      "amount": 50000,
      "balance_before": 55000,
      "balance_after": 105000,
      "ref_type": "topup",
      "ref_id": null,
      "description": "org wallet topup by super admin",
      "performed_by": "00000000-0000-0000-0000-000000000001"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 15,
    "total_pages": 1
  }
}

Field Reference:

Field	Description
`type`	`debit` (funds deducted from the org wallet when allocating to an agent) or `credit` (funds added, e.g. super-admin topup to org, or a refund).
`wallet_id`	The org wallet's unique identifier — all transactions in this list share the same wallet.
`amount`	Transaction amount in INR.
`balance_before` / `balance_after`	Org wallet balance immediately before and after the transaction.
`ref_type`	Reason code — `topup` (allocation to/from agent), `booking` (flight booking), `refund`, or `deduction`.
`ref_id`	Optional reference to a related entity (e.g. booking reference). `null` for topups.
`description`	Human-readable note — `"allocated to agent: <reason>"` for admin-to-agent topups, or `"org wallet topup by super admin"` when SA adds funds.
`performed_by`	User ID of the admin (org admin or super admin) who performed the action.
`agent_id`	If this transaction is an agent allocation, the agent's UUID. `omitted` for non-allocation transactions.
`agent_name`	Agent's display name. `omitted` for non-allocation transactions.

Get Wallet Summary

GET /api/v1/org/wallet/summary

Dashboard-style summary of the org wallet: current balance, monthly activity, agent allocation totals, and a 30-day balance trend.

Success Response (200):

{
  "success": true,
  "message": "wallet summary retrieved",
  "data": {
    "current_balance": 100000.00,
    "credit_limit": 0,
    "available_balance": 100000.00,
    "total_allocated_to_agents": 45000.00,
    "agent_count": 5,
    "this_month": {
      "total_credits": 50000.00,
      "total_debits": 25000.00,
      "net_change": 25000.00,
      "transaction_count": 8
    },
    "balance_trend": [
      { "date": "2026-07-01", "balance": 100000.00 },
      { "date": "2026-07-08", "balance": 95000.00 },
      { "date": "2026-07-15", "balance": 90000.00 },
      { "date": "2026-07-22", "balance": 98000.00 },
      { "date": "2026-07-28", "balance": 100000.00 }
    ]
  }
}

Field Reference:

Field	Description
`current_balance`	Current org wallet balance.
`available_balance`	`balance + credit_limit` — total spendable funds.
`total_allocated_to_agents`	Sum of all allocated balances across agents in the org.
`agent_count`	Number of agents in the org.
`this_month`	Aggregated credit/debit totals for the current calendar month.
`balance_trend`	Daily closing balance for the last 30 days (useful for charts).

List Agents

GET /api/v1/org/wallet/agents

Lists all agents in the org with their allocated balances and last allocation date.

Success Response (200):

{
  "success": true,
  "message": "agents retrieved",
  "data": [
    {
      "agent_id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "John Smith",
      "username": "jsmith",
      "allocated_balance": 15000.00,
      "total_allocated_to_date": 15000.00,
      "last_allocation": "2026-07-25T09:00:00Z",
      "is_active": true
    },
    {
      "agent_id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Jane Doe",
      "username": "jdoe",
      "allocated_balance": 5000.00,
      "total_allocated_to_date": 5000.00,
      "last_allocation": "",
      "is_active": true
    }
  ]
}

Field Reference:

Field	Description
`agent_id`	Internal UUID of the agent.
`allocated_balance`	Current allocated balance for the agent.
`last_allocation`	ISO 8601 timestamp of the most recent allocation to this agent, or empty if never allocated.
`is_active`	Whether the agent account is active.

Get Agent Transactions

GET /api/v1/org/wallet/agents/:agent_id/transactions

Returns allocation history for a specific agent. Supports the same filters as wallet transactions.

Query Parameters:

Parameter	Type	Description
`page`	int	Page number (default: 1).
`per_page`	int	Results per page, max 100 (default: 20).
`from`	date	Start date filter (YYYY-MM-DD).
`to`	date	End date filter (YYYY-MM-DD).

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": "c5f3a2b1-1111-2222-3333-444444444444",
      "created_at": "2026-07-25T09:00:00.000000+05:30",
      "type": "credit",
      "amount": 5000,
      "balance_before": 10000,
      "balance_after": 15000,
      "ref_type": "topup",
      "description": "received from org: monthly allocation",
      "performed_by": "5b920162-500f-474f-8e7a-5f131053a7d5"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Export Transactions

GET /api/v1/org/wallet/transactions/export?from=2026-07-01&to=2026-07-28

Downloads the org wallet's transaction history as a CSV file. Supports the same filters as the transactions list endpoint (without pagination).

Success Response (200):

Returns a text/csv file with Content-Disposition: attachment. Columns: ID, Date, Type, Amount, Balance Before, Balance After, Reference Type, Description, Performed By.

Topup Agent Wallet

POST /api/v1/org/wallet/topup/:agent_id

Allocates funds from the org wallet to an agent's allocated balance. The :agent_id path param is the agent's internal UUID.

Request:

{
  "amount": 5000,
  "description": "Monthly allocation for John"
}

Success Response (200):

{
  "success": true,
  "message": "wallet allocated to agent"
}

Error Response (400 — Insufficient Balance):

{
  "success": false,
  "error": "insufficient org wallet balance (available: 750.00)"
}

Field Reference:

Field	Description
`amount`	Amount to allocate to the agent (deducted from org wallet). Must be greater than zero and ≤ org wallet balance.
`description`	Reason for the allocation. Visible in both org and agent transaction history.

Packages & Markup

Manage org-scoped pricing packages and agent-level package assignments. Org-scoped packages override global defaults and are only visible within the org.

Create Package

POST /api/v1/org/packages Request:

{
  "name": "Premium Package",
  "description": "Best fares with low service fees",
  "markup_type": "flat",
  "markup_value": 150.0,
  "markup_apply_on": "commission",
  "min_commission": 0,
  "max_commission": 0,
  "service_fee_type": "flat",
  "service_fee_value": 50.0,
  "gst_on_service_fee": 18.0,
  "platform_charge": 10.0,
  "priority": 0
}

Fields: markup_type (flat | percent), markup_apply_on (commission | fare | total), service_fee_type (flat | percent).

Success Response (201):

{
  "success": true,
  "message": "package created",
  "data": {
    "id": "b3f1a2c4-...",
    "name": "Premium Package",
    "description": "Best fares with low service fees",
    "org_id": "9551fa77-...",
    "scope": "org",
    "markup_type": "flat",
    "markup_value": 150.0,
    "markup_apply_on": "commission",
    "min_commission": 0,
    "max_commission": 0,
    "service_fee_type": "flat",
    "service_fee_value": 50.0,
    "gst_on_service_fee": 18.0,
    "platform_charge": 10.0,
    "priority": 0,
    "is_active": true,
    "created_by": "5b920162-...",
    "created_at": "2026-04-15T10:00:00Z",
    "updated_at": "2026-04-15T10:00:00Z"
  }
}

List Packages

GET /api/v1/org/packages Success Response (200):

{
  "success": true,
  "message": "packages retrieved",
  "data": [
    {
      "id": "b3f1a2c4-...",
      "name": "Premium Package",
      "scope": "org",
      "org_id": "9551fa77-...",
      "markup_type": "flat",
      "markup_value": 150.0,
      "markup_apply_on": "commission",
      "service_fee_type": "flat",
      "service_fee_value": 50.0,
      "gst_on_service_fee": 18.0,
      "platform_charge": 10.0,
      "priority": 0,
      "is_active": true,
      "is_applied": false,
      "created_at": "2026-04-15T10:00:00Z",
      "updated_at": "2026-04-15T10:00:00Z"
    }
  ]
}

Get Assigned Package

GET /api/v1/org/packages/assigned

Returns the currently assigned org-level package (not agent-specific). Returns 404 if no package is assigned.

Success Response (200):

{
  "success": true,
  "message": "assigned package",
  "data": {
    "id": "b3f1a2c4-...",
    "name": "Premium Package",
    "scope": "org",
    "org_id": "9551fa77-...",
    "markup_type": "flat",
    "markup_value": 150.0,
    "markup_apply_on": "commission",
    "min_commission": 0,
    "max_commission": 0,
    "service_fee_type": "flat",
    "service_fee_value": 50.0,
    "gst_on_service_fee": 18.0,
    "platform_charge": 10.0,
    "priority": 0,
    "is_active": true,
    "created_by": "5b920162-...",
    "created_at": "2026-04-15T10:00:00Z",
    "updated_at": "2026-04-15T10:00:00Z",
    "assignments": null
  }
}

Update Package

PUT /api/v1/org/packages/:id

Same request body as Create Package. Updates all configurable fields.

Success Response (200):

{
  "success": true,
  "message": "package updated",
  "data": {
    "id": "b3f1a2c4-...",
    "name": "Premium Package",
    "description": "Best fares with low service fees",
    "org_id": "9551fa77-...",
    "scope": "org",
    "markup_type": "flat",
    "markup_value": 175.0,
    "markup_apply_on": "commission",
    "min_commission": 0,
    "max_commission": 0,
    "service_fee_type": "flat",
    "service_fee_value": 50.0,
    "gst_on_service_fee": 18.0,
    "platform_charge": 10.0,
    "priority": 0,
    "is_active": true,
    "created_by": "5b920162-...",
    "created_at": "2026-04-15T10:00:00Z",
    "updated_at": "2026-04-16T11:32:07Z"
  }
}

Delete Package

DELETE /api/v1/org/packages/:id

Performs a hard delete (scoped to the org).

Success Response (200):

{
  "success": true,
  "message": "package deleted"
}

Assign Package to Organization

POST /api/v1/org/packages/assign

Assigns a package to the org itself. Removes any previous org-level assignment.

Request:

{
  "package_id": "b3f1a2c4-..."
}

Success Response (200):

{
  "success": true,
  "message": "package assigned"
}

Unassign Package from Organization

DELETE /api/v1/org/packages/assign Success Response (200):

{
  "success": true,
  "message": "package unassigned"
}

List Agent Assignments

GET /api/v1/org/packages/agent-assignments

Returns all agent-specific package assignments for the org, with the preloaded package details.

Success Response (200):

{
  "success": true,
  "message": "agent assignments",
  "data": [
    {
      "id": "a1b2c3d4-...",
      "package_id": "b3f1a2c4-...",
      "org_id": "9551fa77-...",
      "agent_id": "5b920162-...",
      "assigned_at": "2026-04-15T10:00:00Z",
      "assigned_by": "6315581f-...",
      "package": {
        "id": "b3f1a2c4-...",
        "name": "Premium Package",
        "markup_type": "flat",
        "markup_value": 150.0,
        ...
      }
    }
  ]
}

Assign Package to Agent

POST /api/v1/org/packages/assign-agent/:agent_id

Assigns a package to a specific agent (agent-level override). Replaces any prior agent assignment.

Request:

{
  "package_id": "b3f1a2c4-..."
}

Success Response (200):

{
  "success": true,
  "message": "package assigned to agent"
}

Unassign Package from Agent

DELETE /api/v1/org/packages/assign-agent/:agent_id Success Response (200):

{
  "success": true,
  "message": "agent assignment removed"
}

Fare Transactions

View fare transaction history (fare ledger) for the entire organization. Only org_admin can access these endpoints.

List Fare Transactions

GET /api/v1/org/fare-transactions

Query Parameters: page, per_page, period (weekly | monthly, default monthly).

Success Response (200):

{
  "success": true,
  "message": "fare transactions",
  "data": {
    "period": "monthly",
    "summary": {
      "total_public_fare": 125000.50,
      "total_agent_fare": 118750.48,
      "total_agent_commission": 6250.02,
      "transaction_count": 42
    },
    "transactions": [
      {
        "id": "uuid",
        "booking_ref": "GAM-ABCDEF",
        "pnr": "6EABCD",
        "agent_id": "5b920162-...",
        "agent_name": "Test Agent",
        "public_fare": 5500.00,
        "agent_fare": 5225.00,
        "agent_commission": 275.00,
        "currency": "INR",
        "issued_at": "2026-04-15T10:00:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "per_page": 20
  }
}

List Agent Fare Transactions

GET /api/v1/org/fare-transactions/:agent_id

Same response shape as above, filtered to a single sub-agent. Query Parameters: page, per_page, period.

Success Response (200):

{
  "success": true,
  "message": "fare transactions",
  "data": {
    "period": "monthly",
    "summary": {
      "total_public_fare": 14200.00,
      "total_agent_fare": 13490.00,
      "total_agent_commission": 710.00,
      "transaction_count": 5
    },
    "transactions": [
      {
        "id": "uuid",
        "booking_ref": "GAM-QRSTUV",
        "pnr": "6EQRST",
        "agent_id": "5b920162-...",
        "agent_name": "Test Agent",
        "public_fare": 5500.00,
        "agent_fare": 5225.00,
        "agent_commission": 275.00,
        "currency": "INR",
        "issued_at": "2026-04-15T10:00:00Z"
      }
    ],
    "total": 5,
    "page": 1,
    "per_page": 20
  }
}

Audit Logs

View audit trail for all actions within the organization. Only org_admin can access this endpoint. Results are auto-scoped to the org.

List Audit Logs

GET /api/v1/org/audit-logs

Query Parameters: page, per_page, actor_id, entity_type, action.

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "actor_id": "5b920162-...",
      "actor_type": "org_user",
      "actor_org_id": "9551fa77-...",
      "action": "user.created",
      "entity_type": "user",
      "entity_id": "a1b2c3d4-...",
      "old_value": null,
      "new_value": {
        "username": "agent1",
        "role": "agent"
      },
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2026-04-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Self Profile (/me endpoints)

All authenticated org users (both org_admin and agent) can access these endpoints.

Get My Profile

GET /api/v1/me Success Response (200):

{
  "success": true,
  "message": "profile retrieved",
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "username": "admin",
    "email": "admin@demo.com",
    "name": "Demo Admin",
    "phone": "",
    "role": "org_admin",
    "status": "active",
    "org_id": "9551fa77-16ad-4df5-9284-dc23cb95c237",
    "sub_agent_id": "GAMDEMO0002",
    "last_login_at": "2026-04-10T14:45:35.36903+05:30"
  }
}

Update My Profile

PUT /api/v1/me Request:

{
  "name": "Updated Name",
  "phone": "+919999999999"
}

Success Response (200):

{
  "success": true,
  "message": "profile updated",
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "username": "admin",
    "email": "admin@demo.com",
    "name": "Updated Name",
    "phone": "+919999999999",
    "role": "org_admin",
    "status": "active"
  }
}

Change Password

PUT /api/v1/me/password Request:

{
  "current_password": "OldPassword@123",
  "new_password": "NewPassword@123"
}

Success Response (200):

{
  "success": true,
  "message": "password changed successfully"
}

Error Response (400):

{
  "success": false,
  "error": "current password is incorrect"
}

My Stats

GET /api/v1/me/stats Success Response (200):

{
  "success": true,
  "message": "stats retrieved",
  "data": {
    "total_bookings": 0,
    "confirmed_bookings": 0,
    "cancelled_bookings": 0,
    "total_spent": 0,
    "total_commissions": 0,
    "wallet_balance": 0
  }
}

Wallet (Self)

Get My Wallet

GET /api/v1/wallet Success Response (200):

{
  "success": true,
  "message": "wallet retrieved",
  "data": {
    "id": "22222222-2222-2222-2222-222222222220",
    "owner_id": "5b920162-500f-474f-8e7a-5f131053a7d5",
    "owner_type": "user",
    "balance": 5000,
    "allocated_balance": 5000,
    "currency": "INR",
    "credit_limit": 0,
    "is_active": true
  }
}

Get My Transactions

GET /api/v1/wallet/transactions

Query Parameters: page, per_page

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "type": "credit",
      "amount": 5000,
      "description": "Wallet topup from org",
      "created_at": "2026-04-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Flight Search

POST /api/v1/flights/search

One Way

{
  "search_params": {
    "trip_type": "ONE_WAY",
    "passengers": {
      "adults": 1,
      "children": 0,
      "infants": 0
    },
    "cabin_class": "ECONOMY",
    "preferred_currency": "INR",
    "direct_flights_only": false,
    "max_results": 3,
    "airline_id": ""
  },
  "slices": [
    {
      "origin": "DEL",
      "destination": "BOM",
      "departure_date": "2026-05-01"
    }
  ]
}

Round Trip

{
  "search_params": {
    "trip_type": "RETURN",
    "passengers": {
      "adults": 1,
      "children": 0,
      "infants": 0
    },
    "cabin_class": "ECONOMY",
    "preferred_currency": "INR",
    "max_results": 3
  },
  "slices": [
    {
      "origin": "DEL",
      "destination": "BOM",
      "departure_date": "2026-05-01"
    },
    {
      "origin": "BOM",
      "destination": "DEL",
      "departure_date": "2026-05-05"
    }
  ]
}

Trip Types: ONE_WAY, RETURN, MULTI_CITY

Cabin Classes: ECONOMY, PREMIUM_ECONOMY, BUSINESS, FIRST

Validation: cabin_class is required, adults 1-9, children 0-9, infants 0-9, preferred_currency must be 3 letters, slices min=1 max=6

Success Response (200) — One Way:

{
  "success": true,
  "message": "3 offers found",
  "data": {
    "search_id": "srch_20260410_17407",
    "search_meta": {
      "currency": "INR",
      "created_at": "2026-04-10T09:23:20.254656Z",
      "expires_at": "2026-04-10T09:48:20.260503Z",
      "total_results": 3,
      "duration_ms": 20189,
      "provider_status": {
        "m7n4p8qr": { "status": "success", "duration_ms": 20189, "results": 831 },
        "a3f9kx2b": { "status": "success", "duration_ms": 0, "results": 0 }
      }
    },
    "dictionaries": {
      "airlines": {
        "6E": { "name": "IndiGo", "logo_url": "https://pics.avs.io/200/200/6E.png" },
        "I5": { "name": "AirAsia India", "logo_url": "https://pics.avs.io/200/200/I5.png" }
      },
      "airports": {
        "DEL": { "name": "Indira Gandhi International Airport", "city": "Delhi", "country": "India", "iso_country": "IN", "timezone": "Asia/Kolkata", "utc_offset": "+05:30" },
        "BOM": { "name": "Chhatrapati Shivaji International Airport", "city": "Mumbai", "country": "India", "iso_country": "IN", "timezone": "Asia/Kolkata", "utc_offset": "+05:30" }
      },
      "baggage": {
        "BAG_15KG": { "check_in": "15KG", "cabin": "7KG", "fare_family": "Saver", "desc": "15 kg check-in + 7 kg cabin" }
      },
      "refund_policies": {
        "REF_NON": { "is_refundable": false, "cancel_fee": null, "change_fee": null, "no_show_fee": null }
      }
    },
    "segments": [
      {
        "segment_id": "seg_591c95",
        "airline": "I5",
        "flight_number": "IX 1056",
        "origin": "DEL",
        "destination": "BOM",
        "departure": "2026-05-01T18:10:00Z",
        "arrival": "2026-05-01T20:30:00Z",
        "duration_minutes": 140,
        "aircraft_type": "A320",
        "cabin": "ECONOMY",
        "operating_carrier": "I5",
        "seats_available": 9
      }
    ],
    "legs": [
      {
        "leg_id": "leg_delbom_0",
        "route_index": 0,
        "origin": "DEL",
        "destination": "BOM",
        "departure": "2026-05-01T18:10:00Z",
        "arrival": "2026-05-01T20:30:00Z",
        "duration_minutes": 140,
        "stops": 0,
        "stops_detail": [],
        "segments": ["seg_591c95"],
        "operating_carrier": "I5"
      }
    ],
    "offers": [
      {
        "offer_id": "off_m7n4p8qr:YeRaP0TPvhs...",
        "type": "combinable",
        "route_index": 0,
        "combination_group_id": "cg_abc123",
        "combinable_with": "cg_abc123",
        "legs": ["leg_delbom_0"],
        "supplier": "m7n4p8qr",
        "price": {
          "total": 2368,
          "public_fare": 2368,
          "agent_price": {
            "service_fee": 50,
            "gst_on_service_fee": 9,
            "platform_charge": 25,
            "agent_commission": 5,
            "agent_fare": 2363
          },
          "currency": "INR",
          "breakdown": [
            {
              "passenger_type": "ADT",
              "count": 1,
              "unit_base": 1001,
              "unit_tax": 1367,
              "subtotal": 2368
            }
          ]
        },
        "fare_details": {
          "fare_class": "E",
          "fare_family": "Saver",
          "fare_name": "VALUE",
          "seats_left": 9,
          "baggage_ref": "BAG_15KG",
          "refund_ref": "REF_NON"
        },
        "supplier_ref": {
          "offer_token": "m7n4p8qr:YeRaP0TPvhs...",
          "integrity_hash": "a1b2c3d4e5f6...",
          "expires_at": "2026-04-10T09:53:07.279146Z"
        }
      }
    ],
    "debug": {
      "provider_errors": {}
    }
  }
}

Understanding Offer Types:

The type field in each offer indicates how the offer can be combined with other offers for multi-passenger bookings:

Type	Description	Usage
`combinable`	Offer can be combined with other combinable offers of the same airline/route to form a single booking	Use directly in booking - can mix with other combinable offers for group bookings
`bundled`	Offer is a pre-bundled package that must be booked as-is	Use directly in booking - cannot combine with other offers
`one_way`	Offer is for a single leg only (return journey requires separate booking)	Book separately or combine with another one_way for return
`offer`	NDC-style offer from provider	Use directly in booking – cannot combine with other offers

Example - Booking 3 passengers with combinable offers:
If you have 3 passengers and find 3 separate combinable offers for the same flight, you can select all 3 in the price-itinerary request to get a combined price for all passengers. The offer_id from each combinable offer should be included in the offer_ids array.

Field Reference — Offer Object:

Field	Description
`offer_id`	Unique ID for this fare offer — pass it to `/price` or `/fare-rules`.
`supplier`	Code of the flight provider that returned this offer (matches keys in `provider_status`).
`price.total` / `public_fare`	Total price shown to the end customer, in `price.currency`.
`price.agent_price.agent_fare`	The net amount actually deducted from the agent's wallet for this booking.
`price.agent_price.service_fee`	Platform service fee added on top of the base fare.
`price.agent_price.gst_on_service_fee`	Tax (GST) charged on the service fee.
`price.agent_price.agent_commission`	Commission earned by the agent on this booking.
`fare_details.fare_class` / `fare_family`	Airline's fare bucket and named fare tier (e.g. "Saver").
`fare_details.seats_left`	Number of seats remaining at this fare — useful for urgency messaging.
`fare_details.baggage_ref` / `refund_ref`	Keys that look up baggage and refund policy details in the `dictionaries` object.
`supplier_ref.expires_at`	Timestamp after which this offer is no longer bookable — re-search after this time.

Success Response (200) — Round Trip:

{
  "success": true,
  "message": "2 offers found",
  "data": {
    "search_id": "srch_20260410_17411",
    "search_meta": {
      "currency": "INR",
      "created_at": "2026-04-10T09:24:05.101832Z",
      "expires_at": "2026-04-10T09:49:05.108021Z",
      "total_results": 2,
      "duration_ms": 18422,
      "provider_status": {
        "m7n4p8qr": { "status": "success", "duration_ms": 18422, "results": 412 }
      }
    },
    "dictionaries": {
      "airlines": {
        "6E": { "name": "IndiGo", "logo_url": "https://pics.avs.io/200/200/6E.png" }
      },
      "airports": {
        "DEL": { "name": "Indira Gandhi International Airport", "city": "Delhi", "country": "India", "iso_country": "IN", "timezone": "Asia/Kolkata", "utc_offset": "+05:30" },
        "BOM": { "name": "Chhatrapati Shivaji International Airport", "city": "Mumbai", "country": "India", "iso_country": "IN", "timezone": "Asia/Kolkata", "utc_offset": "+05:30" }
      },
      "baggage": {
        "BAG_15KG": { "check_in": "15KG", "cabin": "7KG", "fare_family": "Saver", "desc": "15 kg check-in + 7 kg cabin" }
      },
      "refund_policies": {
        "REF_NON": { "is_refundable": false, "cancel_fee": null, "change_fee": null, "no_show_fee": null }
      }
    },
    "segments": [
      { "segment_id": "seg_out_1", "airline": "6E", "flight_number": "6E 320", "origin": "DEL", "destination": "BOM", "departure": "2026-05-01T08:40:00Z", "arrival": "2026-05-01T10:20:00Z", "duration_minutes": 100, "aircraft_type": "A320", "cabin": "ECONOMY", "operating_carrier": "6E", "seats_available": 6 },
      { "segment_id": "seg_ret_1", "airline": "6E", "flight_number": "6E 455", "origin": "BOM", "destination": "DEL", "departure": "2026-05-05T19:15:00Z", "arrival": "2026-05-05T21:05:00Z", "duration_minutes": 110, "aircraft_type": "A320", "cabin": "ECONOMY", "operating_carrier": "6E", "seats_available": 4 }
    ],
    "legs": [
      { "leg_id": "leg_delbom_0", "route_index": 0, "origin": "DEL", "destination": "BOM", "departure": "2026-05-01T08:40:00Z", "arrival": "2026-05-01T10:20:00Z", "duration_minutes": 100, "stops": 0, "stops_detail": [], "segments": ["seg_out_1"], "operating_carrier": "6E" },
      { "leg_id": "leg_bomdel_1", "route_index": 1, "origin": "BOM", "destination": "DEL", "departure": "2026-05-05T19:15:00Z", "arrival": "2026-05-05T21:05:00Z", "duration_minutes": 110, "stops": 0, "stops_detail": [], "segments": ["seg_ret_1"], "operating_carrier": "6E" }
    ],
    "offers": [
      {
        "offer_id": "off_m7n4p8qr:W8j24Tcq6yjEiC6Sn8BKGwSb...",
        "type": "combinable",
        "route_index": 0,
        "combination_group_id": "cg_rt001",
        "combinable_with": "cg_rt001",
        "legs": ["leg_delbom_0"],
        "supplier": "m7n4p8qr",
        "price": {
          "total": 2405,
          "public_fare": 2405,
          "agent_price": { "service_fee": 50, "gst_on_service_fee": 9, "platform_charge": 25, "agent_commission": 5, "agent_fare": 2400 },
          "currency": "INR",
          "breakdown": [{ "passenger_type": "ADT", "count": 1, "unit_base": 1000, "unit_tax": 1405, "subtotal": 2405 }]
        },
        "fare_details": { "fare_class": "R", "fare_family": "Saver", "fare_name": "SAVER", "seats_left": 6, "baggage_ref": "BAG_15KG", "refund_ref": "REF_NON" },
        "supplier_ref": { "offer_token": "m7n4p8qr:W8j24Tcq6yjEiC6Sn8BKGwSb...", "integrity_hash": "b2c3d4e5f6a7...", "expires_at": "2026-04-10T09:54:05.108021Z" }
      },
      {
        "offer_id": "off_m7n4p8qr:9kLm3NpQr7tYvBxZ5cFgHsJd...",
        "type": "combinable",
        "route_index": 1,
        "combination_group_id": "cg_rt002",
        "combinable_with": "cg_rt002",
        "legs": ["leg_bomdel_1"],
        "supplier": "m7n4p8qr",
        "price": {
          "total": 2405,
          "public_fare": 2405,
          "agent_price": { "service_fee": 50, "gst_on_service_fee": 9, "platform_charge": 25, "agent_commission": 5, "agent_fare": 2400 },
          "currency": "INR",
          "breakdown": [{ "passenger_type": "ADT", "count": 1, "unit_base": 1000, "unit_tax": 1405, "subtotal": 2405 }]
        },
        "fare_details": { "fare_class": "R", "fare_family": "Saver", "fare_name": "SAVER", "seats_left": 4, "baggage_ref": "BAG_15KG", "refund_ref": "REF_NON" },
        "supplier_ref": { "offer_token": "m7n4p8qr:9kLm3NpQr7tYvBxZ5cFgHsJd...", "integrity_hash": "c3d4e5f6a7b8...", "expires_at": "2026-04-10T09:54:05.108021Z" }
      }
    ],
    "debug": { "provider_errors": {} }
  }
}

Round Trip: each route_index (0 = outbound, 1 = return) has its own set of offers. To book both directions together, pass one offer_id from route_index: 0 and one from route_index: 1 in the offer_ids array sent to Price Itinerary.

Get Fare Rules

POST /api/v1/flights/fare-rules Request:

{
  "search_id": "srch_20260410_17407",
  "offer_ids": ["m7n4p8qr:W8j24Tcq6yjEiC6Sn8BKGwSb..."]
}

Note: Use offer_ids from the search response. Alternatively, you can pass fare_keys or booking_keys. At least one of these arrays must be non-empty.

Success Response (200):

{
  "success": true,
  "message": "fare rules retrieved",
  "data": {
    "fare_key": "m7n4p8qr:W8j24Tcq6yjEiC6Sn8BKGwSb...",
    "cancellation": "Cancellation 0H-24H: INR 350",
    "date_change": "Date change allowed with fare difference",
    "baggage_policy": "Check-in: 15KG | Cabin: 7KG",
    "raw_text": "FARE BASIS: XNRA015\nFARE TYPE: Refundable\nCANCELLATION: 0H-24H penalty INR 350\nBAGGAGE: 15KG check-in + 7KG cabin"
  }
}

Price Itinerary

POST /api/v1/flights/price

One Way

{
    "offer_ids": ["m7n4p8qr:W8j24Tcq6yjEiC6Sn8BKGwSb..."],
    "adults": 1,
    "children": 0,
    "infants": 0
}

Round Trip

{
    "offer_ids": [
        "m7n4p8qr:W8j24Tcq6yjEiC6Sn8BKGwSb...",
        "m7n4p8qr:9kLm3NpQr7tYvBxZ5cFgHsJd..."
    ],
    "adults": 1,
    "children": 0,
    "infants": 0
}

Alternative format: Wrap offer_ids inside flight_selection object. The API accepts both offer_ids at root level and { flight_selection: { offer_ids: [...] } }.

Response — One Way / Round Trip

{
  "success": true,
  "message": "pricing successful",
  "data": {
    "booking_keys": ["m7n4p8qr-book:1BG8QVD8geiCxp0Phy...."],
    "status": "PRICE_VERIFIED",
    "currency": "INR",
    "expires_at": "2026-04-10T16:26:54.903522+05:30",
    "price_summary": {
      "total_payable": 2410,
      "public_fare": 2410,
      "currency": "INR",
      "exchange_rate": 1,
      "base_fare_total": 1000,
      "tax_total": 1321,
      "agent_details": {
        "agent_fare": 2405,
        "service_fee": 50,
        "gst_on_service_fee": 9,
        "platform_charge": 25,
        "agent_commission": 5
      }
    },
    "passenger_breakdown": [
      {
        "pax_type": "ADT",
        "count": 1,
        "base_per_pax": 1000,
        "tax_per_pax": 1410,
        "total_per_pax": 2410,
        "tax_breakdown": [
          { "code": "RCF", "amount": 50, "description": "Regulatory Compliance Fee" },
          { "code": "YQ", "amount": 600, "description": "Fuel Surcharge" },
          { "code": "ASF", "amount": 236, "description": "Airport Service Fee" },
          { "code": "UDF", "amount": 152, "description": "User Development Fee" }
        ]
      }
    ],
    "itinerary_snapshot": {
      "segments": [
        {
          "segment_id": "seg_1",
          "airline": "6E",
          "operating_carrier": "6E",
          "flight_number": "6E 320",
          "origin": "DEL",
          "destination": "BOM",
          "dep_terminal": "1",
          "arr_terminal": "2",
          "departure": "2026-04-15T08:40:00",
          "arrival": "2026-04-15T10:20:00",
          "cabin_class": "ECONOMY",
          "rbd": "R",
          "fare_basis": "RLIP",
          "fare_type": "B",
          "baggage": "20 KG",
          "cabin_baggage": "7 Kg",
          "refundable": true,
          "avail_seats": 114,
          "duration_minutes": 100
        }
      ]
    },
    "fare_rules": {
      "is_refundable": true,
      "cancellation_fee": null,
      "change_fee": null,
      "rule_text": null
    },
    "ancillaries": [
      {
        "type": "MEAL",
        "code": "VLML",
        "name": "Veg lacto meal + beverage",
        "price": 0,
        "segment_id": "seg_1"
      },
      {
        "type": "BAGGAGE",
        "code": "XBPC",
        "name": "ExcessBaggage 15KG",
        "price": 4500,
        "segment_id": "seg_1"
      }
    ]
  }
}

Field Reference:

Field	Description
`booking_keys`	Locked-in price keys — pass these to `/book` instead of the original `offer_ids`.
`status`	`PRICE_VERIFIED` means the fare is confirmed and safe to book before `expires_at`.
`expires_at`	Deadline by which the booking must be completed at this price.
`price_summary.total_payable`	Final amount the customer pays, including all taxes.
`price_summary.agent_details.agent_fare`	Amount that will be deducted from the agent's wallet if they proceed with booking.
`passenger_breakdown[].tax_breakdown`	Itemized taxes and surcharges (e.g. fuel surcharge, airport fee) per passenger type.
`fare_rules.is_refundable`	Whether this fare allows a refund on cancellation.
`ancillaries`	Optional add-ons (meals, extra baggage, etc.) available for this itinerary, with their price.

Round Trip — itinerary_snapshot.segments difference:

"itinerary_snapshot": {
    "segments": [
      {
        "segment_id": "seg_1",
        "airline": "6E",
        "operating_carrier": "6E",
        "flight_number": "6E 320",
        "origin": "DEL",
        "destination": "BOM",
        "dep_terminal": "1",
        "arr_terminal": "2",
        "departure": "2026-05-01T08:40:00",
        "arrival": "2026-05-01T10:20:00",
        "cabin_class": "ECONOMY",
        "rbd": "R",
        "fare_basis": "RLIP",
        "fare_type": "B",
        "baggage": "15 KG",
        "cabin_baggage": "7 Kg",
        "refundable": false,
        "avail_seats": 6,
        "duration_minutes": 100
      },
      {
        "segment_id": "seg_2",
        "airline": "6E",
        "operating_carrier": "6E",
        "flight_number": "6E 455",
        "origin": "BOM",
        "destination": "DEL",
        "dep_terminal": "2",
        "arr_terminal": "3",
        "departure": "2026-05-05T19:15:00",
        "arrival": "2026-05-05T21:05:00",
        "cabin_class": "ECONOMY",
        "rbd": "R",
        "fare_basis": "RLIP",
        "fare_type": "B",
        "baggage": "15 KG",
        "cabin_baggage": "7 Kg",
        "refundable": false,
        "avail_seats": 4,
        "duration_minutes": 110
      }
    ]
}

For a round trip, every other field in the response (price_summary, passenger_breakdown, fare_rules, ancillaries) keeps the same shape shown above — only itinerary_snapshot.segments grows to one entry per flight leg (outbound + return), and the totals reflect the combined price of both legs.

Error Response (402 - Insufficient Balance):

{
  "success": false,
  "error": "insufficient wallet balance to proceed — available: 0.00, required: 2372.00 (agent fare)"
}

This means the agent's wallet doesn't have enough balance to cover the agent_fare. Top up the wallet before retrying (see Organization Wallet or Wallet (Self)).

Error Response (400 - Offer Expired):

{
  "success": false,
  "error": "offer has expired, please search again"
}

Offers from Flight Search are only valid for a short window (supplier_ref.expires_at). If pricing is attempted after that window, re-run the search and price the new offer_id.

Get Seat Map

POST /api/v1/flights/seat-map Request:

{
  "fare_key": "m7n4p8qr:test",
  "origin": "DEL",
  "destination": "BOM",
  "passengers": [
    {
      "title": "MR",
      "first_name": "JOHN",
      "last_name": "DOE",
      "type": "ADT",
      "pax_index": 1
    }
  ]
}

Note: Seat map implementation is provider-specific. The passengers array is required with at least one passenger entry (title, first_name, last_name, type, pax_index).

Success Response (200):

{
  "success": true,
  "message": "seat map",
  "data": {
    "info": "seat map requires provider-specific parameters — use fare_key to identify the provider"
  }
}

Book Flight

POST /api/v1/flights/book

One Way

{
  "booking_keys": ["m7n4p8qr-book:1BG8QVD8gz...."],
  "contact_email": "john.doe@example.com",
  "contact_phone": "9876543210",
  "contact_country_code": "91",
  "passengers": [
    {
      "pax_index": 1,
      "type": "ADT",
      "title": "MR",
      "first_name": "JOHN",
      "last_name": "DOE",
      "gender": "Male",
      "dob": "1990-06-15",
      "infant_ref": 0,
      "ancillaries": [
        {
          "type": "MEAL",
          "code": "VLML-",
          "segment_id": "seg_1"
        }
      ]
    }
  ],
  "agent_price": {
    "agent_fare": 2405,
    "service_fee": 50,
    "gst_on_service_fee": 9,
    "platform_charge": 25,
    "agent_commission": 5
  }
}

Round Trip

{
  "booking_keys": [
    "m7n4p8qr-book:1BG8QVD8gz....",
    "m7n4p8qr-book:9kLm3NpQr7tYvBxZ..."
  ],
  "contact_email": "john.doe@example.com",
  "contact_phone": "9876543210",
  "contact_country_code": "91",
  "passengers": [
    {
      "pax_index": 1,
      "type": "ADT",
      "title": "MR",
      "first_name": "JOHN",
      "last_name": "DOE",
      "gender": "Male",
      "dob": "1990-06-15",
      "infant_ref": 0,
      "ancillaries": [
        {
          "type": "MEAL",
          "code": "VLML-",
          "segment_id": "seg_1"
        }
      ]
    }
  ],
  "agent_price": {
    "agent_fare": 4810,
    "service_fee": 100,
    "gst_on_service_fee": 18,
    "platform_charge": 50,
    "agent_commission": 10
  }
}

Note: The booking_keys array comes from the /price response. Use offer_ids instead if booking without pricing. If the org has ticket password enabled, include "issue_ticket_password": "your-password".

Response — One Way

{
  "success": true,
  "message": "booking confirmed",
  "data": {
    "booking_ref": "FA-1773235577155",
    "provider": "m7n4p8qr",
    "status": "CONFIRMED",
    "total_amount": 4540,
    "currency": "INR",
    "legs": [
      {
        "booking_track_id": "RACCU03000030103585841103260092140",
        "provider_pnr": "BX11HC0130",
        "airline_pnr": "U11VNS",
        "ticket_number": "BX11HC01301-1",
        "origin": "DEL",
        "destination": "CCU",
        "gross_amount": 4540,
        "currency": "INR",
        "issued_date": "11/03/2026 18:56:13"
      }
    ]
  }
}

Response — Round Trip

{
  "success": true,
  "message": "booking confirmed",
  "data": {
    "booking_ref": "FA-1773241902318",
    "provider": "m7n4p8qr",
    "status": "CONFIRMED",
    "total_amount": 4810,
    "currency": "INR",
    "legs": [
      {
        "booking_track_id": "RACCU03000030103585841103260092141",
        "provider_pnr": "BX11HC0131",
        "airline_pnr": "U11VNT",
        "ticket_number": "BX11HC01311-1",
        "origin": "DEL",
        "destination": "BOM",
        "gross_amount": 2405,
        "currency": "INR",
        "issued_date": "11/03/2026 18:59:02"
      },
      {
        "booking_track_id": "RACCU03000030103585841103260092142",
        "provider_pnr": "BX11HC0132",
        "airline_pnr": "U11VNU",
        "ticket_number": "BX11HC01311-2",
        "origin": "BOM",
        "destination": "DEL",
        "gross_amount": 2405,
        "currency": "INR",
        "issued_date": "11/03/2026 18:59:02"
      }
    ]
  }
}

Field Reference:

Field	Description
`booking_ref`	GAMAN's own booking reference — use this for all later booking-management calls.
`provider`	Code of the airline/GDS provider that fulfilled the booking.
`status`	`CONFIRMED` means seats are held; ticketing may still be pending — check `tickets`/`issue-ticket`.
`legs[].booking_track_id`	Internal tracking ID for this leg — used by the `/track` endpoint.
`legs[].provider_pnr` / `airline_pnr`	Reservation code from the provider system and the airline respectively — give the airline PNR to customers.
`legs[].ticket_number`	Airline e-ticket number, once issued.

Round Trip: as shown above, the legs array contains 2 entries — the first for the outbound flight, the second for the return flight — each with its own PNR and ticket number.

Error Response (400 - Booking Failed):

{
  "success": false,
  "error": "booking key has expired, please price the itinerary again"
}

Returned when the booking_keys from Price Itinerary have passed their expires_at time before /book was called. Re-run Price Itinerary to get fresh booking_keys and retry.

List Bookings

GET /api/v1/flights/bookings

Query Parameters: page, per_page, status (pending, confirmed, cancelled)

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": "8555813d-f437-49ff-9e7e-a1d144894528",
      "booking_ref": "FA-1775272567576",
      "pnr": "BX04HD0001",
      "provider": "m7n4p8qr",
      "origin": "BOM",
      "destination": "DEL",
      "passenger_count": 1,
      "base_fare": 2162,
      "public_fare": 2162,
      "currency": "INR",
      "status": "confirmed",
      "booked_at": "2026-04-04T08:46:07.576683+05:30",
      "passengers": [
        {
          "title": "MR",
          "first_name": "JOHN",
          "last_name": "DOE",
          "type": "ADT"
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 3,
    "total_pages": 1
  }
}

Get Booking Details

GET /api/v1/flights/bookings/:ref Example:

GET /api/v1/flights/bookings/FA-1775272567576

Success Response (200):

{
  "success": true,
  "message": "booking retrieved",
  "data": {
    "booking_id": "ca056426-bc9a-4859-8dbc-44c5bac26e83",
    "booking_ref": "FA-1773235577155",
    "provider": "m7n4p8qr",
    "provider_ref": "RACCU03000030103585841103260092140",
    "status": "CONFIRMED",
    "created_at": "2026-03-11T18:56:17.159116+05:30",
    "currency": "INR",
    "pnr_details": [
      {
        "pnr": "BX11HC0130",
        "airline_pnr": "U11VNS",
        "airline": "6E",
        "supplier": "m7n4p8qr",
        "supplier_ref": "RACCU03000030103585841103260092140",
        "status": "CONFIRMED",
        "segment_refs": ["seg_1"],
        "ancillaries": [
          { "type": "MEAL", "code": "VLML-", "segment_id": "seg_1" }
        ]
      }
    ],
    "passengers": [
      {
        "pax_id": "pax_001",
        "type": "ADT",
        "title": "MR",
        "first_name": "JOHN",
        "last_name": "DOE",
        "dob": "1990-06-15",
        "gender": "Male",
        "seat_onward": "",
        "seat_return": ""
      }
    ],
    "itinerary": {
      "legs": [
        { "leg_index": 0, "origin": "DEL", "destination": "CCU", "segment_refs": ["seg_1"] }
      ],
      "segments": [
        {
          "segment_id": "seg_1",
          "airline": "6E",
          "flight_number": "6E 320",
          "origin": "DEL",
          "destination": "CCU",
          "departure": "2026-03-11T18:30:00",
          "arrival": "2026-03-11T20:45:00",
          "duration_minutes": 135,
          "cabin": "ECONOMY",
          "rbd": "R",
          "baggage": "15KG",
          "cabin_baggage": "7KG",
          "operating_carrier": "6E",
          "status": "CONFIRMED"
        }
      ]
    },
    "pricing": {
      "currency": "INR",
      "total_payable": 4540,
      "supplier_currency": "INR",
      "supplier_total": 4540,
      "exchange_rate": 1,
      "public_fare": 2410,
      "agent_fare": 2405,
      "agent_commission": 5,
      "total_service_fee": 50,
      "total_gst": 9,
      "total_platform_charge": 25,
      "pax_breakdown": [
        {
          "pax_id": "pax_001",
          "type": "ADT",
          "base": 1000,
          "tax": 1410,
          "total": 2410
        }
      ]
    },
    "tickets": [
      {
        "tkt_number": "BX11HC01301-1",
        "pax_id": "pax_001",
        "pnr_ref": "BX11HC0130",
        "status": "ISSUED",
        "segment_refs": ["seg_1"]
      }
    ],
    "contact_details": {
      "country_code": "91",
      "phone": "9876543210",
      "email": "john.doe@example.com"
    },
    "can_issue_ticket": false
  }
}

Field Reference:

Field	Description
`pnr_details[].status`	Status of this specific PNR (a booking can span multiple PNRs).
`passengers[].seat_onward` / `seat_return`	Assigned seat numbers, if seat selection was made — empty if not yet assigned.
`pricing.public_fare` vs `agent_fare`	Customer-facing price vs. what was actually charged to the agent's wallet; the difference includes fees and commission.
`tickets[].status`	`ISSUED` means the e-ticket exists; otherwise call Issue Ticket.
`can_issue_ticket`	Whether the `/issue-ticket` endpoint can currently be called for this booking.

Note: The pnr field is deprecated. Use pnr_details array for multi-PNR bookings.

Round Trip: For round trip bookings, the itinerary.legs array contains 2 entries (index 0 = outbound, index 1 = inbound), and itinerary.segments includes all segments across both legs. The pnr_details array may contain separate PNRs per leg depending on the provider.

Retrieve Booking

Fetches latest booking data directly from the provider system and returns both the local DB record and the provider's response.

GET /api/v1/flights/bookings/:ref/retrieve Example:

GET /api/v1/flights/bookings/FA-1775272567576/retrieve

Success Response (200):

{
  "success": true,
  "message": "booking retrieved",
  "data": {
    "local": {
      "booking_ref": "FA-1775272567576",
      "pnr": "BX04HD0001",
      "status": "confirmed",
      "provider": "m7n4p8qr"
    },
    "provider": {
      "booking_ref": "FA-1775272567576",
      "pnr": "BX04HD0001",
      "status": "confirmed",
      "provider_booking_id": "RACCU03000030103630040404260094069",
      "ticket_status": "CONFIRMED"
    }
  }
}

Track Booking Status

Tracks booking status from the provider. Response format is provider-specific.

GET /api/v1/flights/bookings/:ref/track Example:

GET /api/v1/flights/bookings/FA-1775272567576/track

Success Response (200) — m7n4p8qr provider:

{
  "success": true,
  "message": "booking status",
  "data": {
    "Status": {
      "Track_Status": "SUCCESS",
      "ResultCode": "1"
    },
    "TrackStatusresponse": {
      "ItinearyDetails": [
        {
          "RiyaPNR": "BX04HD0001",
          "TotalAmount": "2162.00",
          "TicketStatus": "CONFIRMED",
          "TripType": "O"
        }
      ]
    }
  }
}

Provider-specific: Response structure varies by provider. The example shows the m7n4p8qr provider format. For other providers, the response may differ.

Get SSR (Special Services)

Retrieves Special Service Requests for a booking. Response is provider-dependent.

GET /api/v1/flights/bookings/:ref/ssr Query Parameters:

?airline_pnr=U11VNS (optional)

Example:

GET /api/v1/flights/bookings/FA-1775272567576/ssr

Success Response (200):

{
  "success": true,
  "message": "SSR retrieved",
  "data": {}  
}

Provider-specific: The SSR response format varies by provider. The airline_pnr query parameter can be used to target a specific PNR.

Get Cancellation Penalty

POST /api/v1/flights/bookings/:ref/penalty Example:

POST /api/v1/flights/bookings/FA-1775272567576/penalty

Request:

{}

Success Response (200):

{
  "success": true,
  "message": "cancellation penalty",
  "data": {
    "booking_ref": "FA-1775272567576",
    "pnr": "BX04HD0001",
    "penalty": 350,
    "refund_amount": 1812,
    "currency": "INR"
  }
}

Cancel Booking

POST /api/v1/flights/bookings/:ref/cancel Example:

POST /api/v1/flights/bookings/FA-1775272567576/cancel

Request:

{}

Success Response (200):

{
  "success": true,
  "message": "booking cancelled"
}

Note: Always check /penalty first to see the cancellation fee before cancelling.

Issue Ticket

POST /api/v1/flights/bookings/:ref/issue-ticket Example:

POST /api/v1/flights/bookings/FA-1775272567576/issue-ticket

Request:

{
  "amount": 4540,
  "public_fare": 2410,
  "agent_fare": 2405,
  "agent_commission": 5
}

Validation: amount is required and must be > 0.

Success Response (200):

{
  "success": true,
  "message": "ticket issued",
  "data": {
    "ticket_numbers": ["BX04HD00011-1"],
    "status": "issued"
  }
}

Reschedule Availability

POST /api/v1/flights/bookings/:ref/reschedule-avail Example:

POST /api/v1/flights/bookings/FA-1775272567576/reschedule-avail

Request:

{
  "origin": "BOM",
  "destination": "DEL",
  "new_date": "2026-06-15",
  "remarks": ""
}

Validation: origin and destination are required (3-letter IATA codes). new_date is required (format: YYYYMMDD or YYYY-MM-DD).

Success Response (200):

{
  "success": true,
  "message": "reschedule options retrieved",
  "data": {
    "options": [
      {
        "date": "2026-06-15",
        "penalty_amount": 500,
        "fare_difference": 200
      }
    ]
  }
}

Hotels

🏨

Coming Soon

The Hotels API — covering search, availability, pricing, and booking — is currently in development. It will follow the same success / data / error response shape as the rest of the GAMAN API.

Check back soon, or reach out to your GAMAN account contact for early access.

Notifications

List Notifications

GET /api/v1/notifications

Query Parameters: page, per_page

Success Response (200):

{
  "success": true,
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 0,
    "total_pages": 0
  }
}

Get Unread Count

GET /api/v1/notifications/unread-count Success Response (200):

{
  "success": true,
  "message": "unread count",
  "data": {
    "unread": 0
  }
}

Mark Notification as Read

PUT /api/v1/notifications/:id/read Success Response (200):

{
  "success": true,
  "message": "notification marked as read"
}

Mark All as Read

PUT /api/v1/notifications/read-all Success Response (200):

{
  "success": true,
  "message": "all notifications marked as read"
}

Common Error Responses

401 Unauthorized

{
  "success": false,
  "error": "invalid credentials"
}

403 Forbidden

{
  "success": false,
  "error": "access denied"
}

404 Not Found

{
  "success": false,
  "error": "resource not found"
}

422 Validation Error

{
  "success": false,
  "error": "code=422, message=[{field this field is required}]"
}

402 Payment Required (Insufficient Balance)

{
  "success": false,
  "error": "insufficient wallet balance to proceed — available: 0.00, required: 2372.00 (agent fare)"
}

429 Rate Limited

{
  "success": false,
  "error": "too many requests"
}

500 Internal Server Error

{
  "success": false,
  "error": "internal server error, please try again later"
}

Rare, and not tied to anything in your request. Safe to retry with backoff; if it persists on a specific endpoint, contact GAMAN support with the approximate request time.