Requests

Inquiries endpoint for group bookings - turn a school-class or group form on your website into a go~mus request.

The requests endpoint is the bridge from a public inquiry form on your website into go~mus inquiry handling. School classes asking for a guided tour, travel groups with a preferred date, senior groups with special needs - anything that gets advised and confirmed manually in the back office typically starts here.

Unlike tickets, events and tours, requests are not a sales endpoint. A request is not a booking - it kicks off a human workflow.

Full endpoint and schema reference: Swagger.

Endpoints at a glance

EndpointActionAuth
POST /api/v4/requestsCreate a requestAPI user with write access to requests

There is no GET / PUT / DELETE endpoint for requests. Requests are only created; everything else happens in the go~mus back office.

Lifecycle

   Website form
        │
        ▼
   POST /api/v4/requests
        │
        ▼
  ┌────────────┐
  │  pending   │ ─── customer created/linked, address attached
  └─────┬──────┘
        │
        ▼
  ┌────────────┐
  │ registered │ ─── confirmation email to customer (unless skip_confirmation_email)
  └─────┬──────┘
        │
        ▼
   manual in back office: confirm, adjust, convert to booking, decline

Anatomy of a request

Top-level fields:

  • participants (integer) - number of participants in the group
  • companions (integer) - accompanying persons (teachers, supervisors)
  • date (YYYY-MM-DD) - requested visit date (required by model validation)
  • notes (string) - free-text notes, special requirements
  • payment_mode (id or name) - payment mode (e.g. "Rechnung", "Bar")
  • language (id or name) - preferred tour language
  • age_group (id or name) - age group
  • grade (id or name) - school grade
  • proposal_category (id or name) - proposal category
  • category (id or name) - customer category / price target audience (e.g. "Schule")
  • skip_confirmation_email (boolean, default false) - suppress the confirmation email
  • items (array, required, at least one entry) - requested tours
  • customer (object, optional) - customer data

Entry in the items array:

  • tour_id (integer, required) - product id of the requested tour
  • time (HH:MM) - requested start time

Customer object:

  • name, surname, email, phone, mobile
  • salutation, title - by name or id, see Lookups
  • street, zip, city, state, country
  • category, language - by name or id

Common tasks

Create a request

curl -X POST "https://demo.gomus.de/api/v4/requests" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "participants": 15,
      "companions": 2,
      "date": "2026-09-15",
      "notes": "We need wheelchair access.",
      "payment_mode": "Rechnung",
      "language": "Deutsch",
      "age_group": 1,
      "grade": 3,
      "category": "Schule",
      "items": [
        { "tour_id": 42, "time": "14:00" }
      ],
      "customer": {
        "name": "Max",
        "surname": "Mustermann",
        "email": "max@example.com",
        "salutation": "Herr",
        "phone": "+49 30 12345678",
        "street": "Musterstraße 123",
        "zip": "10115",
        "city": "Berlin",
        "country": "Deutschland"
      }
    }
  }'

Success response (200):

{
  "request": {
    "id": 123,
    "created_at": "2026-09-01T10:30:00+02:00",
    "updated_at": "2026-09-01T10:30:00+02:00"
  }
}

Suppress the confirmation email

If your website already sends its own confirmation email after a form submit, the go~mus mail would duplicate it. Set skip_confirmation_email: true:

{
  "request": {
    "skip_confirmation_email": true,
    "...": "..."
  }
}

Default is false (email is sent).

Lookup fields: id or name

Several fields accept either a numeric id or the translated name as a string:

  • payment_mode, language, age_group, grade, proposal_category, category
  • Customer fields: salutation, title, country, state, category, language

The server tries the id first, falls back to a name lookup. Useful when your website form has free text inputs or pulls dropdown values from Lookups.

Pitfalls

  • API user with write access to requests required. A public token does not work, this endpoint is typically proxied server-side. Before going live, ask us to enable write access on your API user, otherwise you hit 401.
  • items must not be empty. At least one { tour_id, time } entry, otherwise 422.
  • date is required. If the visit date is missing, the server rejects the request with 422.
  • Lookup values are instance-specific. Language "Deutsch", category "Schule", age-group ids - all from Lookups, do not hard-code.
  • No lookup after create. There is no GET endpoint for requests. To track the status of a request later, use the go~mus back office or your own state tracking on the website side.
  • Customer linking happens server-side. If the email matches an existing customer (or is found via foreign_id), the request is attached to the existing record. Otherwise the server creates a new customer. Implication: form inputs on your side need to be GDPR-compliant when captured and transmitted.