An availability type is a kind of appointment an organization offers, for example "First visit, 30 minutes, by video". Availabilities, free slots and bookings always belong to exactly one type, so a type is the first thing to create when you set up scheduling.

Requirements

  • Appointment booking must be enabled for the organization. Without it every endpoint on this page returns 403 with the code feature_disabled. See Scheduling API overview.
  • In-person appointments must be enabled to link a type to an appointment resource. A type without a resource needs nothing extra.
  • Instance tokens name the organization with organization_id or organization_external_id when they create a type, and may use them as a filter on lists.

The availability type object

Field Type Description
id string (uuid) MeetOne's ID of the type.
external_id string, nullable Your key for the type. Unique within the organization. See Identifiers.
display_name string The name shown to patients and staff, e.g. First visit.
identifier string A short key made of lower-case letters, digits, - and _, unique within the organization. Derived from display_name when you do not send one, e.g. first-visit. Reserved identifiers such as onboarding are not available; see Reserved identifiers.
slot_duration integer Minutes. The length of every slot and every booked appointment of this type.
color string The type's colour as #RRGGBB, e.g. #22C55E.
bookable boolean Whether the type is offered on the online booking page.
description string, nullable A description of the type.
mailer_instructions string, nullable Text added to the appointment confirmation email.
requires_consent boolean Whether the consent declaration has to be read and accepted before an appointment of this type is booked in the app.
send_questionnaire boolean Whether the patient receives the type's questionnaire, if it has an active one, when an appointment of this type is booked.
appointment_resource object, nullable The place where it takes place (id, external_id, name, address). null is an online video appointment.
reserved boolean A system type. It cannot be deleted.
created_at, updated_at string (date-time) Timestamps.

List and show types

GET /api/v1/availability_types and GET /api/v1/availability_types/{id}

The list accepts organization_id/organization_external_id (instance tokens), external_id, updated_since, page and per_page. Types are listed by display_name.

curl "https://acme.meetone.io/api/v1/availability_types?per_page=100" \
  -H "Authorization: Bearer $TOKEN"

Create a type

POST /api/v1/availability_types

Field Type Required Description
display_name string Yes The name of the type.
slot_duration integer Yes Minutes, 1 or more.
identifier string No Derived from display_name if omitted; made unique with a numeric suffix if needed. A reserved identifier returns 422 (code reserved, attribute identifier).
external_id string No Your key for the type.
color string No #RRGGBB. Defaults to the next colour of the palette that the organization has not used yet.
bookable boolean No Defaults to true.
description, mailer_instructions string No See the object above.
requires_consent, send_questionnaire boolean No Both default to false.
appointment_resource_id or appointment_resource_external_id string No Makes the type an in-person type at this resource. Omit it, or send null, for a video type. 
curl -X POST "https://acme.meetone.io/api/v1/availability_types" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "First visit",
    "external_id": "first-visit",
    "slot_duration": 30,
    "mailer_instructions": "Please bring your insurance card."
  }'

A successful request returns 201 Created:

{
  "data": {
    "id": "5d9a2f77-c3e1-4b08-8a64-7e1f0c92d3b6",
    "external_id": "first-visit",
    "display_name": "First visit",
    "identifier": "first-visit",
    "slot_duration": 30,
    "color": "#22C55E",
    "bookable": true,
    "description": null,
    "mailer_instructions": "Please bring your insurance card.",
    "requires_consent": false,
    "send_questionnaire": false,
    "appointment_resource": null,
    "reserved": false,
    "created_at": "2026-10-08T10:00:00+02:00",
    "updated_at": "2026-10-08T10:00:00+02:00"
  }
}

Validation errors return 422 in the standard error format, for example greater_than on slot_duration or taken on external_id. A resource reference that does not exist in the organization returns 404, and assigning one without in-person appointments returns 403 (feature_disabled).

Update a type

PATCH /api/v1/availability_types/{id}

Send only the fields you want to change. To turn an in-person type into a video type, send "appointment_resource_id": null. The identifier of a reserved type cannot change (422, code immutable).

curl -X PATCH "https://acme.meetone.io/api/v1/availability_types/5d9a2f77-c3e1-4b08-8a64-7e1f0c92d3b6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "slot_duration": 45, "bookable": false }'

Changing slot_duration changes the slot grid for all future free slots. Appointments that are already booked keep the length they were booked with.

Reserved identifiers

MeetOne reserves some identifiers for system types, onboarding among them. An organization's availability type cannot use one:

  • Sending a reserved identifier returns 422 with the code reserved and the attribute identifier.
  • A display_name that would turn into a reserved identifier gets a suffix instead: "Onboarding" becomes onboarding-2.
  • The reserved system types themselves cannot be deleted (409, code reserved) and their identifier cannot change.

Delete a type

DELETE /api/v1/availability_types/{id} returns 204 No Content.

A type can only be deleted when nothing ahead depends on it. Otherwise the response is 409 Conflict:

Code Why
in_use Appointments that are not cancelled, or availabilities, still lie ahead for this type. Cancel or delete them first. Questionnaires that use the type also block deletion (in_use).
reserved The type is a system type.

Appointments in the past keep their data when their type is deleted; their availability_type becomes null.

Questions? Contact us at support@meetone.io.