# Scheduling API overview

> What the Scheduling API v1 covers, the flow from organization to synced appointment, what instance and organization tokens may do, and which features it requires.

Source: https://help.meetone.io/developers/scheduling-api/overview
Last updated: 2026-10-23

---

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

| Resource | Endpoints | What it is |
|---|---|---|
| Organizations | `/api/v1/organizations` | The customer accounts on an installation. See [Organizations endpoints](https://help.meetone.io/developers/scheduling-api/organizations-endpoints). |
| Users | `/api/v1/users` | Practitioners (`doctor`), medical assistants, admins and patients. See [Users endpoints](https://help.meetone.io/developers/scheduling-api/users-endpoints). |
| Availability types | `/api/v1/availability_types` | The kinds of appointment an organization offers: name, length and whether it takes place by video or in person. See [Availability types endpoints](https://help.meetone.io/developers/scheduling-api/availability-types-endpoints). |
| Appointment resources | `/api/v1/appointment_resources` | The places where in-person appointments happen. See [Appointment resources endpoints](https://help.meetone.io/developers/scheduling-api/appointment-resources-endpoints). |
| Availabilities | `/api/v1/availabilities` | When a practitioner offers appointments of a type. See [Availabilities endpoints](https://help.meetone.io/developers/scheduling-api/availabilities-endpoints). |
| Free slots | `/api/v1/availability_slots` | The times a type can still be booked at. See [Free slots and booking](https://help.meetone.io/developers/scheduling-api/availability-slots-and-booking). |
| Appointments | `/api/v1/appointments` | Read, sync, book, reschedule, cancel and complete. See [Free slots and booking](https://help.meetone.io/developers/scheduling-api/availability-slots-and-booking) and [Appointments endpoints](https://help.meetone.io/developers/scheduling-api/appointments-endpoints). |
| Waitlist entries | `/api/v1/waitlist_entries` | The people on the organization's waitlist, read only and with an organization token only. See [Waitlist API overview](https://help.meetone.io/developers/waitlist-api/overview). |

## 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](https://help.meetone.io/developers/scheduling-api/appointments-endpoints#keep-your-system-in-sync).

## 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.

```bash
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"
```

```json
{
  "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:

```bash
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](https://help.meetone.io/developers/scheduling-api/appointments-endpoints#the-appointment-object).

## Tokens: instance and organization

Requests carry an API token in the `Authorization` header, as described in [Authentication & API tokens](https://help.meetone.io/developers/getting-started/authentication-api-tokens). Which kind of token you use decides how far the request reaches.

| | Instance token | Organization token |
|---|---|---|
| Reach | The whole installation. | One organization. |
| Naming the organization | On installations with organizations, `organization_id` or `organization_external_id`. Required to create anything; a filter on lists; optional on a single record, where it must match. | Implicit. Naming any other organization returns `403` (`organization_forbidden`). |
| Records of other organizations | Reachable by naming their organization. | `404`, as if they did not exist. |
| Create and delete organizations | Yes. | No (`403`, `instance_token_required`). |
| Update an organization | All fields. | Its own organization, without the instance-token-only fields (`403`, `attribute_forbidden`). |
| Rate limit | The organization-token limit does not apply. | 50 requests per minute and 100 per five minutes. See [Rate limits](https://help.meetone.io/developers/getting-started/rate-limits). |
| Booking limit | None. | At most 1,000 appointments booked through the API per calendar month. |

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`.

> **Note**
>
> On an installation without organizations there is no organization to name: the organization parameters are ignored, everything runs without an organization, and the organizations endpoints return `404`.

## Feature requirements

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

| Feature | Needed for |
|---|---|
| Appointment booking (`appointment_booking`) | Availability types, availabilities, free slots, booking and rescheduling appointments. |
| In-person appointments (`appointment_resources`) | Appointment resources, and linking an availability type to a resource. |
| Waitlist (`treatment_waitlist`) | Waitlist entries. |

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](https://help.meetone.io/developers/scheduling-api/organizations-endpoints#fields-only-instance-tokens-may-set). 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](https://help.meetone.io/developers/scheduling-api/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](https://help.meetone.io/developers/getting-started/errors-and-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`](https://help.meetone.io/meetone-scheduling-api.yml). Paste it into [editor.swagger.io](https://editor.swagger.io/) for a browsable reference, or feed it into [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) to generate a typed client. Your MeetOne installation also serves the same reference interactively at `/api-docs`.

## In this section

- [Identifiers](https://help.meetone.io/developers/scheduling-api/identifiers)
- [Organizations endpoints](https://help.meetone.io/developers/scheduling-api/organizations-endpoints)
- [Users endpoints](https://help.meetone.io/developers/scheduling-api/users-endpoints)
- [Availability types endpoints](https://help.meetone.io/developers/scheduling-api/availability-types-endpoints)
- [Appointment resources endpoints](https://help.meetone.io/developers/scheduling-api/appointment-resources-endpoints)
- [Availabilities endpoints](https://help.meetone.io/developers/scheduling-api/availabilities-endpoints)
- [Free slots and booking](https://help.meetone.io/developers/scheduling-api/availability-slots-and-booking)
- [Appointments endpoints](https://help.meetone.io/developers/scheduling-api/appointments-endpoints)

Questions? Contact us at [support@meetone.io](mailto:support@meetone.io).