Round Robin Booking

Environment tip: All examples use v3.onsched.com for production. Replace the host with api-stage.onsched.com when calling the staging environment.

What Is Round Robin?

Round robin is the strategy OnSched uses to automatically assign resources to appointments when multiple resources can fulfill a service. Instead of always picking the same resource, round robin distributes bookings fairly.

Why Use Round Robin?

Without Round Robin

If the system always picked the first available resource:

• Resource A gets overbooked (100 appointments)
• Resource B sits idle (10 appointments)
• Resource C barely works (5 appointments)

This creates uneven workload and poor resource utilization.

With Round Robin

The system intelligently distributes appointments:

• Resource A gets 40 appointments
• Resource B gets 38 appointments
• Resource C gets 37 appointments

Everyone stays busy, and no one is overwhelmed.

Round Robin Modes

OnSched supports four modes on the service (roundRobin field). New services default to NONE unless you set another mode.

NONE (API default for new services)

How it works:

• No automatic assignment when consumers omit resources
• Requires explicit resource selection (or you pass ResourceIds yourself in integration code)
• For customer choice, stylist/doctor preference, or multi-resource coordination

Use when:

• Customers must pick a specific resource
• Several resources must be booked together and you will pass each ID
• You want the simplest server-side contract: no implicit pick

Example:

Service "Team Consultation" requires 2 consultants:

• roundRobin: NONE
• Must specify ResourceIds=consultant1&ResourceIds=consultant2
• Availability only shows when all specified resources are free
• System assigns those resources to the appointment

Configuration:

{
  "name": "Team Consultation",
  "roundRobin": "NONE"
}

When using NONE, end users typically cannot complete booking without choosing (or your app supplying) which resource(s) they want.

RANDOM

How it works:

• System picks one eligible resource at random for each slot / assignment
• Equal chance among candidates; does not balance load by count

Use when:

• Any qualified resource is fine
• You do not need even workload distribution

Configuration:

{
  "name": "Haircut",
  "roundRobin": "RANDOM"
}

BALANCED

How it works:

• Counts existing appointments per resource within the availability search date range
• Picks the resource with the fewest bookings in that window (ties broken randomly)

Use when:

• Fair workload matters across staff with similar capacity

Configuration:

{
  "name": "Consultation",
  "roundRobin": "BALANCED"
}

Load calculation window: Counts use startDate–endDate from the request, not lifetime totals.

COMBINED

How it works (availability): With GET /v3/availability, pass every required resource in ResourceIds and set roundRobin=COMBINED. A slot is returned only when each of those resources is free together for the full duration (and padding). Omitting ResourceIds does not infer a list—you must pass the coordinated set.

Use when:

• Joint appointments (e.g. practitioner + room, two roles that must attend)

See: Availability Guide — joint availability section.

Mode Comparison

Configuring Round Robin

Round robin mode is set on the service, not the resource:

curl -X POST https://v3.onsched.com/v3/service \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Massage",
    "duration": 60,
    "roundRobin": "BALANCED",
    "scope": "COMPANY"
  }'

All bookings for "Massage" will use balanced assignment unless overridden with explicit ResourceIds.

API Behavior

Availability Requests

When calling GET /v3/availability, the service’s stored roundRobin (and optional roundRobin query override) determine how each slot lists resources:

• NONE (service default) — slots typically include all eligible resource IDs for that time; you choose (or pass through) IDs at booking.
• RANDOM / BALANCED — omitting ResourceIds returns slots where at least one resource is free; each slot lists one chosen resource according to the mode (see Availability Guide).
• NONE — omitting ResourceIds still returns candidate times; slots usually include every eligible resource ID so the customer (or your UI) picks before booking.
• COMBINED — you must pass the full, fixed ResourceIds set on the availability request; only jointly free times appear.

Example without ResourceIds (typical RANDOM / BALANCED flow):

curl "https://v3.onsched.com/v3/availability?\
startDate=2025-12-01&\
endDate=2025-12-07&\
LocationId=LOCATION_ID&\
ServiceId=SERVICE_ID&\
roundRobin=BALANCED" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

• At least one resource must be free; assignment semantics follow the active mode when you book.

