HomeBook an Intro CallStartup Program
Documentation

Linked Resources and Locations

Learn how services connect to resources and locations to determine who can deliver services and where they're available.

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

Overview

Services define what can be booked, but they need to be linked to:

  • Resources – Who or what delivers the service (staff, equipment, rooms)
  • Locations – Where the service is available (via scoping and resource assignment)

These relationships determine whether a service appears in availability searches and which resources are assigned to appointments.

Service-Resource Relationships

Why Link Resources?

A service without linked resources:

  • Won't appear in availability searches
  • Can't be booked (no one to fulfill it)
  • Exists as a definition only

Linking resources makes services bookable.

How Linking Works

Resources, services, and locations are linked with independent many-to-many associations:

  • One service can be fulfilled by many resources
  • One resource can deliver many services
  • A resource is bookable for a service at a location only when it is linked to both that service and that location

Example:

A dental practice has a "Cleaning" service (company-scoped). At the downtown location:

  • Resource: "Hygienist Sarah" → linked to "Cleaning"
  • Resource: "Hygienist Tom" → linked to "Cleaning"
  • Resource: "Dr. Martinez" → NOT linked to "Cleaning" (does exams, not cleanings)

When customers book a cleaning at downtown, they can be assigned to Sarah or Tom (but not Dr. Martinez).

Creating Resource Links

There are no nested /v3/resource/:id/services or /v3/service/:id/resources routes. Use setAssociations (replace), addAssociations (add), and removeAssociations (remove).

Typical pattern:

  1. Create service
  2. Create or identify resources
  3. Associate the resource with the service and the location

Example API Flow:

# Step 1: Create service
curl -X POST https://v3.onsched.com/v3/service \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Haircut",
    "duration": 30,
    "scope": "COMPANY"
  }'

# Step 2: Link resource to the service and location
curl -X PUT "https://v3.onsched.com/v3/resource/RESOURCE_ID/addAssociations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "services": ["SERVICE_ID"],
    "locations": ["LOCATION_ID"]
  }'

You can also call PUT /v3/service/SERVICE_ID/addAssociations with { "resources": ["RESOURCE_ID"], "locations": ["LOCATION_ID"] }.

Viewing Resource Links

Read the service or resource. List filters use repeated UUID query params, not nested collection routes:

curl https://v3.onsched.com/v3/service/SERVICE_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl "https://v3.onsched.com/v3/resources?services=SERVICE_ID&locations=LOCATION_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Resource Assignment During Booking

Automatic Assignment

When checking availability or creating appointments, OnSched automatically:

  1. Identifies resources linked to the requested service at the location
  2. Filters to resources with availability during the requested time
  3. Assigns resources based on round robin mode (if not specified)

Example:

Customer requests availability for "Haircut" at downtown location:

  • System finds 3 resources linked to "Haircut" at downtown
  • Checks each resource's schedule and existing appointments
  • Returns slots where at least one resource is available

Manual Assignment

You can specify which resource(s) to use:

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

This restricts availability to only the specified resources.

Round Robin Assignment

When multiple resources can fulfill a service, round robin mode determines assignment:

  • RANDOM (default) – Picks any available resource
  • BALANCED – Chooses resource with fewest bookings in the search window
  • NONE – Requires all specified resources to be available (for multi-resource appointments)

See Round Robin Booking for details.

Service-Location Relationships

Via Scoping

Service scope determines initial location availability:

  • Company-scoped – Potentially available at all locations (if resources exist)
  • Location-scoped – Only available at the specified location

See Service Scoping.

Via Resource Assignment

Even company-scoped services are only actually available at locations where:

  1. At least one resource is linked to the service
  2. That resource has availability (schedules, allocations)

Example:

"Consultation" is company-scoped across 5 locations:

  • Location A – 2 resources linked, service shows in availability
  • Location B – 1 resource linked, service shows
  • Location C – No resources linked, service does NOT show in availability
  • Location D – Resources linked but currently on vacation, service might not show availability
  • Location E – Resources linked, service shows

Company scope makes the service eligible everywhere, but resource links make it bookable.

Multi-Location Resource Scenarios

Resource Works at Multiple Locations

A resource can be linked to services at multiple locations:

Example:

Dr. Smith works at 3 locations:

  • Monday: Downtown location
  • Tuesday/Wednesday: Suburban location
  • Thursday/Friday: East side location

Configuration:

  1. Create resource: "Dr. Smith"
  2. Link "Dr. Smith" to services at all 3 locations
  3. Use weekly allocations to define when Dr. Smith is at each location

When customers check availability:

  • Monday searches at downtown show Dr. Smith slots
  • Tuesday searches at suburban show Dr. Smith slots
  • Thursday searches at east side show Dr. Smith slots

See Weekly Allocations for scheduling resources across locations.

Resource Exclusive to One Location

Some resources work at only one location:

Example:

"Massage Room 3" only exists at the spa location:

  • Link to services at spa location only
  • No allocations at other locations needed

This resource never appears in availability for other locations.

Practical Examples

Single-Location Business

Setup:

  • 1 location
  • 3 services: "Consultation", "Follow-up", "Workshop"
  • 2 resources: "Consultant A", "Consultant B"

