# Availability types endpoints

> Reference for creating, reading, updating and deleting availability types: the kinds of appointment an organization offers, with slot length, colour, place and booking options.

Source: https://help.meetone.io/developers/scheduling-api/availability-types-endpoints
Last updated: 2026-10-08

---

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](https://help.meetone.io/developers/scheduling-api/overview#feature-requirements).
- **In-person appointments** must be enabled to link a type to an [appointment resource](https://help.meetone.io/developers/scheduling-api/appointment-resources-endpoints). 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](https://help.meetone.io/developers/scheduling-api/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](https://help.meetone.io/developers/scheduling-api/availability-types-endpoints#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`.

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

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

```json
{
  "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](https://help.meetone.io/developers/getting-started/errors-and-pagination), 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`).

```bash
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 }'
```

> **Note**
>
> Changing `slot_duration` changes the slot grid for all future [free slots](https://help.meetone.io/developers/scheduling-api/availability-slots-and-booking). 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`.

## Related

- [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)
- [Scheduling API overview](https://help.meetone.io/developers/scheduling-api/overview)

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