Example with ResourceIds (explicit selection or COMBINED):

curl "https://v3.onsched.com/v3/availability?\
startDate=2025-12-01&\
endDate=2025-12-07&\
LocationId=LOCATION_ID&\
ServiceId=SERVICE_ID&\
ResourceIds=RESOURCE_ID_1&\
ResourceIds=RESOURCE_ID_2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

• Narrows to the listed resources; add roundRobin=COMBINED when all of them must be free together.

Appointment Creation

When calling POST /v3/appointment:

Without ResourceIds (only when the service uses automatic assignment):

Services configured with RANDOM or BALANCED can omit ResourceIds; the API picks an eligible resource. NONE (the default for new services) expects you to pass ResourceIds (or your integration supplies them)—otherwise booking validation fails.

curl -X POST "https://v3.onsched.com/v3/appointment?\
LocationId=LOCATION_ID&\
ServiceId=SERVICE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Customer": {...},
    "Unavailability": {
      "startTime": "2025-12-01T14:00:00Z",
      "endTime": "2025-12-01T14:30:00Z"
    },
    "duration": 30
  }'

• With RANDOM / BALANCED: assigns a resource automatically when omitted.
• With NONE: include ResourceIds in the query string.

With ResourceIds:

curl -X POST "https://v3.onsched.com/v3/appointment?\
LocationId=LOCATION_ID&\
ServiceId=SERVICE_ID&\
ResourceIds=RESOURCE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}'

• Uses the specified resource(s); fails if they are unavailable.

Practical Examples

Scenario 1: Hair Salon (RANDOM)

Setup:

• Service: "Basic Haircut" (roundRobin: RANDOM)
• Resources: 4 stylists

Behavior:

• Customer books 2:00 PM slot
• All 4 stylists are available
• System randomly picks "Stylist C"
• Customer booked with Stylist C

No preference—everyone gets equal opportunity.

Scenario 2: Consulting Firm (BALANCED)

Setup:

• Service: "Strategy Session" (roundRobin: BALANCED)
• Resources: 3 consultants

Situation:

• Consultant A: 8 appointments this week
• Consultant B: 5 appointments this week
• Consultant C: 10 appointments this week

Behavior:

• Customer books Thursday 10:00 AM
• All 3 are available
• System assigns Consultant B (lowest count)
• Balances workload over time

Ensures fair distribution.

Scenario 3: Dental Procedure (NONE)

Setup:

• Service: "Root Canal" (roundRobin: NONE)
• Resources: Dr. Martinez (dentist), Lisa (assistant)

Behavior:

• Customer requests availability
• Must specify both resource IDs
• Availability shows only when both are free simultaneously
• Appointment assigns both resources

No round robin—explicit coordination required.

Scenario 4: Customer Preference (Override)

Setup:

• Service: "Personal Training" (roundRobin: BALANCED)
• Resources: 5 trainers

Behavior:

• Customer wants "Trainer Mike" specifically
• Request includes ResourceIds=trainer-mike-id
• Round robin bypassed
• Availability shows only Mike's open slots
• Appointment assigns Mike

Customer choice overrides round robin.

Advanced Considerations

BALANCED with Different Capacity Resources

If resources have different bookingsPerSlot values:

• Resource A: bookingsPerSlot: 1
• Resource B: bookingsPerSlot: 2 (can handle 2 simultaneous appointments)

BALANCED mode counts appointments, not capacity utilization. Resource B might handle twice as many appointments before being considered "busy."

Recommendation: Use BALANCED with resources of similar capacity, or implement custom load balancing in your application layer.

BALANCED with New Resources

When adding a new resource:

• They start with 0 appointments
• BALANCED mode will heavily favor them initially
• After a few bookings, distribution normalizes

This is expected behavior—new resources naturally receive more initial assignments.

Time Window Effects

BALANCED counts appointments only within the availability search date range. Implications:

• Searching next week? Counts bookings next week only.
• Searching today only? Counts appointments today only.
• Different search windows yield different "balanced" assignments.

For consistent long-term balancing, use broader search windows or implement external tracking.

Round Robin with Holds

When creating holds (POST /appointment/hold):

