Developer API

Build On Your Scheduling

A Simple, Token-Authenticated REST API To Read Event Types, Check Availability, And Create Or Cancel Bookings. Free On Every Plan.

Get Started Free Read The Docs

Getting Started

The appntmnts REST API is organized around resources you already manage in your account. All requests are made over HTTPS, all responses are JSON, and every request is scoped to your account by your API key.

Base URL

https://appntmnts.io/api/v1

Token Auth

Bearer or X-Api-Key header

120 req / min

Per key rate limit

JSON Only

Requests & responses

Authentication

Create a free account, then generate a key from Developers → API Keys in your portal. Keys look like ak_… and are shown only once - store yours somewhere safe. Send it on every request as either a Bearer token or an X-Api-Key header. 

# Option 1 - Authorization header (recommended)
Authorization: Bearer ak_your_key_here

# Option 2 - X-Api-Key header
X-Api-Key: ak_your_key_here

Errors & Rate Limits

Errors return the matching HTTP status with a JSON body: { "error": "message" }. Requests are limited to 120 per minute per key; exceeding it returns 429.

StatusMeaning
200 / 201 Success. 201 is returned when a booking is created.
401 Missing or invalid API key.
403 The account for this key is not active.
404 The requested resource does not exist or is not yours.
422 Validation failed, or the slot is unavailable.
429 Rate limit exceeded - slow down.

Identity

GET /me

Identify the account the API key belongs to. Useful for a quick credential check.

Example Request

curl https://appntmnts.io/api/v1/me \
  -H "Authorization: Bearer $API_KEY"

Example Response

{
  "data": {
    "id": 3,
    "name": "Jane Doe",
    "email": "[email protected]",
    "username": "janedoe",
    "timezone": "America/Phoenix",
    "booking_url": "https://appntmnts.io/janedoe",
    "white_label": false
  }
}

Event Types

GET /event-types

List every event type on your account.

Parameters

Name Type In Required Description
active_only boolean Query Optional When true, only active event types are returned.

Example Request

curl "https://appntmnts.io/api/v1/event-types?active_only=true" \
  -H "Authorization: Bearer $API_KEY"

Example Response

{
  "data": [
    {
      "id": 12,
      "name": "30 Minute Meeting",
      "slug": "30min",
      "kind": "one_on_one",
      "description": "A quick intro call.",
      "duration_minutes": 30,
      "location": "Video (Built-In Room)",
      "price": null,
      "requires_payment": false,
      "is_active": true,
      "booking_url": "https://appntmnts.io/janedoe/30min"
    }
  ]
}
GET /event-types/{idOrSlug}

Fetch a single event type by its numeric id or its slug.

Parameters

Name Type In Required Description
idOrSlug string Path Required The event type id (e.g. 12) or slug (e.g. 30min).

Example Request

curl https://appntmnts.io/api/v1/event-types/30min \
  -H "Authorization: Bearer $API_KEY"

Example Response

{
  "data":   {
    "id": 12,
    "name": "30 Minute Meeting",
    "slug": "30min",
    "kind": "one_on_one",
    "description": "A quick intro call.",
    "duration_minutes": 30,
    "location": "Video (Built-In Room)",
    "price": null,
    "requires_payment": false,
    "is_active": true,
    "booking_url": "https://appntmnts.io/janedoe/30min"
  }
}

Availability

GET /event-types/{idOrSlug}/slots

Open start times for a single date, honouring the event type's schedule, buffers, and existing bookings.

Parameters

Name Type In Required Description
idOrSlug string Path Required Event type id or slug.
date date (YYYY-MM-DD) Query Required The day to check. Must be today or later.

Example Request

curl "https://appntmnts.io/api/v1/event-types/30min/slots?date=2026-07-24" \
  -H "Authorization: Bearer $API_KEY"

Example Response

{
  "data": {
    "event_type": "30min",
    "date": "2026-07-24",
    "slots": [
      { "start": "09:00", "end": "09:30" },
      { "start": "09:30", "end": "10:00" },
      { "start": "14:00", "end": "14:30" }
    ]
  }
}
GET /availability

Open start times across a small date range (up to 31 days). Days with no availability are omitted.

Parameters

Name Type In Required Description
event_type string Query Required Event type id or slug.
from date (YYYY-MM-DD) Query Optional First day of the range. Defaults to today.
days integer (1-31) Query Optional How many days to scan. Defaults to 7.

Example Request

curl "https://appntmnts.io/api/v1/availability?event_type=30min&from=2026-07-24&days=5" \
  -H "Authorization: Bearer $API_KEY"

Example Response

