# Waitlist API overview

> Read your organization's waitlist through the API: who is waiting, what they answered, and where each entry stands from confirmation to booking or deletion.

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

---

The Waitlist API lets your own system read your organization's waitlist: the people who asked for an appointment through your waitlist form, what they answered, and where each of them stands. Use it to bring the list into your practice management software, to report on it, or to match people to free capacity in your own planning.

The Waitlist API is part of the Scheduling API v1. It uses the same base path `/api/v1`, the same tokens, the same conventions and the same OpenAPI document, so everything under [Conventions](https://help.meetone.io/developers/scheduling-api/overview#conventions) in the Scheduling API overview applies here too.

## What the API covers

| Endpoint | Purpose |
|---|---|
| `GET /api/v1/waitlist_entries` | List and filter the entries; the interface for syncing. |
| `GET /api/v1/waitlist_entries/{id}` | Show one entry. |

The API is **read only**. Entries come from your waitlist form alone, and your team invites, archives and deletes them in MeetOne on the **Waitlist** page. There is no endpoint to create, change or delete an entry, and no webhook for waitlist changes: poll the list as described in [Waitlist entries endpoints](https://help.meetone.io/developers/waitlist-api/waitlist-entries-endpoints#keep-your-system-in-sync).

## Requirements

- **An Organization API Token.** Waitlist entries are personal data of one organization, so only that organization's own token can read them. An Instance API Token gets `403` with the code `organization_token_required`. A read-only token is enough, and it is the right choice for a job that only reads. See [Authentication & API tokens](https://help.meetone.io/developers/getting-started/authentication-api-tokens#organization-api-token-scoped-access) for how to get one.
- **The waitlist enabled for your organization.** Without it, both endpoints return `403` with the code `feature_disabled`.

Organization API Tokens are rate limited to 50 requests per minute and 100 per five minutes. See [Rate limits](https://help.meetone.io/developers/getting-started/rate-limits).

## From sign-up to booking

An entry passes through these steps. The API sees it from step 2 on.

1. **Sign-up.** Someone fills in your waitlist form, through the waitlist link, the iFrame or the website widget. MeetOne sends them a link to confirm their email address.
2. **Confirmation.** Once they confirm, the entry is on the list with the status `waiting`, and `email_confirmed_at` is set. Until then the entry does not exist for the API: it is in no list, and asking for it returns `404`. An address that is not confirmed within 7 days is deleted.
3. **Invitation.** Your team invites the person to book an appointment. The entry becomes `invited`, and `invitation` describes the invitation, including the practitioner and the availability type when it is limited to one. Inviting again replaces the invitation.
4. **Booking.** The person books through the invitation. The entry becomes `booked`, and `invitation.appointment_id` is the `id` of the appointment, which you can read with [Appointments endpoints](https://help.meetone.io/developers/scheduling-api/appointments-endpoints). The appointment is booked for the entry's name and email address. A waitlist entry is not a user, so the appointment's `patient` is `null` unless a patient account with that address exists.

While an entry is `waiting` or `invited`, MeetOne asks the person every 6 months by email whether they are still interested. An answer sets `last_reconfirmed_at`. Without an answer within 30 days the entry is archived.

## Statuses

| `status` | Meaning |
|---|---|
| `waiting` | On the list. An entry also returns to `waiting` when its invitation can no longer be used, for example because its availability type was deleted, and when the person answers the "still interested?" email after their entry was archived for not answering. |
| `invited` | Has been invited to book. `invitation` describes the invitation. |
| `booked` | Has booked through the invitation. `invitation.appointment_id` names the appointment. |
| `archived` | Off the list: archived by your team, or because the "still interested?" email went unanswered. An open invitation is withdrawn, so `invitation` is `null`. The entry is deleted 30 days after it was archived. |
| `withdrawn` | Not used. Someone who leaves the list is deleted, and their entry disappears. The value stays in the API's list of statuses so that clients filtering by it keep working. |

## Deleted entries disappear

An entry is deleted, and from then on missing from every list and answered with `404`, when:

- your team deletes it in MeetOne,
- the person leaves the waitlist with the link in the emails MeetOne sends them about it (confirmation, invitation, "still interested?"),
- it was archived 30 days ago.

The API does not report deletions, and a sync with `updated_since` never returns a deleted entry. Read the whole list from time to time and remove from your system what is no longer in it, so your copy does not keep people MeetOne has already deleted. [Waitlist entries endpoints](https://help.meetone.io/developers/waitlist-api/waitlist-entries-endpoints#remove-deleted-entries) shows how.

## First request

The following request lists the people still waiting for an invitation, oldest sign-up first. Replace `acme` with your tenant and use your organization's token.

```bash
export TOKEN="eyJhbGciOiJIUzI1****"

curl "https://acme.meetone.io/api/v1/waitlist_entries?status=waiting" \
  -H "Authorization: Bearer $TOKEN"
```

```json
{
  "data": [
    {
      "id": "8a3f6d21-4c7e-4b9a-a1d2-6e5f0c9b7d34",
      "status": "waiting",
      "first_name": "Mary",
      "last_name": "Major",
      "email": "mary.major@example.com",
      "submitted_at": "2026-09-14T08:12:44+02:00",
      "updated_at": "2026-09-14T08:15:02+02:00"
    }
  ]
}
```

(Abbreviated; every field is described in [Waitlist entries endpoints](https://help.meetone.io/developers/waitlist-api/waitlist-entries-endpoints#the-waitlist-entry-object).)

## The OpenAPI specification

The waitlist endpoints are part of the Scheduling API's OpenAPI document, [`/meetone-scheduling-api.yml`](https://help.meetone.io/meetone-scheduling-api.yml), under the tag `Waitlist entries`. Your MeetOne installation serves the same reference interactively at `/api-docs`.

## In this section

- [Waitlist entries endpoints](https://help.meetone.io/developers/waitlist-api/waitlist-entries-endpoints)

## Related

- [Scheduling API overview](https://help.meetone.io/developers/scheduling-api/overview)
- [Authentication & API tokens](https://help.meetone.io/developers/getting-started/authentication-api-tokens)
- [Errors & pagination](https://help.meetone.io/developers/getting-started/errors-and-pagination)

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