Skip to main content

API Integrations

GGNomad's API integration surface lets you connect external systems — property and channel managers, ticketing platforms, payment providers, and CRMs — to the platform's inventory, bookings, and trip data. Integrations talk to the GGNomad GraphQL API and react to domain events, so external systems stay in sync without polling.

Integration capabilities​

GraphQL access The primary integration surface is GraphQL:

  • Read inventory (properties, tours, activities, events, transport trips)
  • Read providers, bookings, and analytics
  • Write bookings (createGgnomadBooking, cancelGgnomadBooking)
  • Manage favorites and provider/listing creation
  • Select exactly the fields each integration needs

Event-driven sync React to changes as they happen instead of polling:

  • Subscribe to domain events such as booking.created
  • Mirror confirmed bookings into a PMS or channel manager
  • Trigger downstream notifications and reconciliation
  • Redelivery-safe, idempotent handlers

Authentication​

Credentials Every request is authenticated before any data is returned:

  • OAuth 2.0 / OIDC bearer tokens for service and interactive callers
  • Workspace-scoped API keys for automation and integrations
  • Issued and rotated from the developer portal

Authorization Every operation is permission-checked and scoped to a workspace:

  • Request the minimum ggnomad:* permissions an integration needs
  • An id from one workspace never resolves in another
  • Audit fields are stamped on every write

Reliability​

Pagination & efficiency Keep integrations efficient and within quota:

  • Paginate every list query (pagination: { skip, take })
  • Request only the fields a job consumes
  • Cache rarely changing reference data where appropriate

Error handling Handle typed GraphQL error codes rather than parsing messages:

  • UNAUTHENTICATED / FORBIDDEN
  • WORKSPACE_REQUIRED
  • NOT_FOUND
  • VALIDATION_ERROR

Add backoff and retry around transient failures, and surface validation details to the source system.

Implementation guide​

Integration setup Follow these steps to build an API integration:

  1. Issue a workspace-scoped credential from the developer portal
  2. Confirm connectivity with a read query (ggnomadProperties)
  3. Map your external entities to GGNomad inventory and bookings
  4. Wire booking create/cancel and (optionally) listing sync
  5. Subscribe to booking.created and make the handler idempotent

Best practices Ensure a robust, maintainable integration:

  • Keep writes and event handlers idempotent
  • Treat the published GraphQL schema as the contract
  • Monitor health, usage, and errors
  • Verify cross-workspace isolation and RBAC behavior

Getting started​

Begin implementing an integration:

  • Review the API Reference
  • Confirm a read query works with your credential
  • Wire booking flows, then add event-driven sync

For integration support, see the developer documentation or contact the GGNomad team at [email protected].