Appointments API Reference

Query calendar syncs, booked appointments, hosts, setters, meeting URLs, and outcome log states.

List Appointments

Retrieve a paginated list of appointments. Results can be filtered by call category, outcome, lead, and assigned setter, closer, or triager.

GET/api/external/appointments

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number for pagination. Default: 1
limit	integer	Optional	Number of items per page. Default: 10, Max: 100
call_category	string	Optional	Filter by category (e.g. SALES_CALL, COACHING_CALL, TRIAGE_CALL).
outcome_role	string	Optional	Filter by outcome role (e.g. NEW_LEAD, APPOINTMENT_BOOKED, NO_SHOW, RESCHEDULED, CANCELED, PARTIAL_PAYMENT, WON, UNQUALIFIED, FOLLOW_UP, LOST).
setter	string	Optional	Filter by assigned setter email.
closer	string	Optional	Filter by assigned closer email.
triage	string	Optional	Filter by assigned triager email.
lead_id	string (UUID)	Optional	Filter by associated lead UUID.

Code Examples

curl -X GET "https://api.hermon.io/api/external/appointments?page=1&limit=10&call_category=COACHING_CALL&outcome_role=APPOINTMENT_BOOKED&setter=sales-setter@mailinator.com&closer=hermon@mailinator.com&triage=triager@mailinator.com&lead_id=e799c30f-9da7-4fd7-9552-83b96a9bfac2" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "status": "success",
  "message": "Appointments fetched successfully",
  "data": [
    {
      "id": "c76340d1-72a8-403e-b920-d6a2b526926c",
      "lead": {
        "id": "e799c30f-9da7-4fd7-9552-83b96a9bfac2",
        "first_name": "Chris",
        "last_name": null,
        "email": "cpulf1@gmail.com",
        "phone_e164": "+61492817298",
        "phone_country": "AU",
        "next_touch_point_at": null,
        "next_touch_point_type": null
      },
      "schedule_time": "2026-05-23T11:00:00.000Z",
      "host": null,
      "setter": null,
      "triager": null,
      "meeting_url": null,
      "appointment_type": "Millionaire Commerce - Qualification Call - PS",
      "call_category": "SALES_CALL",
      "appointment_event_type": {
        "id": "a7a2117c-7e2b-4d9d-b18a-0ea24afe3371",
        "provider": "CALENDLY",
        "owner_name": "M.C. Elite - Succes Team"
      },
      "outcome": {
        "id": "bac5eb24-e69f-410e-ad94-0185decad74a",
        "name": "Canceled",
        "role": "CANCELED",
        "description": "Lead cancelled, no reschedule",
        "text_color": "#E11D48",
        "bg_color": "#FFF1F2"
      },
      "notes": "Canceled via Calendly",
      "recording_url": null,
      "no_show": false,
      "source": "CALENDLY",
      "external_reference": "https://api.calendly.com/scheduled_events/8970bc3c-91c1-476d-8dbb-f3ae825b2537/invitees/f37e53c6-f293-4e5f-82c9-565e2ccd20a6",
      "fathom": null,
      "created_at": "2026-05-22T11:32:04.386Z",
      "updated_at": "2026-05-23T10:31:16.573Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Get Appointment Details

Fetch detailed information for a single appointment by its unique UUID.

GET/api/external/appointments/:id

Path Parameters

:idRequired. The unique appointment UUID.

Appointment Object Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the appointment.
lead	object	Associated lead summary details (id, first_name, last_name, email, phone_e164, phone_country, next_touch_point_at, next_touch_point_type).
schedule_time	string	ISO 8601 timestamp when the appointment is scheduled.
host	string \| null	Email of the assigned host/assignee.
setter	string \| null	Email of the assigned setter.
triager	string \| null	Email of the assigned triager.
meeting_url	string \| null	Video conference join link.
appointment_type	string	Type/name of the scheduled appointment.
call_category	string	Billing or call category (e.g. SALES_CALL, COACHING_CALL).
appointment_event_type	object	Metadata for scheduling event (id, provider, owner_name).
outcome	object	Current outcome details (id, name, role, description, text_color, bg_color).
notes	string \| null	Text notes associated with the booking.
recording_url	string \| null	Video call recording link.
no_show	boolean	Whether the contact failed to show up.
source	string	Scheduling origin provider (e.g. CALENDLY, MANUAL).
external_reference	string \| null	Unique external provider reference link.
fathom	object \| null	Fathom call recording integration details.
created_at	string	ISO 8601 timestamp of creation.
updated_at	string	ISO 8601 timestamp of last modification.
opt_ins	array	Opt-in records generated from this booking [Details API Only].

Code Examples

curl -X GET "https://api.hermon.io/api/external/appointments/c76340d1-72a8-403e-b920-d6a2b526926c" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "status": "success",
  "message": "Appointment fetched successfully",
  "data": {
    "id": "c76340d1-72a8-403e-b920-d6a2b526926c",
    "lead": {
      "id": "e799c30f-9da7-4fd7-9552-83b96a9bfac2",
      "first_name": "Chris",
      "last_name": null,
      "email": "cpulf1@gmail.com",
      "phone_e164": "+61492817298",
      "phone_country": "AU",
      "next_touch_point_at": null,
      "next_touch_point_type": null
    },
    "schedule_time": "2026-05-23T11:00:00.000Z",
    "host": null,
    "setter": null,
    "triager": null,
    "meeting_url": null,
    "appointment_type": "Millionaire Commerce - Qualification Call - PS",
    "call_category": "SALES_CALL",
    "appointment_event_type": {
      "id": "a7a2117c-7e2b-4d9d-b18a-0ea24afe3371",
      "provider": "CALENDLY",
      "owner_name": "M.C. Elite - Succes Team"
    },
    "outcome": {
      "id": "bac5eb24-e69f-410e-ad94-0185decad74a",
      "name": "Canceled",
      "role": "CANCELED",
      "description": "Lead cancelled, no reschedule",
      "text_color": "#E11D48",
      "bg_color": "#FFF1F2"
    },
    "notes": "Canceled via Calendly",
    "recording_url": null,
    "no_show": false,
    "source": "CALENDLY",
    "external_reference": "https://api.calendly.com/scheduled_events/8970bc3c-91c1-476d-8dbb-f3ae825b2537/invitees/f37e53c6-f293-4e5f-82c9-565e2ccd20a6",
    "fathom": null,
    "created_at": "2026-05-22T11:32:04.386Z",
    "updated_at": "2026-05-23T10:31:16.573Z",
    "opt_ins": [
      {
        "id": "ec610936-9757-4199-b85c-ae0031206108",
        "lead_id": "e799c30f-9da7-4fd7-9552-83b96a9bfac2",
        "source": "CALENDLY",
        "provider_form_id": null,
        "provider_form_name": "Millionaire Commerce - Qualification Call - PS",
        "external_reference": "https://api.calendly.com/scheduled_events/8970bc3c-91c1-476d-8dbb-f3ae825b2537/invitees/f37e53c6-f293-4e5f-82c9-565e2ccd20a6",
        "created_at": "2026-05-22T11:32:04.443Z"
      }
    ]
  }
}

Error Responses

401Missing or invalid API key

json

{
  "status": "error",
  "message": "Invalid or revoked API key"
}

404Resource not found

json

{
  "status": "error",
  "message": "Resource not found"
}

429Rate limit exceeded

json

{
  "status": "error",
  "message": "Too many requests"
}