{"openapi":"3.1.0","info":{"title":"Orita Provider Resolution API","version":"1.0.0","description":"Search your provider network, apply eligibility rules, resolve real-time availability, and safely confirm bookings through one API.","contact":{"name":"Orita","url":"https://orita.online/developers","email":"hola@orita.online"}},"servers":[{"url":"https://orita.online/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your Orita API key as a Bearer token."}},"schemas":{"AnyOf":{"type":"object","description":"Constraint matcher — provider must match at least one value.","properties":{"anyOf":{"type":"array","items":{"type":"string"}}},"required":["anyOf"],"example":{"anyOf":["es"]}},"ResolutionConstraints":{"type":"object","description":"Hard constraints. An option is invalid if any required constraint fails.","properties":{"languageCodes":{"$ref":"#/components/schemas/AnyOf","description":"Provider must speak at least one language."},"modalityCodes":{"$ref":"#/components/schemas/AnyOf","description":"Provider must support at least one modality (virtual, in_person)."},"specialties":{"$ref":"#/components/schemas/AnyOf","description":"Provider must have at least one matching specialty."},"profession":{"type":"string","description":"Exact profession code match."},"acceptsNewClients":{"type":"boolean","description":"If true, only providers accepting new clients are returned."}},"example":{"languageCodes":{"anyOf":["es"]},"modalityCodes":{"anyOf":["virtual"]},"acceptsNewClients":true}},"ResolutionPreferences":{"type":"object","description":"Soft preferences. They affect ranking but do not exclude options.","properties":{"dayParts":{"type":"array","items":{"type":"string","enum":["morning","afternoon","evening"]},"description":"Preferred time of day."},"earliestAvailable":{"type":"boolean","description":"Rank earliest available slot higher."},"continuityProviderId":{"type":"string","description":"Prefer a provider the customer has seen before."}},"example":{"dayParts":["afternoon"],"earliestAvailable":true}},"Resolution":{"type":"object","properties":{"resolutionId":{"type":"string","example":"res_7812"},"status":{"type":"string","enum":["resolved","zero_results","expired","confirmed"]},"expiresAt":{"type":"string","format":"date-time","description":"Resolution expires 5 minutes after creation."},"summary":{"type":"object","properties":{"providersScanned":{"type":"integer"},"eligibleProviders":{"type":"integer"},"providersWithAvailability":{"type":"integer"}}},"options":{"type":"array","items":{"$ref":"#/components/schemas/ResolutionOption"}},"exclusions":{"type":"object","description":"Count of providers excluded per reason."},"warnings":{"type":"array","items":{"type":"string"}}}},"ResolutionOption":{"type":"object","properties":{"optionId":{"type":"string","example":"opt_92ab"},"provider":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"}}},"slot":{"type":"object","properties":{"start":{"type":"string","format":"date-time"}}},"score":{"type":"integer","minimum":0,"maximum":100,"example":94},"matchedConstraints":{"type":"array","items":{"type":"string"}},"reason":{"type":"string","description":"Plain-language explanation of why this option was selected and ranked here."}}},"Hold":{"type":"object","properties":{"holdId":{"type":"string"},"status":{"type":"string","enum":["active","expired","released"]},"expiresAt":{"type":"string","format":"date-time","description":"Hold expires at this time. Default TTL: 120s. Max: 600s."}}},"Booking":{"type":"object","properties":{"bookingId":{"type":"string"},"resolutionId":{"type":"string"},"status":{"type":"string","enum":["confirmed","rescheduled","cancelled","completed"]},"provider":{"type":"object"},"slot":{"type":"object","properties":{"start":{"type":"string","format":"date-time"}}},"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"field":{"type":"string"}}}}},"paths":{"/resolutions":{"post":{"operationId":"createResolution","summary":"Create a provider resolution","description":"Search the provider network, apply hard constraints and preferences, resolve real-time availability, and return ranked explained options. Does NOT create a booking. Resolution expires after 5 minutes.","tags":["Resolution"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["serviceId","dateRange"],"properties":{"serviceId":{"type":"string","example":"svc_therapy","description":"Service or event type ID to resolve."},"dateRange":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date","example":"2026-08-05"},"to":{"type":"string","format":"date","example":"2026-08-12"},"timezone":{"type":"string","example":"America/New_York"}}},"constraints":{"$ref":"#/components/schemas/ResolutionConstraints"},"preferences":{"$ref":"#/components/schemas/ResolutionPreferences"},"limit":{"type":"integer","default":5,"minimum":1,"maximum":20}}},"example":{"serviceId":"svc_therapy","dateRange":{"from":"2026-08-05","to":"2026-08-12","timezone":"America/New_York"},"constraints":{"languageCodes":{"anyOf":["es"]},"modalityCodes":{"anyOf":["virtual"]},"acceptsNewClients":true},"preferences":{"dayParts":["afternoon"],"earliestAvailable":true},"limit":5}}}},"responses":{"200":{"description":"Resolution created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resolution"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized"}}}},"/resolutions/{id}":{"get":{"operationId":"getResolution","summary":"Get a resolution","description":"Retrieve a stored resolution with all options, explanations, and exclusion reasons.","tags":["Resolution"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resolution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resolution"}}}}}}},"/resolutions/{id}/options/{optionId}/hold":{"post":{"operationId":"holdOption","summary":"Hold a resolution option","description":"Temporarily reserve one option. Default TTL: 120 seconds. Maximum: 600 seconds. Does NOT create a booking.","tags":["Resolution"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"optionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttlSeconds":{"type":"integer","minimum":1,"maximum":600,"default":120}}}}}},"responses":{"200":{"description":"Hold created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hold"}}}}}},"delete":{"operationId":"releaseHold","summary":"Release a held option","tags":["Resolution"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"optionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Hold released"}}}},"/resolutions/{id}/confirm":{"post":{"operationId":"confirmResolution","summary":"Confirm a resolution and create the booking","description":"Revalidate availability and atomically confirm the selected option. Creates the booking. Call only after the customer approves the provider, service, time, timezone, and policies. Hold is optional before confirmation.","tags":["Resolution"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Required. Use a stable unique key per confirmation attempt."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["optionId","customer"],"properties":{"optionId":{"type":"string","description":"The optionId from the resolution response."},"customer":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"lastname":{"type":"string"}}},"metadata":{"type":"object","description":"Optional arbitrary metadata to attach to the booking."}}},"example":{"optionId":"opt_92ab","customer":{"name":"James Park","email":"james@example.com"}}}}},"responses":{"201":{"description":"Booking created with status 'pending'. Client receives a confirmation email. Status transitions to confirmed after client clicks the link. Listen for booking.confirmed webhook.","content":{"application/json":{"example":{"data":{"id":"bk_01JZBK...","status":"pending","title":"Therapy Session","date":"2026-08-05T15:00:00.000Z","tokenToConfirm":"ecc4deb7aa22e7e85b...","resolutionId":"res_7812"}}}}},"409":{"description":"Slot no longer available or resolution already confirmed"}}}},"/slots":{"get":{"operationId":"getSlots","summary":"Get available slots for a known provider","description":"Use when the provider is already known. Returns available time slots after removing calendar conflicts. For unknown-provider flows, use POST /resolutions instead.","tags":["Direct Scheduling"],"parameters":[{"name":"providerId","in":"query","required":true,"schema":{"type":"string"}},{"name":"eventTypeId","in":"query","required":true,"schema":{"type":"string"}},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Available slots list"}}}},"/bookings":{"post":{"operationId":"createBooking","summary":"Create a direct booking","description":"Use when the provider is already known and a slot has been selected via GET /slots.","tags":["Direct Scheduling"],"responses":{"201":{"description":"Booking created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}}}}},"/bookings/{id}":{"get":{"operationId":"getBooking","summary":"Get a booking","tags":["Direct Scheduling"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}}}}},"/bookings/{id}/reschedule":{"post":{"operationId":"rescheduleBooking","summary":"Reschedule a booking","description":"Move an existing booking to a new date and time. Cancels the original and creates a new booking. Requires customer approval. Changes external state.","tags":["Direct Scheduling"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date","time"],"properties":{"date":{"type":"string","description":"New date in YYYY-MM-DD format.","example":"2026-08-06"},"time":{"type":"string","description":"New time in HH:MM format in the provider's timezone.","example":"15:00"},"notes":{"type":"string","description":"Optional notes.","required":false}}},"example":{"date":"2026-08-06","time":"15:00"}}}},"responses":{"200":{"description":"New booking created with status 'pending'. Original booking cancelled.","content":{"application/json":{"example":{"data":{"id":"bk_new...","status":"pending","date":"2026-08-06T19:00:00.000Z","end_time":"2026-08-06T20:00:00.000Z"}}}}}}}},"/bookings/{id}/cancel":{"post":{"operationId":"cancelBooking","summary":"Cancel a booking","description":"Requires customer approval. Changes external state.","tags":["Direct Scheduling"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Booking cancelled"}}}},"/professionals":{"post":{"operationId":"createProfessional","summary":"Create a professional","description":"Add a professional to your provider graph. Insurance and license region are stored here and filterable via GET /professionals, but are not hard constraints in resolution.","tags":["Provider Graph"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["displayName"],"properties":{"displayName":{"type":"string"},"professionCode":{"type":"string"},"languageCodes":{"type":"array","items":{"type":"string"}},"specialtyIds":{"type":"array","items":{"type":"string"}},"modalityCodes":{"type":"array","items":{"type":"string"}},"insurancePlanIds":{"type":"array","items":{"type":"string"},"description":"Stored on the provider. Not a resolution constraint."},"licenseRegionIds":{"type":"array","items":{"type":"string"},"description":"Stored on the provider. Not a resolution constraint."},"acceptsNewClients":{"type":"boolean"},"timezone":{"type":"string"}}}}}},"responses":{"201":{"description":"Professional created"}}},"get":{"operationId":"listProfessionals","summary":"List and filter professionals","tags":["Provider Graph"],"responses":{"200":{"description":"Professional list"}}}},"/webhooks":{"put":{"operationId":"configureWebhook","summary":"Configure webhook endpoint","tags":["Reliability"],"responses":{"200":{"description":"Webhook configured"}}}},"/webhooks/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List webhook delivery logs","description":"Inspect delivery attempts, status codes, latency, and response excerpts.","tags":["Reliability"],"responses":{"200":{"description":"Delivery log list"}}}},"/webhooks/deliveries/{id}/replay":{"post":{"operationId":"replayWebhookDelivery","summary":"Replay a webhook delivery","description":"Manually replay a failed or missed webhook delivery. Requires Launch plan or higher.","tags":["Reliability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Delivery replayed"},"402":{"description":"Plan upgrade required (Launch+)"}}}}},"webhooks":{"booking.confirmed":{"post":{"summary":"Booking confirmed","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","example":"booking.confirmed","description":"Event type field is named 'type', not 'event'."},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Booking"}}}}}},"responses":{"200":{"description":"Acknowledged"}}}}},"tags":[{"name":"Resolution","description":"Unknown-provider flow: resolve → hold (optional) → confirm"},{"name":"Direct Scheduling","description":"Known-provider flow: getSlots → book"},{"name":"Provider Graph","description":"Manage professionals and services"},{"name":"Reliability","description":"Webhooks, delivery logs, replay, idempotency"}]}