{
  "data": {
    "event_type": "30min",
    "availability": {
      "2026-07-24": ["09:00", "09:30", "14:00"],
      "2026-07-25": ["10:00", "10:30"]
    }
  }
}

Bookings

GET /bookings

List your bookings, most recent first. Paginated.

Parameters

Name Type In Required Description
status string Query Optional One of: pending, confirmed, cancelled, completed, no_show.
from date Query Optional Only bookings on or after this date.
to date Query Optional Only bookings on or before this date.
event_type string Query Optional Filter to one event type (id or slug).
per_page integer (1-100) Query Optional Results per page. Defaults to 25.

Example Request

curl "https://appntmnts.io/api/v1/bookings?status=confirmed&per_page=10" \
  -H "Authorization: Bearer $API_KEY"

Example Response

{
  "data": [
    {
      "id": 481,
      "reference": "#00481",
      "status": "confirmed",
      "payment_status": "unpaid",
      "event_type": { "id": 12, "name": "30 Minute Meeting", "slug": "30min" },
      "customer": { "name": "Sam Rivera", "email": "[email protected]", "phone": "+1 555 0100" },
      "scheduled_date": "2026-07-24",
      "scheduled_time_start": "14:00",
      "scheduled_time_end": "14:30",
      "meeting_url": "https://meet.example.com/abc-xyz",
      "notes": "Discuss onboarding.",
      "created_at": "2026-07-18T09:12:04+00:00",
      "updated_at": "2026-07-18T09:12:04+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 10,
    "total": 48
  }
}
POST /bookings

Create a booking against one of your event types. The slot is validated for availability; returns 201 on success.

Parameters

Name Type In Required Description
event_type string Body Required Event type id or slug to book.
customer_name string Body Required The attendee name.
customer_email email Body Required The attendee email.
customer_phone string Body Optional Optional attendee phone.
scheduled_date date (YYYY-MM-DD) Body Required Booking day, today or later.
scheduled_time_start string (HH:MM) Body Required Start time, must match an open slot.
notes string Body Optional Optional note (max 1000 chars).

Example Request

curl -X POST https://appntmnts.io/api/v1/bookings \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "30min",
    "customer_name": "Sam Rivera",
    "customer_email": "[email protected]",
    "scheduled_date": "2026-07-24",
    "scheduled_time_start": "14:00"
  }'

Example Response

{
  "data":   {
    "id": 481,
    "reference": "#00481",
    "status": "confirmed",
    "payment_status": "unpaid",
    "event_type": { "id": 12, "name": "30 Minute Meeting", "slug": "30min" },
    "customer": { "name": "Sam Rivera", "email": "[email protected]", "phone": "+1 555 0100" },
    "scheduled_date": "2026-07-24",
    "scheduled_time_start": "14:00",
    "scheduled_time_end": "14:30",
    "meeting_url": "https://meet.example.com/abc-xyz",
    "notes": "Discuss onboarding.",
    "created_at": "2026-07-18T09:12:04+00:00",
    "updated_at": "2026-07-18T09:12:04+00:00"
  }
}
GET /bookings/{id}

Retrieve a single booking you own.

Parameters

Name Type In Required Description
id integer Path Required The booking id.

Example Request

curl https://appntmnts.io/api/v1/bookings/481 \
  -H "Authorization: Bearer $API_KEY"

Example Response

{
  "data":   {
    "id": 481,
    "reference": "#00481",
    "status": "confirmed",
    "payment_status": "unpaid",
    "event_type": { "id": 12, "name": "30 Minute Meeting", "slug": "30min" },
    "customer": { "name": "Sam Rivera", "email": "[email protected]", "phone": "+1 555 0100" },
    "scheduled_date": "2026-07-24",
    "scheduled_time_start": "14:00",
    "scheduled_time_end": "14:30",
    "meeting_url": "https://meet.example.com/abc-xyz",
    "notes": "Discuss onboarding.",
    "created_at": "2026-07-18T09:12:04+00:00",
    "updated_at": "2026-07-18T09:12:04+00:00"
  }
}
POST /bookings/{id}/cancel

Cancel a pending or confirmed booking. Triggers your normal cancellation emails and workflows.

Parameters

Name Type In Required Description
id integer Path Required The booking id.
reason string Body Optional Optional cancellation reason (max 500 chars).

Example Request

curl -X POST https://appntmnts.io/api/v1/bookings/481/cancel \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer requested reschedule" }'

Example Response

{
  "data": { "id": 481, "status": "cancelled", "...": "..." }
}

Ready To Build?

Create a free account, grab a key, and make your first call in minutes.

Get Started Free