Configuration:

  • Link both resources to "Consultation" and "Follow-up"
  • Link only "Consultant A" to "Workshop" (specialized skill)

Result:

  • Consultation and follow-up can be booked with either consultant
  • Workshop only shows availability when Consultant A is free

Multi-Location Chain

Setup:

  • 3 locations
  • 5 services (company-scoped)
  • 10 resources (distributed across locations)

Configuration:

  • Location 1: 4 resources, all linked to 5 services
  • Location 2: 3 resources, linked to 3 services (don't offer 2 specialized services)
  • Location 3: 3 resources, all linked to 5 services

Result:

  • Location 1 and 3 offer full menu
  • Location 2 offers subset (2 services never show availability there)

Service Requiring Multiple Resources

Example: Dental procedure needs both a dentist and a hygienist

Configuration:

  • Create service: "Complex Procedure"
  • Link both "Dentist" and "Hygienist" resources to service
  • When booking, use roundRobin: NONE to require both resources available

Result:

  • Availability only shows when both dentist AND hygienist are free
  • Appointment assigns both resources

Managing Resource Links

Adding Resources to Services

As your team grows:

  1. Add new resource records
  2. Link them to appropriate services
  3. Define their availability schedules
  4. Service immediately shows increased availability

No need to modify the service definition itself.

Removing Resources from Services

When staff leave or change roles:

  1. Unlink resource from services they no longer perform
  2. Optionally soft-delete the resource
  3. Existing appointments remain linked (historical data)
  4. Future availability no longer includes that resource

Changing Service Offerings

To expand or contract what a resource can do:

  • Add links – Resource can now perform additional services
  • Remove links – Resource no longer performs certain services

This is more flexible than creating new resources or services.

Troubleshooting

Service not appearing in availability

Check:

  1. Service has at least one resource linked at the location
  2. Resource has availability defined (weekly schedule or allocations)
  3. Resource isn't fully booked during search window
  4. Service isn't soft-deleted
  5. For location-scoped services, LocationId matches the service's location

Wrong resources being assigned

Check:

  1. Round robin mode matches your intent (RANDOM, BALANCED, NONE)
  2. All linked resources are appropriate for the service
  3. Resource filters (ResourceIds parameter) aren't accidentally excluding desired resources
  4. Resource schedules allow them to work during requested times

Resource linked but not showing availability

Check:

  1. Resource has operating hours or allocations defined
  2. Resource isn't marked as unavailable (out of office)
  3. Resource's calendar isn't blocking the time (if external calendar sync enabled)
  4. Resource's existing appointments aren't filling their schedule

Can't link resource to service

Check:

  1. Both service and resource belong to the same company
  2. For location-scoped services, you're linking at the correct location
  3. You have permission to manage resources and services
  4. Resource and service aren't soft-deleted

Best Practices

Link Conservatively

Only link resources to services they can actually deliver:

  • Don't link every resource to every service for convenience
  • Mismatched skills lead to poor customer experiences
  • Over-linking makes assignment logic confusing

Document Specializations

Use resource descriptions or custom fields to note specializations:

{
  "name": "Stylist Jane",
  "description": "Specializes in color treatments and extensions",
  "CustomFields": {
    "certifications": "colorist,extensions",
    "yearsExperience": "10"
  }
}

This helps when deciding which services to link.

Test Availability After Linking

After adding resource links:

  1. Check availability for the service at the location
  2. Verify expected resources appear as assignable
  3. Confirm booking flow works end-to-end

Plan for Absences

When resources are unavailable (vacation, sick, training):

Review Links Periodically

As your business evolves:

  • Audit resource-service links quarterly
  • Remove outdated links (departed staff, discontinued services)
  • Add links for new capabilities
  • Ensure links reflect current reality

API Patterns

Bulk Linking

To link a resource to multiple services:

curl -X PUT "https://v3.onsched.com/v3/resource/RESOURCE_ID/addAssociations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "services": ["service1", "service2", "service3"],
    "locations": ["LOCATION_ID"]
  }'

Retrieving Full Relationship Map

To understand which resources deliver which services:

curl "https://v3.onsched.com/v3/services?include=resources,locations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl "https://v3.onsched.com/v3/resources?services=SERVICE_ID&locations=LOCATION_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Build a map in your application for reporting or UI purposes.

Common Questions

Can a service exist without resources?

Yes, but it won't be bookable. Use this for:

  • Defining services before hiring staff
  • Placeholder services during setup
  • Services delivered by resources you'll link later

Can a resource exist without services?

Yes, but they won't appear in availability. Create resources first, link to services after.

How many resources should a service have?

As many as you have available staff/equipment:

  • Minimum: 1 (service becomes bookable)
  • Typical: 2-5 (provides flexibility and load distribution)
  • Maximum: No limit (large teams, equipment fleets)

More resources = more availability slots.

Can I link resources conditionally?

Not directly. Resource links are static. For conditional logic:

  • Use separate services (e.g., "Beginner Class" vs "Advanced Class" with different resource links)
  • Handle conditionally in your application and filter ResourceIds in availability requests

Related Documentation

Understanding resource-service links is key to making your OnSched implementation work smoothly. Link strategically, and your availability and booking flows will be accurate and efficient.

Updated 14 days ago

Did this page help you?