Known-Host Scheduling vs. Provider Resolution

The most important architectural decision in scheduling infrastructure is not which tool to use — it is which model you need. Known-host scheduling assumes you already know who should handle the request. Provider resolution starts from a customer need and finds the right professional from a network. These are not competing products. They solve different problems. Choosing the wrong model for your context creates complexity that no amount of tooling can fix.

Known-Host Scheduling

In known-host scheduling, a specific person or team is the starting point. The question is not who — it is when. You look at a calendar, find available slots, and book one.

This model covers the vast majority of scheduling products on the market:

• Calendly, Cal.com, Google Calendar API: A professional shares a booking link. A customer picks a slot.
• Acuity Scheduling, Squarespace Scheduling: A business sets up services and availability. Customers book against that availability.
• Microsoft Bookings: A team or service is pre-defined. Customers pick from available staff.

The underlying data model is: calendar account → event type → available slots → booking.

When to use it:

• You are building a scheduling page for a specific person (consultant, doctor in a solo practice, freelancer)
• You have a small, fixed team and customers choose their preferred provider themselves
• The scheduling action is the entire user journey, not part of a larger matching workflow
• Providers do not have eligibility attributes that need to match against customer needs

Provider Resolution

In provider resolution, a customer need is the starting point. The question is not when someone is free — it is who is right for this request, and when are they free?

The data model is fundamentally different: customer need → constraints → provider network → eligibility → availability → ranked options → confirmation.

When to use it:

• You manage a network of professionals with varying specialties, languages, or other attributes
• Customers describe what they need and the system finds the right match
• Eligibility rules must be applied before scheduling is even possible
• Double-booking prevention across concurrent intake flows is a hard requirement
• Results need to be explainable — "why this provider, why not others"

Side-by-Side Comparison

| Dimension | Known-Host Scheduling | Provider Resolution | |---|---|---| | Starting point | A specific person or team | A customer need | | Primary question | When is this person free? | Who is right, and when are they free? | | Primary job | Find open time | Find the right professional + time | | Data model | Calendar + event type | Professional + service + eligibility | | Network size | 1 to handful | Dozens to thousands | | Eligibility logic | None | Built-in, per-constraint | | Explanation | None needed | Per-option, per-exclusion | | Concurrency concern | Low | High (multiple customers, same pool) | | Example tools | Calendly, Cal.com, Google Cal API | Orita |

Code: The Known-Host Path

import Orita from "orita-sdk";

const orita = new Orita({ platformKey: process.env.ORITA_PLATFORM_KEY });

// Provider is already known — the customer chose them or was pre-assigned
const { slots } = await orita.getSlots(eventTypeId, "2026-08-05", providerId);

// Book directly — no resolution needed
const booking = await orita.book({
  slotId: slots[0].slotId,
  customer: {
    name: "Laura Méndez",
    email: "laura@example.com",
    timezone: "Europe/Madrid",
  },
});

This maps directly to POST /api/v1/bookings:

POST /api/v1/bookings
Authorization: Bearer <platform-key>
Content-Type: application/json

{
  "slotId": "slot_xxyyzz445566",
  "customer": {
    "name": "Laura Méndez",
    "email": "laura@example.com",
    "timezone": "Europe/Madrid"
  }
}

Simple, fast, requires no resolution step. Two things in, one booking out.

Code: The Provider Resolution Path

// Provider is NOT known — the customer gave us a need, not a name
const resolution = await orita.resolveScheduling({
  constraints: {
    specialtyCodes: { anyOf: ["family-law", "employment-law"] },
    languageCodes: { anyOf: ["es"] },
    jurisdictionCodes: { anyOf: ["CA"] },
  },
  dateRange: {
    start: "2026-08-04T00:00:00Z",
    end: "2026-08-08T23:59:59Z",
  },
  timezone: "America/Los_Angeles",
  idempotencyKey: "intake-case-00432",
});

// Hold the best option while the customer reviews
await orita.holdOption(
  resolution.resolutionId,
  resolution.options[0].optionId,
  { ttlSeconds: 300 }
);

// Confirm after customer selects
const booking = await orita.confirmResolution(resolution.resolutionId, {
  optionId: resolution.options[0].optionId,
  customer: {
    name: "Miguel Torres",
    email: "miguel@example.com",
    timezone: "America/Los_Angeles",
  },
});

The resolution response tells you who was found, who was excluded and why, and provides explainable scores for every option:

{
  "resolutionId": "res_01j2k3m4n5p6q7r8",
  "status": "resolved",
  "summary": {
    "providersScanned": 85,
    "eligibleProviders": 7,
    "exclusionReasons": {
      "missingSpecialty": 54,
      "languageNotMatched": 18,
      "noAvailability": 6
    }
  },
  "options": [
    {
      "optionId": "opt_aabbcc112233",
      "slotId": "slot_xxyyzz445566",
      "provider": {
        "providerId": "prov_88ff99ee00dd",
        "name": "Sofía Parra, Esq.",
        "specialties": ["family-law", "employment-law"],
        "languages": ["es", "en"],
        "jurisdictions": ["CA", "NV"]
      },
      "slot": {
        "start": "2026-08-05T11:00:00Z",
        "end": "2026-08-05T12:00:00Z",
        "timezone": "America/Los_Angeles"
      },
      "score": 0.96,
      "reason": "Matches all constraints. Family and employment law confirmed. Spanish primary. CA jurisdiction.",
      "matchedConstraints": ["specialtyCodes", "languageCodes", "jurisdictionCodes"]
    }
  ]
}

Concrete Scenarios: Which Model Fits?

Scenario A: A consultant's personal booking page

A freelance UX consultant wants clients to book discovery calls. There is one provider. No eligibility filtering needed. → Known-host scheduling. Cal.com or Calendly is the right tool.

Scenario B: A therapist matching platform

An app helps people find a licensed therapist based on specialty, language, modality, and insurance. 150 therapists in the network. → Provider resolution. The app cannot present 150 profiles and ask the user to filter manually.

Scenario C: A small law firm with 5 attorneys

Clients call the firm and are routed to an attorney by the receptionist. The receptionist then books using the attorney's calendar. → Known-host scheduling. The routing decision is human; the scheduling step uses a known provider.

Scenario D: A healthcare intake chatbot

An AI assistant gathers patient intake information and schedules a visit with an appropriate provider based on condition, location, and insurance. The patient does not select a provider — the system does. → Provider resolution. The chatbot needs to match, not just book.

When Orita Is Not the Right Solution

• Small or fixed teams: If you have 5 or fewer providers and customers select them manually, standard scheduling tools are simpler and cheaper.
• No eligibility layer: If all providers are interchangeable, there is no matching problem to solve. Any booking API works.
• Consumer calendar sync: If the task is syncing personal calendars between accounts, use CalDAV or iCal, not a provider network API.
• Pre-selected provider flows: If your UX always has the user pick a provider before scheduling, skip resolution entirely and use POST /api/v1/bookings directly.

Next Steps

• What Is a Provider Resolution API? — foundational concepts
• How a Multi-Provider Scheduling API Works — the resolution pipeline in detail
• Why AI Applications Need Provider-Aware Scheduling — AI + resolution
• Try both paths in the interactive demo

Explore the Provider Resolution API →