HomeBook an Intro CallStartup Program
Documentation
Start typing to search…

Linked Services and Locations

Learn how resources connect to services and locations, enabling multi-location scheduling and flexible resource assignment.

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

Overview

Resources must be linked to both services and locations to be useful. These links determine:

  • Which services a resource can deliver
  • Where the resource works
  • When the resource appears in availability

Without proper linking, resources remain dormant—defined but not bookable.

Resource-Service Links

Why Link to Services?

A resource without service links:

  • Won't appear in availability searches
  • Can't be assigned to appointments
  • Exists as metadata only

Linking to services makes resources functional.

How Service Links Work

Links are many-to-many:

  • One resource can deliver multiple services
  • One service can be fulfilled by multiple resources
  • Links are location-specific

Example:

Resource "Dr. Smith" can perform:

  • "General Checkup"
  • "Follow-up Consultation"
  • "Specialist Exam"

When customers book any of these services at Dr. Smith's locations, she's eligible for assignment.

Creating Service Links

Link a resource to services it can perform:

curl -X POST "https://v3.onsched.com/v3/resource/RESOURCE_ID/services" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ServiceId": "service-uuid",
    "LocationId": "location-uuid"
  }'

This creates a link at the specified location. Repeat for each service-location combination.

Viewing Service Links

See which services a resource can perform:

curl https://v3.onsched.com/v3/resource/RESOURCE_ID/services \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "data": [
    {
      "id": "service-1-id",
      "name": "Haircut",
      "duration": 30
    },
    {
      "id": "service-2-id",
      "name": "Color Treatment",
      "duration": 90
    }
  ]
}

Removing Service Links

Unlink a resource from a service:

curl -X DELETE "https://v3.onsched.com/v3/resource/RESOURCE_ID/services/SERVICE_ID?LocationId=LOCATION_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The resource can no longer fulfill that service at that location.

Resource-Location Relationships

How Location Links Work

Resources don't have a single "home" location. Instead, they're linked to locations through:

  1. Service links – Resource linked to services at specific locations
  2. Weekly allocations – Explicit schedules defining when resource works at each location
  3. Single allocations – One-time blocks for specific location work

This flexibility supports:

  • Multi-location resources (work at multiple sites)
  • Mobile resources (travel to customers)
  • Shared resources (pool across locations)

Single-Location Resources

Most resources work at one location:

Example:

"Exam Room 3" only exists at the downtown clinic:

  1. Create resource: "Exam Room 3"
  2. Link to services at downtown location
  3. Set availability (operating hours)

This resource never appears at other locations.

Multi-Location Resources

Some resources work at multiple locations with different schedules:

Example:

"Consultant Jane" works:

  • Mondays: Location A
  • Tuesdays/Wednesdays: Location B
  • Thursdays/Fridays: Location C

Configuration:

  1. Create resource: "Consultant Jane"
  2. Link to services at all three locations
  3. Create weekly allocations defining which days she's at each location

Weekly Allocation Example:

{
  "ResourceId": "jane-id",
  "LocationId": "location-a-id",
  "dayOfWeek": 1,
  "startTime": "09:00",
  "endTime": "17:00"
}

Repeat for each day-location combination.

See Weekly Allocations for full configuration.

Mobile Resources

For resources that travel to customers:

Example:

"Mobile Detailing Van" serves customers at their addresses:

  1. Create resource: "Detailing Van #2"
  2. Link to mobile services at a "virtual" location (e.g., "Service Area North")
  3. Set broad availability
  4. Store customer addresses in appointment location field

The "location" in OnSched represents the service territory, not a physical office.

Availability with Multi-Location Resources

How It Works

When checking availability:

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

The system:

  1. Identifies resources linked to SERVICE_ID at LOCATION_B_ID
  2. Checks if resources have allocations at Location B during the date range
  3. Returns slots where resources are available

Example:

Consultant Jane works at Location B only on Tuesdays/Wednesdays:

  • Monday search: Jane's slots don't appear (she's at Location A)
  • Tuesday search: Jane's slots appear (she's at Location B)
  • Thursday search: Jane's slots don't appear (she's at Location C)

Allocations ensure resources only show availability where they actually work.

No Allocation = No Availability

If a resource is linked to services at a location but has NO allocation there, they won't appear in availability for that location.

Fix: Create weekly or single allocations to define when the resource is present.

Practical Examples

Example 1: Single-Location Clinic

Setup:

  • 1 location: "Main Clinic"
  • 3 resources: "Dr. A", "Dr. B", "Nurse C"
  • 5 services: Various medical services

Configuration:

  • Link all resources to appropriate services at Main Clinic
  • Set weekly operating hours for each resource
  • No allocations needed (single location, simple schedules)

Result:

All resources appear in availability at Main Clinic based on their schedules.

Example 2: Multi-Location Franchise

Setup:

  • 3 locations: Downtown, Suburban, Airport
  • 10 resources: 8 location-specific, 2 shared

Configuration:

Location-specific resources:

  • Downtown: Resources 1-3 linked to services at Downtown only
  • Suburban: Resources 4-6 linked to services at Suburban only
  • Airport: Resources 7-8 linked to services at Airport only

Shared resources:

  • Manager linked to services at all 3 locations
  • Weekly allocations:
    • Monday/Tuesday: Downtown
    • Wednesday: Suburban
    • Thursday/Friday: Airport

Result:

  • Most resources always work at one location
  • Manager appears in availability at the correct location each day

Example 3: Consulting Firm

Setup:

  • 5 locations (client offices)
  • 15 consultants (work remotely and at client sites)

Configuration:

  • All consultants linked to all services at all locations
  • Use single allocations for specific client visit days
  • No weekly pattern (project-based scheduling)

Result:

  • Consultants appear in availability only when explicitly allocated to client locations
  • Flexible, project-driven scheduling

Managing Links at Scale

Bulk Linking

To link one resource to multiple services:

for SERVICE_ID in service1 service2 service3; do
  curl -X POST "https://v3.onsched.com/v3/resource/RESOURCE_ID/services" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"ServiceId\": \"$SERVICE_ID\",
      \"LocationId\": \"LOCATION_ID\"
    }"
