Scheduling API overview

The Scheduling API (/api/v1) lets your system run organizations and appointment scheduling in MeetOne: create organizations and their users, define what can be booked and when, offer free slots, book appointments, and keep your own system in sync.

What the API covers

From organization to synced appointment

The resources build on each other. A complete integration walks through them in this order:

1. Organization. Create the organization with POST /api/v1/organizations using an instance token, optionally together with its owner. If you integrate a single existing organization with its own organization token, skip this step.
2. Users. Create the practitioners who offer appointments, plus medical assistants and admins as needed. Patients can be created up front, or inline when you book their first appointment.
3. Availability types and appointment resources. Define what can be booked: each availability type has a length (slot_duration) and a place. A type without an appointment resource is an online video appointment; a type with one is held in person at that place.
4. Availabilities. Give each practitioner blocks of time per type, optionally repeating daily or weekly.
5. Free slots. Ask GET /api/v1/availability_slots which times of a type can still be booked.
6. Booking. Book a slot with POST /api/v1/appointments. The appointment is confirmed immediately and, for video types, comes with its join links.
7. Changes. Reschedule, cancel or complete the appointment as it progresses.
8. Sync. Poll GET /api/v1/appointments?updated_since=... to keep your own system current. Cancelled appointments stay in the list. See Appointments endpoints.

Try it: look up slots and book one

The following requests use an organization token and the external_id of an availability type your system assigned earlier. Replace acme with your tenant.

export TOKEN="eyJhbGciOiJIUzI1****"

curl "https://acme.meetone.io/api/v1/availability_slots?availability_type_external_id=first-visit&from=2026-10-12&to=2026-10-16" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "starts_at": "2026-10-12T09:00:00+02:00",
      "ends_at": "2026-10-12T09:30:00+02:00",
      "doctors": [{ "id": "b7d2e9c4-1a3f-4c58-8e66-2f9a0d7c5b13", "external_id": "staff-12" }]
    }
  ]
}

Book the first slot. The patient is looked up by external_id or email and created if they do not exist yet:

curl -X POST "https://acme.meetone.io/api/v1/appointments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "availability_type_external_id": "first-visit",
    "starts_at": "2026-10-12T09:00:00+02:00",
    "patient": {
      "external_id": "pat-1001",
      "email": "mary.major@example.com",
      "profile": { "first_name": "Mary", "last_name": "Major" }
    }
  }'

The response is 201 Created with the appointment in the { "data": { ... } } envelope. Every field is described in Appointments endpoints.

Tokens: instance and organization

Requests carry an API token in the Authorization header, as described in Authentication & API tokens. Which kind of token you use decides how far the request reaches.

A token is either read and write, or read only. A read-only token can call the GET endpoints only; everything else returns 403 with the code read_only_token.

Feature requirements

Some endpoints depend on features that are enabled per organization. Without the feature they return 403 with the code feature_disabled.

Users, organizations and reading, cancelling or completing appointments do not need a feature. An instance token switches features on or off with the features field of the organization; see Organizations endpoints. Installations that run in rooms-only mode have no scheduling, and the scheduling endpoints return 404 there.

Conventions

• Base URL. https://{tenant}.meetone.io, the same tenant subdomain you use for the Video API. All paths start with /api/v1.
• JSON. Requests with a body use Content-Type: application/json. A body that is not valid JSON returns 400 (invalid_json).
• Envelope. Lists return { "data": [ ... ] }, single records { "data": { ... } }.
• Identifiers. Every record has a UUID id and an optional external_id you set yourself; references accept either form. See Identifiers.
• Times. ISO 8601 with an offset, for example 2026-10-08T14:30:00+02:00. A time without an offset is read in Europe/Berlin, and every response uses that time zone.
• Errors and pagination. One error format with stable codes, page and per_page on every list, and updated_since for syncing, which pages by cursor. See Errors & pagination.
• Null instead of empty. Fields without a value are null, never an empty string.
• No internal data. Responses contain no internal numeric IDs, tokens, or bank and tax data.

The OpenAPI specification

The full API is described in an OpenAPI 3.0 document: /meetone-scheduling-api.yml. Paste it into editor.swagger.io for a browsable reference, or feed it into OpenAPI Generator to generate a typed client. Your MeetOne installation also serves the same reference interactively at /api-docs.

In this section

• Identifiers
• Organizations endpoints
• Users endpoints
• Availability types endpoints
• Appointment resources endpoints
• Availabilities endpoints
• Free slots and booking
• Appointments endpoints

Questions? Contact us at support@meetone.io.