OMSCourse Search API
DemoAPI reference
Guides

Displaying results

Practical guidance for a clear, honest search experience. See the demo for a working example.

Loading

Searches take 4–8 seconds. Disable the button, show a spinner or skeleton cards and a short message such as "Finding the right OMS courses…". Keep the visitor's question visible.

Results by status

results
Show answer, then course cards, then online activities, then supporting_content as related reading.
no_results
Show answer and follow_up_question (if any), plus a link to browse all OMS courses. Never show an empty grid alone.
clarification_needed
Show follow_up_question prominently with the input ready for a reply. Send the reply with context.
out_of_scope
Show answer and suggest a training-related search.

Course cards

  • Has dates (events not empty): list dates in UK time with location, delivery and price.
  • No upcoming dates (has_upcoming_events: false): say "No dates currently scheduled" and link register_interest_url or course_url.
  • Online/self-paced: items in online_activities have no dates; show "Start any time".

Booking status and links

open
Book button → booking_url.
full
"Full" badge. If booking_url is present it's usually the waiting list: label it with booking_message.
waiting_list
"Waiting list" badge, button labelled booking_message.
unavailable / unknown
No Book button; link event_url or course_url for details.
  • Never show a number of places unless places_remaining is a number.
  • Show prices with VAT basis, e.g. "£324.00 inc VAT (£270.00 + VAT)". If price is null, say "Price on request" or omit.
  • Open booking links unchanged; don't rewrite or shorten them.

Follow-ups

Keep the input visible after results so visitors can refine ("in Leicester", "next month", "online?"). Send the stored context. Offer a "New search" button that clears it. See Conversation context.

Errors and timeouts

  • On 429, 503 or 504: "Search is busy, please try again in a moment." Retry once automatically after Retry-After.
  • On network failure or your own 30-second timeout: the same friendly message with a Retry button.
  • Always keep a plain link to the OMS course list as a fallback.