Provider Graph

What is the Provider Graph?

The provider graph is your network of professionals inside Orita. Every provider is a self-contained node with everything Orita needs to route appointments to them.

When you call POST /api/v2/resolutions, Orita runs each provider in your graph through the eligibility rules before checking real-time availability.

Provider Schema

A fully populated provider object looks like this:

{
  "id": "pro_01K...",
  "organizationId": "org_01K...",
  "externalId": "customer-provider-2841",
  "displayName": "Dr. Ana García",
  "email": "ana@example.com",
  "status": "active",
  "searchable": true,
  "professionCode": "clinical_psychologist",
  "specialtyCodes": ["anxiety", "cbt"],
  "languageCodes": ["es", "en"],
  "modalityCodes": ["virtual"],
  "serviceRegionCodes": ["US-NJ"],
  "insurancePlanCodes": ["aetna", "cigna"],
  "ageGroupCodes": ["adult"],
  "licenseRecords": [{
    "licenseTypeCode": "psychologist",
    "regionCode": "US-NJ",
    "status": "active",
    "expiresAt": "2027-06-30",
    "verifiedAt": "2026-07-20T14:00:00Z"
  }],
  "acceptsNewClients": true,
  "timezone": "America/New_York",
  "profileVersion": 12
}

Eligibility Attributes

Orita uses these fields as hard constraints during resolution. If a constraint is present in the resolution request and the provider does not satisfy it, the provider is excluded.

Onboarding a Provider

Three steps to get a provider ready for resolution: create the provider, create a service, then configure availability.

// Step 1 — Create the provider
const resp = await fetch('https://orita.online/api/v2/providers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORITA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    externalId: 'your-provider-id',
    displayName: 'Dr. Ana García',
    email: 'ana@example.com',
    professionCode: 'clinical_psychologist',
    specialtyCodes: ['anxiety', 'cbt'],
    languageCodes: ['es', 'en'],
    modalityCodes: ['virtual'],
    serviceRegionCodes: ['US-NJ'],
    insurancePlanCodes: ['aetna'],
    licenseRecords: [{ licenseTypeCode: 'psychologist', regionCode: 'US-NJ', status: 'active', expiresAt: '2027-06-30' }],
    acceptsNewClients: true,
    timezone: 'America/New_York',
  }),
});
const provider = await resp.json();

// Step 2 — Create a service for them
const service = await orita.eventTypes.create({
  providerId: provider.id,
  title: "Initial Consultation",
  duration: 50,
  price: 80,
  currency: "EUR",
});

// Step 3 — Create availability
const availability = await orita.availability.create({
  providerId: provider.id,
  title: "Default Schedule",
  timezone: "Europe/Madrid",
  days: {
    monday:    { enabled: true,  slots: [{ start: "09:00", end: "17:00" }] },
    tuesday:   { enabled: true,  slots: [{ start: "09:00", end: "17:00" }] },
    wednesday: { enabled: true,  slots: [{ start: "09:00", end: "17:00" }] },
    thursday:  { enabled: true,  slots: [{ start: "09:00", end: "17:00" }] },
    friday:    { enabled: true,  slots: [{ start: "09:00", end: "17:00" }] },
    saturday:  { enabled: false, slots: [] },
    sunday:    { enabled: false, slots: [] },
  },
});

Bulk Import

Use bulk import to upsert up to 500 providers in one call. Use your own stable externalId for each provider. Run a dry import first to validate, then commit.

const response = await fetch(
  'https://orita.online/api/v2/provider-imports',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ORITA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 'upsert',
      dryRun: true,
      providers, // your provider data with externalId fields
    }),
  }
);
const importJob = await response.json();
// { importId, status: 'validating', dryRun: true }

Need a sample dataset? See the example providers.json in the AI Receptionist Provider Routing repo.

Searching Providers

Use GET /api/v2/providers to list your provider graph — useful for admin dashboards or pre-flight checks.

const resp = await fetch(
  'https://orita.online/api/v2/providers?status=active&limit=50',
  { headers: { Authorization: `Bearer ${process.env.ORITA_API_KEY}` } }
);
const { data: providers } = await resp.json();
console.log(`Found ${providers.length} active providers`);

How Providers Flow Into Resolution

When you call POST /api/v2/resolutions, here is what happens under the hood:

All providers in your graph
        │
        ▼
  ┌─────────────────────────────┐
  │  Hard constraint filters    │  ← specialty, language, modality, insurance
  └──────────────┬──────────────┘
                 │ eligible providers
                 ▼
  ┌─────────────────────────────┐
  │  Real-time availability     │  ← checks calendar within dateRange
  └──────────────┬──────────────┘
                 │ available slots
                 ▼
  ┌─────────────────────────────┐
  │  Ranking                    │  ← preference match → density → score
  └──────────────┬──────────────┘
                 │
                 ▼
        Top 10 options returned