done

Templating New Resources

When adding similar resources (e.g., new stylists):

  1. Document standard service links for that role
  2. Apply same links to new resources
  3. Customize as needed for specializations

Auditing Links

Regularly review:

  • Resources without service links (inactive?)
  • Services without resource links (unavailable?)
  • Mismatched links (wrong services for a resource)

Troubleshooting

Resource not appearing in availability for a location

Check:

  1. Resource is linked to the requested service at that location
  2. Resource has availability defined for that location (allocation or schedule)
  3. Location operating hours allow bookings
  4. Resource isn't fully booked or out-of-office

Resource showing at wrong location

Check:

  1. Service links—confirm links are at correct locations only
  2. Allocations—verify weekly/single allocations target correct locations
  3. Location ID in request matches expectation

Can't link resource to service

Check:

  1. Both resource and service belong to same company
  2. Location ID is valid and belongs to company
  3. Service isn't soft-deleted
  4. You have permission to manage resources/services

Service shows availability but no resources assigned

Check:

  1. Service has resources linked at the location
  2. At least one linked resource has availability
  3. Round robin mode isn't set to NONE without specified ResourceIds

Best Practices

Link Intentionally

Only link resources to services they can actually deliver:

  • Don't link all resources to all services for convenience
  • Mismatched skills lead to booking errors
  • Maintain accurate links for reliable availability

Use Allocations for Complex Schedules

For resources with:

  • Variable schedules
  • Multi-location work
  • Project-based availability

Use weekly or single allocations instead of simple weekly schedules.

Document Resource Capabilities

Use resource descriptions or custom fields:

{
  "name": "Stylist Jamie",
  "description": "Specializes in balayage and extensions",
  "CustomFields": {
    "certifications": "colorist,extensions",
    "languages": "en,es"
  }
}

This helps when deciding which services to link.

Test After Linking

After creating or modifying links:

  1. Check availability for affected services
  2. Verify expected resources appear
  3. Book test appointment to confirm assignment
  4. Review appointment details

Keep Links Updated

As your business evolves:

  • Add links for new capabilities
  • Remove links when staff leave or change roles
  • Update allocations when schedules change

Common Questions

Can a resource be linked to services at multiple locations?

Yes! This is common for multi-location resources. Use allocations to define when they're at each location.

What if a resource can only do certain services at certain locations?

Link them selectively:

  • Link to Service A at Location 1 only
  • Link to Service B at Location 2 only
  • Don't link to Service A at Location 2

Links are location-specific by design.

How do I temporarily remove a resource from a location?

Instead of unlinking services, create an out-of-office block for the resource at that location. This preserves links while blocking availability.

Can I link a resource to company-scoped services?

Yes. When linking to company-scoped services, you still specify which location the link applies to. The service is defined company-wide, but resource links are location-specific.

Do location-scoped services work differently with resource links?

No—the linking mechanism is identical. Location-scoped services just happen to be defined for one location, so resource links naturally exist only at that location.

Advanced Scenarios

Resource Pool

For equipment or interchangeable resources:

Example: 10 identical bikes

Option 1: Create 10 separate resources, link to "Bike Rental" service

Option 2: Create 1 resource "Bike Fleet" with bookingsPerSlot: 10

Option 2 is simpler for true commodity resources.

Resource Teams

For appointments requiring multiple resources:

Example: Surgery needs surgeon + anesthesiologist + OR

Configuration:

  • Service: "Surgery" with roundRobin: NONE
  • Resources: Link surgeon, anesthesiologist, and OR to "Surgery" at location
  • When booking, specify all three ResourceIds
  • Availability shows only when ALL are free

Tiered Services by Resource

Example: Haircut by junior vs senior stylist

Option 1: One service with all stylists linked; customer accepts assignment

Option 2: Two services ("Standard Haircut", "Premium Haircut") with different resources linked

Option 2 gives customers choice and can support different pricing.

Related Documentation

Proper linking is the foundation of a working OnSched system. Link resources to services at the right locations, define their availability, and the platform handles the rest.

Updated 4 days ago