Groupbinder API v1

Read-only access to your organization's trips, participants, payment schedules, ledgers, and itineraries. Keys are created by an organization owner or admin under Settings, API access, in the app.

Authentication

Every request carries your key as a Bearer token:


curl -H "Authorization: Bearer gb_live_..." https://app.groupbinder.com/api/v1/trips

Keys are shown once at creation and stored only as a hash. A revoked or unknown key answers 401 with a JSON error body. Treat keys like passwords: server-side only, never in a browser or a mobile app.

Conventions

Base URL: https://app.groupbinder.com/api/v1
Responses are JSON. Timestamps are ISO-8601 UTC. Dates are YYYY-MM-DD.
Money is an object: { "amount_minor": 45000, "currency": "USD" } (integer minor units; $450.00).
Errors are { "error": { "code": "...", "message": "..." } }.
Every response carries an X-Request-Id header; include it when reporting a problem.
The key's organization scopes every query. A trip id from another organization answers 404.

Pagination

List endpoints take ?limit= (max 200, default 50) and ?cursor=. A response with more rows carries next_cursor; pass it back as ?cursor= for the next page. A response with next_cursor: null is the last page.


curl -H "Authorization: Bearer gb_live_..." "https://app.groupbinder.com/api/v1/trips?limit=100&cursor=01J..."

Rate limit

120 requests per minute per key. Over the limit answers 429 with a Retry-After header (seconds).

Endpoints

GET /organization

The key's organization: id, name, home_currency, timezone, locale, created_at.


curl -H "Authorization: Bearer gb_live_..." https://app.groupbinder.com/api/v1/organization

GET /trips

Your trips, paginated. Fields: id, slug, name, destination, description, start_date, end_date, timezone, capacity, currency, signup_open, listed_at, archived_at, show_map, created_at, updated_at.


curl -H "Authorization: Bearer gb_live_..." https://app.groupbinder.com/api/v1/trips

GET /trips/:id

One trip, same fields.


curl -H "Authorization: Bearer gb_live_..." https://app.groupbinder.com/api/v1/trips/01J...

GET /trips/:id/participants

The trip's roster, paginated. Fields: id, reference_code, name, email, phone, emergency_name, emergency_phone, dietary, accessibility, rooming_pref, roommate_request, sms_consent, waitlisted, source, created_at, updated_at.


curl -H "Authorization: Bearer gb_live_..." https://app.groupbinder.com/api/v1/trips/01J.../participants

GET /trips/:id/schedule

The trip's payment schedule: id, label, due_on, amount (money), sort.


curl -H "Authorization: Bearer gb_live_..." https://app.groupbinder.com/api/v1/trips/01J.../schedule

GET /trips/:id/ledger

The trip's payment ledger, paginated: id, participant_id, amount (money), method, source, received_on, reversal_of, created_at. Corrections are reversal rows (reversal_of points at the entry they reverse); entries are never edited or deleted.


curl -H "Authorization: Bearer gb_live_..." https://app.groupbinder.com/api/v1/trips/01J.../ledger

GET /trips/:id/itinerary

The trip's itinerary items: id, day (1-based), time (HH:MM or null for all-day), title, notes, place_name, address, lat, lng, sort. An item with lat and lng is a stop on the trip's map.


curl -H "Authorization: Bearer gb_live_..." https://app.groupbinder.com/api/v1/trips/01J.../itinerary

What v1 does not do

v1 is read-only: no write endpoints, no webhooks, no OAuth. If your integration needs one of those, tell us at trips@groupbinder.com and we will build against real demand.