Common integration patterns

This guide collects the integration patterns teams ask for most often. Use it to shape your architecture before you commit to one-off scripts or aggressive polling.

Pattern 1: CRM or CDP sync with webhooks

Use webhooks when another system should react to participant, reward, booking, or Smart Link activity without polling.

A common pattern looks like this:

Recommended habits:

• separate the OmniLab receiver from the downstream CRM write logic
• verify signatures before the event enters your queue
• keep the receiver idempotent by storing webhook-id
• subscribe only to the event types the CRM actually uses

Pattern 2: Analytics and warehouse export

This is the right pattern when you want OmniLab engagement data in BI dashboards, a data lake, or a warehouse.

Event types commonly used here include:

• touchpoint.page_visit.v1
• touchpoint.participated.v1
• touchpoint.completed.v1
• reward.won.v1
• reward.redeemed.v1
• smartlink.redirected.v1

Prefer event-driven ingestion over high-frequency polling. If you still need backfills, run them in paginated batches outside peak traffic.

Pattern 3: Build a booking self-service view

This pattern is useful when a participant-facing portal or mobile app should display upcoming bookings and allow cancellations.

1. Fetch bookings for one contact

Use GET https://<api-host>/v1/interactions:fetchContactBookings with the participant's external ID and any filters you need.

curl -X GET "https://<api-host>/v1/interactions:fetchContactBookings?external_id=CONTACT-123&booking_status=CONFIRMED&page_size=50&page_number=1"       -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Available query parameters include:

• external_id (required)
• interactions or public_keys to narrow the result set
• slot_date_range.from and slot_date_range.to
• booking_status
• page_size
• page_number

Use either interactions or public_keys for filtering, not both at the same time.

The response includes a paginated bookings array with fields such as:

• activity
• interaction
• ticket_type
• host
• slot_starting_at
• slot_duration_in_minutes
• booking_status
• booked_at, cancelled_at, checkedin_at
• booking
• timezone

Current booking statuses include CONFIRMED, CANCELLED, CHECKED_IN, and WAITLIST.

2. Cancel a booking

Use POST https://<api-host>/v1/interactions:cancelInteractionBooking with the booking ID returned by the fetch call.

curl -X POST "https://<api-host>/v1/interactions:cancelInteractionBooking"       -H "Authorization: Bearer YOUR_ACCESS_TOKEN"       -H "Content-Type: application/json"       -d '{
    "booking": "BOOKING_ID"
  }'

A successful cancellation returns an empty JSON object.

3. Good booking UX practices

• show all booking times in the timezone returned by OmniLab
• ask the participant to confirm before cancellation
• refresh the booking list after cancellation succeeds
• handle empty booking lists gracefully
• keep date inputs and filters in UTC when you call the API

Pattern 4: Controlled automation around campaigns or downstream systems

Some teams need an API-assisted workflow around campaigns, rewards, or participants. Because the full public API reference is not published yet, the safest pattern is to keep that automation controlled and explicit.

• confirm the supported endpoint list with OmniLab before development starts
• put the automation behind a feature flag on your side
• validate the full flow in staging before production
• keep audit logs of every automated action your system performs

Related