Appointments endpoints

Appointments are what your integration ultimately cares about. This article covers reading them, keeping your own system in sync, and changing them after they are booked. How they are created is described in Free slots and booking.

Read-only tokens can call the two GET endpoints only. Instance tokens may name the organization with organization_id or organization_external_id; on a single appointment it is optional and must match the appointment's organization. Organization tokens get 404 for appointments of other organizations.

The appointment object

Medical history, private notes of the practitioner, and bank and tax data are never part of the object.

{
  "data": {
    "id": "c6e0b3a9-72d4-4f1b-9a58-0d3f8e2c6b17",
    "external_id": "booking-8812",
    "status": "confirmed",
    "scheduled_at": "2026-10-12T09:00:00+02:00",
    "ends_at": "2026-10-12T09:30:00+02:00",
    "duration": 30,
    "confirmed_at": "2026-10-08T10:20:00+02:00",
    "cancelled_at": null,
    "cancelled_reason": null,
    "completed_at": null,
    "completed_status": null,
    "availability_type": {
      "id": "5d9a2f77-c3e1-4b08-8a64-7e1f0c92d3b6",
      "external_id": "first-visit",
      "display_name": "First visit"
    },
    "appointment_resource": null,
    "doctor": {
      "id": "b7d2e9c4-1a3f-4c58-8e66-2f9a0d7c5b13",
      "external_id": "staff-12",
      "first_name": "Maria",
      "last_name": "Muster"
    },
    "patient": {
      "id": "e41c8a0f-6b9d-4d27-a3f5-90c2b7d1e8a4",
      "external_id": "pat-1001",
      "email": "mary.major@example.com",
      "first_name": "Mary",
      "last_name": "Major"
    },
    "patient_name": "Mary Major",
    "patient_email": "mary.major@example.com",
    "video": {
      "host_join_url": "https://acme.meetone.io/r/7bbb22b73d4e4732",
      "guest_join_url": "https://acme.meetone.io/r/3d4e4722b7327bbb"
    },
    "message_to_patient": "See you on Monday.",
    "message_to_doctor": null,
    "source": "api",
    "created_at": "2026-10-08T10:20:00+02:00",
    "updated_at": "2026-10-08T10:20:00+02:00"
  }
}

Statuses

cancelled takes precedence over completed, and both over the other statuses.

List appointments

GET /api/v1/appointments

Times without an offset are read in Europe/Berlin. Filters combine: all that you send must match.

Without updated_since, the list is ordered by start time, with appointments that have no time last. With updated_since, it is ordered by updated_at.

curl "https://acme.meetone.io/api/v1/appointments?from=2026-10-12T00:00:00%2B02:00&to=2026-10-13T00:00:00%2B02:00&status=confirmed&doctor_external_id=staff-12" \
  -H "Authorization: Bearer $TOKEN"

Show an appointment

GET /api/v1/appointments/{id} returns the appointment in the object shown above, or 404 if it does not exist or belongs to another organization.

Keep your system in sync

The list is the interface for keeping an external system in sync: cancelled appointments stay in it, so a cancellation is just another change you read, and updated_since returns only what changed.

• updated_since=<timestamp> returns the appointments whose updated_at is at or after that time, ordered by updated_at, oldest change first.
• Such a sync pages by cursor, not by page number. Follow the next URL of the link response header until there is none. Its page value is an opaque cursor: do not build it or count it up. A response to a sync has no total-count or total-pages header, so the missing next link is the only signal that you reached the end. A cursor that is malformed returns 422 with the code invalid and the attribute page.
• An appointment that changes while you page comes again further on, after the ones you have not read yet. Store appointments by id (upsert), so reading one twice does no harm.
• Next time, send the updated_at of the last appointment you processed as updated_since, or a minute earlier to be safe. What comes again is simply stored again.
• For the first run, send an updated_since far in the past, for example 2000-01-01T00:00:00+00:00. That reads every appointment, in the same order as later runs, and the last updated_at becomes your first cursor.

import requests
from datetime import datetime, timedelta

