What Is a Provider Resolution API?
A provider resolution API accepts a customer need — a set of constraints, preferences, and a time window — searches a network of professionals, applies eligibility rules, checks real-time availability, and returns ranked options with human-readable explanations. The caller does not need to know in advance who should handle the request. That is precisely what the API resolves.
This is the core distinction from every other scheduling tool you may have used. A booking API assumes you already know who to book. A calendar API assumes you already have access to a specific calendar account. A provider resolution API starts from a need and answers the question: who should handle this, and when?
The Problem It Solves
Most scheduling infrastructure is built around a single professional or a small, pre-scoped team. You pick a person, you look at their calendar, you pick a slot, you book it.
That model breaks the moment your platform manages a network. A telehealth company with 200 licensed therapists. A coaching marketplace with 50 specialists across five disciplines. A legal platform routing clients to the right attorney based on case type, jurisdiction, and language.
In these contexts, the central challenge is not calendar lookup. It is who — finding the right professional before you can even ask about when.
Provider resolution is the layer that bridges the two.
The 6-Step Resolution Flow
When you call POST /api/v1/resolutions, Orita executes a deterministic pipeline:
Customer Need
│
â–¼
[Provider Graph] ─── Who is in the network?
│
â–¼
[Eligibility Rules] ─── Who is qualified for this request?
│ (specialty, language, insurance, modality…)
â–¼
[Availability] ─── Who has open slots in the requested window?
│
â–¼
[Conflict Detection] ─── Exclude double-booked or held slots
│
â–¼
[Ranking + Scoring] ─── Score each (provider, slot) pair
│
â–¼
[Explanation] ─── Why was each option returned? Why were others excluded?
│
â–¼
Ranked Options → Caller
Each step produces structured output you can inspect. The API returns not just the options that made it through, but the reasons why other providers were excluded — which is essential for compliance, debugging, and building transparent user experiences.
A Real Resolution Request
Here is a complete example using the Orita SDK:
import Orita from "orita-sdk";
const orita = new Orita({ platformKey: process.env.ORITA_PLATFORM_KEY });
const resolution = await orita.resolveScheduling({
constraints: {
specialtyCodes: { anyOf: ["CBT", "trauma-focused"] },
languageCodes: { anyOf: ["en", "es"] },
modalityCodes: { anyOf: ["virtual"] },
acceptingNewClients: true,
},
dateRange: {
start: "2026-08-04T00:00:00Z",
end: "2026-08-08T23:59:59Z",
},
timezone: "America/New_York",
idempotencyKey: "session-req-abc123",
});
The equivalent raw HTTP call:
POST /api/v1/resolutions
Authorization: Bearer <platform-key>
Idempotency-Key: session-req-abc123
Content-Type: application/json
{
"constraints": {
"specialtyCodes": { "anyOf": ["CBT", "trauma-focused"] },
"languageCodes": { "anyOf": ["en", "es"] },
"modalityCodes": { "anyOf": ["virtual"] },
"acceptingNewClients": true
},
"dateRange": {
"start": "2026-08-04T00:00:00Z",
"end": "2026-08-08T23:59:59Z"
},
"timezone": "America/New_York"
}
The Resolution Response
{
"resolutionId": "res_01j2k3m4n5p6q7r8",
"status": "resolved",
"summary": {
"providersScanned": 47,
"eligibleProviders": 9,
"exclusionReasons": {
"missingSpecialty": 28,
"languageNotMatched": 6,
"noAvailability": 4
}
},
"options": [
{
"optionId": "opt_aabbcc112233",
"slotId": "slot_xxyyzz445566",
"provider": {
"providerId": "prov_88ff99ee00dd",
"name": "Dr. Marina Vidal",
"specialties": ["CBT", "trauma-focused"],
"languages": ["es", "en"],
"modalities": ["virtual"]
},
"slot": {
"start": "2026-08-05T14:00:00Z",
"end": "2026-08-05T15:00:00Z",
"timezone": "America/New_York"
},
"score": 0.94,
"reason": "Matches all constraints. CBT specialty confirmed. Spanish primary language.",
"matchedConstraints": ["specialtyCodes", "languageCodes", "modalityCodes", "acceptingNewClients"]
},
{
"optionId": "opt_ddeeff334455",
"slotId": "slot_aabbcc778899",
"provider": {
"providerId": "prov_11aa22bb33cc",
"name": "James Ortega, LCSW",
"specialties": ["trauma-focused"],
"languages": ["en", "es"],
"modalities": ["virtual"]
},
"slot": {
"start": "2026-08-06T10:00:00Z",
"end": "2026-08-06T11:00:00Z",
"timezone": "America/New_York"
},
"score": 0.87,
"reason": "Matches all constraints. Trauma-focused specialty. English primary, Spanish available.",
"matchedConstraints": ["specialtyCodes", "languageCodes", "modalityCodes", "acceptingNewClients"]
}
]
}
From Resolution to Confirmation
Once you have a resolution, you typically hold an option to prevent it from being booked by a concurrent request, then confirm when the customer selects:
// Hold the top option for 5 minutes while the customer reviews
await orita.holdOption(resolution.resolutionId, resolution.options[0].optionId, {
ttlSeconds: 300,
});
// When the customer confirms their selection
const booking = await orita.confirmResolution(resolution.resolutionId, {
optionId: resolution.options[0].optionId,
customer: {
name: "Ana GarcÃa",
email: "ana@example.com",
timezone: "America/New_York",
},
});
The hold and confirmation are atomic — they prevent double-bookings across concurrent resolution requests targeting the same providers.
How It Differs From Other APIs
| Dimension | Calendar API | Booking API | Provider Resolution API | |---|---|---|---| | Starting point | A specific calendar | A specific person | A customer need | | Primary job | Show free/busy | Reserve a slot | Find who + find when | | Knowledge required | Calendar credentials | Who to book | What the customer needs | | Network size | 1–few | 1–few | Dozens to thousands | | Eligibility logic | None | None | Built-in | | Explanation | None | None | Per-option, per-exclusion |
When Orita Is the Right Solution
- You manage a network of professionals (not a single calendar owner)
- Customer needs must be matched against professional attributes before scheduling
- You need explainable results — why this provider, why not others
- You are building an AI assistant or intake flow that handles scheduling as part of a larger workflow
- Double-booking prevention across concurrent requests is a hard requirement
When Orita Is Not the Right Solution
- Single-professional apps: If you are building a scheduling page for one person or a small fixed team, Orita is unnecessary overhead. Calendly, Cal.com, or Google Calendar API are better fits.
- No eligibility dimension: If all providers in your system are interchangeable (any can serve any request), resolution scoring adds complexity without benefit.
- Already-known provider: If your UI always selects the provider before scheduling, use
POST /api/v1/bookingsdirectly — or a simpler slot API. - Consumer calendar sync: If the task is syncing personal calendars between apps, use a calendar protocol like CalDAV or iCal.
Next Steps
- Multi-Provider Scheduling API: How It Works
- Known-Host Scheduling vs. Provider Resolution
- Try a live resolution in the interactive demo