Lookups

The go~mus API exposes several lookup endpoints with constant master data - countries, states, dispatch modes, salutations, titles. The ids from these lists appear as values in many other endpoints (customer addresses, order items, filter parameters). This page gathers them in one place.

Full endpoint and schema reference: Swagger.

Endpoints at a glance

Endpoint	What	Where you need the ids
GET /api/v4/countries	List of countries with ISO code	addr_country_id on customers/orders
GET /api/v4/states	States/regions with country link	Address forms, reporting
GET /api/v4/dispatch_modes	Dispatch modes configured on the instance	dispatch_mode_id on annual tickets, orders with shipping
GET /api/v4/customers/salutations	Salutations	customer_salutation_id on customer create
GET /api/v4/customers/titles	Academic titles	customer_title_id on customer create
GET /api/v4/events/categories, audiences, languages	Event filter constants	Event list filters
GET /api/v4/tours/categories, audiences, languages	Tour filter constants	Tour list filters

Sample responses

Countries

curl "https://demo.gomus.de/api/v4/countries"

{
  "countries": [
    { "id": 60, "name": "Deutschland", "code": "DE" },
    { "id": 76, "name": "Frankreich", "code": "FR" }
  ],
  "meta": { "total_count": 249, "page": 1, "per_page": 25 }
}

code is ISO 3166-1 alpha-2. That lets you match the server's country_id against common client-side libraries without waiting for the lookup call to land.

States

curl "https://demo.gomus.de/api/v4/states"

{
  "states": [
    { "id": 3, "name": "Berlin", "country_id": 60 },
    { "id": 1, "name": "Baden-Württemberg", "country_id": 60 }
  ],
  "meta": { "total_count": 16, "page": 1, "per_page": 25 }
}

Dispatch modes

curl "https://demo.gomus.de/api/v4/dispatch_modes"

Response varies per instance - e.g. e-mail, post, on-site pickup, service fee. Never hard-code.

Salutations and titles

curl "https://demo.gomus.de/api/v4/customers/salutations"
curl "https://demo.gomus.de/api/v4/customers/titles"

Salutations are instance-specific. Some houses maintain extra salutations ("Family", "Company") on top of the standard ones. Titles likewise (e.g. "Prof. Dr. Dr.").

Caching note

Lookups practically never change. Caching strategy: refresh once per day locally, render forms from the cached list. This avoids unnecessary round trips on every form render.

At setup time it pays to pull these lists once and translate them into your own schema - the go~mus ids are instance-specific, and keeping a backup mapping helps later audits.

Pitfalls

• Ids are instance-specific. The country "Germany" can be id 60 on one instance and id 1 on another. The ISO codes (code: "DE") are stable; use them as a bridge when syncing between instances.
• Pagination can bite. countries has ~249 entries while the default per_page is 25. On first sync set per_page=300 or iterate over all pages.
• Fetch salutations/titles before customer create. Guessing a salutation id makes the create fail with a validation error.

Related pages

• Customers - uses customer_salutation_id, customer_title_id, addr_country_id
• Orders - addresses with country_id, shipping with dispatch_mode_id
• Annual tickets - personalization with dispatch_mode_id
• Events, Tours - category/audience/language filters