BASE = "https://acme.meetone.io/api/v1"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def sync(last_updated_at):
    """Store every appointment changed since the last run; return the new last updated_at."""
    # A minute earlier than the last one we stored, to be safe.
    since = (datetime.fromisoformat(last_updated_at) - timedelta(minutes=1)).isoformat()
    url, params = f"{BASE}/appointments", {"updated_since": since, "per_page": 100}
    while url:
        response = requests.get(url, headers=HEADERS, params=params)
        response.raise_for_status()
        for appointment in response.json()["data"]:
            upsert(appointment)                              # idempotent, keyed by appointment["id"]
            last_updated_at = appointment["updated_at"]      # oldest change first: the last one is the newest
        url = response.links.get("next", {}).get("url")      # the cursor is inside this URL
        params = None                                        # ...which already carries every parameter
    return last_updated_at

Run it on a schedule, for example every few minutes, and persist the returned value after each run. An Organization API Token is rate limited, so poll at a moderate rate; see Rate limits. If you need to react faster, subscribe to webhooks and use the list as the safety net that catches anything a webhook missed.

The same updated_since filter, with the same cursor paging, works on every other list of the Scheduling API, for example users and availabilities.

Update an appointment

PATCH /api/v1/appointments/{id}

Updates only the fields that do not touch the time. To move an appointment, use reschedule.

curl -X PATCH "https://acme.meetone.io/api/v1/appointments/c6e0b3a9-72d4-4f1b-9a58-0d3f8e2c6b17" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message_to_doctor": "Patient asks for a sick note." }'

The response is 200 OK with the updated appointment. An external_id that is already in use returns 422 with the code taken.

Reschedule an appointment

POST /api/v1/appointments/{id}/reschedule

Moves the appointment to a new time, and optionally to another practitioner.

curl -X POST "https://acme.meetone.io/api/v1/appointments/c6e0b3a9-72d4-4f1b-9a58-0d3f8e2c6b17/reschedule" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "starts_at": "2026-10-14T10:30:00+02:00" }'

• The new time has to be a free slot of the appointment's type, with the appointment itself not counting as taken, so you can move it by a few minutes into its own slot. Otherwise the response is 409 with the code slot_unavailable. With ignore_availability: true the slot check is skipped, but the practitioner still cannot be double-booked.
• Only a confirmed or unconfirmed appointment can be moved. A cancelled or completed one, or one without a time, returns 409 with the code not_reschedulable.
• Rescheduling needs appointment booking to be enabled for the organization (403, feature_disabled).
• The slot is checked and the appointment moved under the same lock as when booking, so concurrent requests cannot take the same slot.
• An appointment that was booked with notify: false stays silent: it sends no emails when it is rescheduled either.

The response is 200 OK with the rescheduled appointment.

Cancel an appointment

POST /api/v1/appointments/{id}/cancel

curl -X POST "https://acme.meetone.io/api/v1/appointments/c6e0b3a9-72d4-4f1b-9a58-0d3f8e2c6b17/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Practitioner is ill.", "notify": true }'

The response is 200 OK with the appointment, now with status cancelled. Cancelling closes its video call. The patient and the practitioner are told by email only when the appointment still lies ahead and notify is not false; an appointment that was booked with notify: false stays silent. A missing reason returns 422 with the code blank; an appointment that is already cancelled or completed returns 409 with the code not_cancellable.

The cancelled appointment stays in the list and in your sync.

Complete an appointment

POST /api/v1/appointments/{id}/complete

Records how the appointment went and closes its video call.

curl -X POST "https://acme.meetone.io/api/v1/appointments/c6e0b3a9-72d4-4f1b-9a58-0d3f8e2c6b17/complete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "no_success", "reason": "Patient did not show up." }'

The response is 200 OK with the appointment, now with status completed. An unknown status or a missing reason returns 422. Only a scheduled appointment that is neither cancelled nor completed can be completed; anything else returns 409 with the code not_completable.

Webhooks and notifications

Booking, rescheduling, cancelling and completing through the API do exactly what the same steps do in the app: they send the emails, and they send the webhooks appointment.created, appointment.reschedule, appointment.cancel and appointment.complete to the endpoints that subscribed to them. notify: false holds back the emails only, never the webhooks. See Webhook events reference.

Webhook payloads use their own, older representation, not the objects of this API. Their id, where they have one, is not the UUID id you see here. The UUID is the payload's public_id, so match a webhook to the appointment in this API by public_id. If you give every appointment you book an external_id, that is part of the payload too and matches the webhook to the appointment in your own system. To read the current state, fetch the appointment through the API.

Errors at a glance

Related

• Free slots and booking
• Identifiers
• Webhook events reference
• Errors & pagination

Questions? Contact us at support@meetone.io.