• Round robin applies the same way
• Holds count toward resource load for BALANCED mode
• Expired holds release the resource (load decreases)

Choosing the Right Mode

Ask these questions:

Do customers care which resource they get?

• No → RANDOM or BALANCED
• Yes → NONE (let customers choose)

Is workload distribution important?

• Yes → BALANCED
• No → RANDOM

Do appointments require multiple resources?

• Yes, fixed set must attend together → use COMBINED on GET /v3/availability with the full ResourceIds set (see Availability Guide).
• Yes, customer picks explicit roster → NONE on the service and require ResourceIds in your flow.
• No → RANDOM or BALANCED.

Maximum control

• Always specify resources → keep NONE (default) or use explicit ResourceIds with any mode
• Automatic single assignee → RANDOM or BALANCED
• Everyone in a fixed group must be free → COMBINED on availability, then book with that set

Mixing Modes

Different services can use different modes:

[
  {
    "name": "Quick Trim",
    "roundRobin": "RANDOM"
  },
  {
    "name": "Color Treatment",
    "roundRobin": "BALANCED"
  },
  {
    "name": "Bridal Package",
    "roundRobin": "NONE"
  },
  {
    "name": "Tandem Massage",
    "roundRobin": "NONE"
  }
]

(COMBINED is selected per GET /v3/availability query, not stored as the service default.)

Match the mode to service requirements.

Overriding Round Robin

You can always override round robin by specifying ResourceIds in availability or appointment requests, regardless of service configuration.

Use override for:

• Customer preferences ("I want Dr. Smith")
• Returning customers (book with same resource)
• VIP experiences (specific staff member)
• Testing (assign to specific resource for QA)

Troubleshooting

BALANCED not distributing evenly

Check:

1. Search date range—BALANCED counts appointments within search window only
2. Resource availability—if some resources have limited hours, they naturally get fewer bookings
3. Booking patterns—balancing happens over time; short-term imbalances are normal

NONE mode failing with error

Check:

1. Did you specify ResourceIds?
2. Are all specified resources available during the slot?
3. Are specified resources linked to the service?

Resources still getting uneven bookings with BALANCED

Possible reasons:

1. Resources have different availability (one works part-time)
2. External calendar blocks (one resource has many external events)
3. Different bookingsPerSlot values
4. Customers explicitly requesting certain resources

Balanced mode helps but doesn't guarantee perfect distribution if underlying factors differ.

Round robin applying when I don't want it

Solution:

• Always specify ResourceIds to bypass round robin
• Or set service to roundRobin: NONE to require explicit selection

Best Practices

Start from the API default (NONE)

Unless you need automatic assignment:

• NONE is the default for new services—require or pass ResourceIds when booking
• Add RANDOM for "any provider is fine"
• Switch to BALANCED when you need fair counts in the search window
• Use COMBINED on availability when a fixed set must all be free

Use BALANCED for Staff Fairness

If fair workload matters (compensation, morale, burnout prevention):

• Choose BALANCED
• Monitor actual distribution over time
• Adjust resource availability if needed

Reserve automatic modes when they earn their keep

Use RANDOM or BALANCED only when you want the API to choose a single assignee without the customer picking. Stick with NONE (the service default) when staff choice, compliance, or multi-resource coordination matters—NONE often adds a UI step, which is appropriate when preferences or audit trails need it.

Let Customers Override When Appropriate

Even with RANDOM or BALANCED:

• Allow customers to request specific resources
• Show resource profiles (photos, bios, reviews)
• Pass ResourceIds for preferred bookings

Flexibility improves customer satisfaction.

Document Your Choice

Record why you chose each mode:

• "Haircut uses BALANCED because stylists prefer equal bookings"
• "Massage uses RANDOM because all therapists are equally popular"
• "Team consult uses NONE because customers must pick both roles"
• "Joint procedures use COMBINED on availability so both resources share the slot"

This helps future decision-making.

Related Documentation

• Resources Overview – Resource configuration
• Services Overview – Service setup
• Availability Guide – How round robin affects availability
• Appointments – Booking with resource assignment
• Linked Resources – Connecting resources to services

Round robin makes resource assignment automatic and fair. Choose the right mode for your business model, and OnSched handles the complexity of distribution for you.