Appointments API Reference

Create and cancel appointments from external calendar tools, and query calendar syncs, booked appointments, hosts, setters, meeting URLs, and outcome log states.

Date & Timezone Handling: All timestamps in responses are UTC, formatted as ISO 8601 (2026-01-15T10:30:00.000Z). Date-range filters accept either date-only YYYY-MM-DD (which expands to UTC day boundaries) or full ISO 8601 timestamps. Note that scheduled_from and scheduled_to query filters match against schedule_time, not created_at.

Create Appointment

Add an appointment to Hermon from an external calendar tool (for example, Cal.ai via Make.com). The lead is resolved by email (created if new), the event type is resolved by name (created as a SALES_CALL if new), and all standard booking side effects run — default statuses, the Call Booked notification, and outbound webhooks — exactly as an in-app booking.

POST/api/external/appointments

No duplicate appointments. Every request must include an external_reference — the unique booking ID from your source system. Sending the same reference again returns the existing appointment (is_duplicate: true) instead of creating a second one. A new booking must use a new reference. If the same reference is sent with a different schedule_time, the request is rejected with 409 Conflict rather than silently changing the time.

Provide the lead as lead_email (find or create) or an existing lead_id; provide the event type as event_type_name (find or create) or an existing event_type_id. host_email, setter_email, and triager_email must belong to active members of your organization.

Request Body

Field	Type	Required	Description
external_reference	string	Required	Unique ID of the booking from your source system (e.g. the Cal.ai booking ID). Used to prevent duplicates: sending the same value again returns the existing appointment instead of creating a new one.
schedule_time	string (ISO 8601)	Required	Appointment start time in UTC, e.g. 2026-08-20T15:00:00Z.
lead_email	string	Required	Attendee email. Finds an existing lead in your org by email, or creates a new lead if none matches. Required unless lead_id is provided.
event_type_name	string	Required	Name of the call/event type (e.g. "Sales Call"). Matched case-insensitively; if it does not exist yet, a new event type is created with call category SALES_CALL. Required unless event_type_id is provided.
lead_id	string (UUID)	Optional	Target an existing lead directly by UUID. Use instead of lead_email.
event_type_id	string (UUID)	Optional	Target an existing event type directly by UUID. Use instead of event_type_name.
lead_first_name	string	Optional	First name used when a new lead is created. Falls back to the email prefix if omitted.
lead_last_name	string	Optional	Last name used when a new lead is created.
lead_phone	string	Optional	Attendee phone number. E.164 format preferred (e.g. +14155551234); numbers that cannot be parsed are ignored.
host_email	string	Optional	Email of the host (closer) for the call. Must be an active member of your organization.
setter_email	string	Optional	Email of the setter. Must be an active member of your organization.
triager_email	string	Optional	Email of the triager. Must be an active member of your organization.
meeting_url	string	Optional	URL of the video/meeting room for the appointment.
notes	string	Optional	Free-text note attached to the appointment.

Code Examples

curl -X POST "https://api.hermon.io/api/external/appointments" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here" \
  -d '{
    "external_reference": "cal-ai-booking-123",
    "schedule_time": "2026-08-20T15:00:00Z",
    "lead_email": "jane@example.com",
    "event_type_name": "Sales Call",
    "lead_first_name": "Jane",
    "lead_phone": "+14155551234",
    "host_email": "closer@yourorg.com",
    "meeting_url": "https://cal.ai/j/abc",
    "notes": "Booked via Cal.ai"
  }'

Response Example

A new booking returns 201 Created.

json

{
  "status": "success",
  "message": "Appointment created successfully",
  "data": {
    "id": "c76340d1-72a8-403e-b920-d6a2b526926c",
    "is_duplicate": false
  }
}

A repeated external_reference returns 200 OK with the existing appointment.

json

{
  "status": "success",
  "message": "Appointment already exists for this reference",
  "data": {
    "id": "c76340d1-72a8-403e-b920-d6a2b526926c",
    "is_duplicate": true
  }
}

Log Call Outcome

Log the outcome of a call from outside Hermon. This mirrors the Log outcome modal in the app: the outcome is recorded on the appointment, the linked lead status is updated, an optional note is attached, an optional next touchpoint is scheduled for the team member given in next_follow_up.owner_id, and the usual Slack notifications and outbound webhooks fire. Re-logging an outcome on an appointment that already has one is allowed.

PATCH/api/external/appointments/:id/outcome

Path Parameters

:idRequired. The unique appointment UUID.

Resolve the status first with GET /api/external/statuses and pass its id as status_id. status_name is a convenience fallback: it is matched case-insensitively and rejected when it is ambiguous, so prefer status_id for automations.

The status must be usable on appointments (type APPOINTMENT or BOTH) and its call_categoriesmust include the appointment's call category. Statuses with the RESCHEDULED or CANCELED role are rejected — rescheduling is not supported by this endpoint, and cancellations go through POST /api/external/appointments/cancel.

Reasons (Lost / Unqualified): when the outcome has role LOST or UNQUALIFIED and the organization has configured reasons on it, you may record one with reason_id or reason_name. Look them up via GET /api/external/statuses/:id/reasons. The reason is optional over the API (unlike the in-app form, which requires it) — but when you do send one it is validated and stored on the status-change record for reporting.

Request Body

Field	Type	Required	Description
status_id	string (UUID)	Conditional	The unique UUID of the status to log as the outcome. Required unless status_name is provided. Takes precedence when both are sent.
status_name	string	Conditional	Status name, matched case-insensitively against appointment-applicable statuses in your workspace. Required unless status_id is provided. Returns a validation error when the name is unknown or matches more than one status.
reason_id	string (UUID)	Optional	Loss/disqualification reason to record, by id. Only applies when the outcome has role LOST or UNQUALIFIED and syncs to the lead. Must be an active reason configured on that status. Takes precedence when both reason_id and reason_name are sent. Optional over the API.
reason_name	string	Optional	Reason to record, matched case-insensitively against the outcome’s active reasons. Alternative to reason_id. Returns a validation error when no active reason with that name exists on the status.
notes	string	Optional	Free-text note recorded against the lead and linked to this appointment. Maximum 10,000 characters.
next_follow_up	object	Optional	Schedules a next touchpoint on the lead for the given owner. type, datetime and owner_id are all required when this object is sent. A team member has at most one open touchpoint per lead, so if the owner already has one it is rescheduled to these values.
next_follow_up.type	string (enum)	Conditional	Follow-up type. See Touch Point Type Values.
next_follow_up.datetime	string (ISO 8601)	Conditional	When the follow-up is due, in UTC or with an explicit offset (e.g. "2026-09-12T14:00:00Z").
next_follow_up.owner_id	string	Conditional	Clerk user ID of the team member who owns the follow-up. Must be an active member of the workspace (IDs from GET /api/external/team-members), otherwise the request fails with 400.

Touch Point Type Values

Value	Description
PHONE_CALL	Phone call
WHATSAPP	WhatsApp message
EMAIL	Email
FOLLOW_UP_CALL	Follow-up call
PROPOSAL_REVIEW	Proposal review
OTHER	Anything else

Code Examples

curl -X PATCH "https://api.hermon.io/api/external/appointments/c76340d1-72a8-403e-b920-d6a2b526926c/outcome" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here" \
  -d '{
    "status_name": "Follow-up Required",
    "notes": "Budget confirmed, wants to review with partner.",
    "next_follow_up": {
      "type": "FOLLOW_UP_CALL",
      "datetime": "2026-09-12T14:00:00Z",
      "owner_id": "user_2abcCloser"
    }
  }'

Response Example

json

{
  "success": true,
  "message": "Appointment outcome updated successfully",
  "data": {
    "id": "c76340d1-72a8-403e-b920-d6a2b526926c",
    "outcome": {
      "id": "9c8b7a6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
      "name": "Follow-up Required",
      "role": "FOLLOW_UP"
    }
  }
}

Call GET /api/external/appointments/:id afterwards if you need the full updated appointment.

Error Responses

The appointment does not exist in your workspace.

json

{
  "success": false,
  "message": "Appointment not found"
}

The status name is unknown (an ambiguous name returns a similar error listing the matching status IDs).

json

{
  "success": false,
  "message": "Invalid status_name: No appointment status named \"Follow Upp\" in your workspace"
}

The status is not allowed for this appointment's call category.

json

{
  "success": false,
  "message": "Status \"Coaching Complete\" is not allowed for SALES_CALL appointments"
}

The status carries a role this endpoint does not support.

json

{
  "success": false,
  "message": "Status \"Rescheduled\" cannot be set via the API. Rescheduling an appointment is not supported by this endpoint."
}

The reason does not match an active reason on the status (same shape for an unknown reason_id).

json

{
  "success": false,
  "message": "Invalid reason_name: no active reason named \"Too pricy\" for this status in your workspace"
}

Cancel Appointment

Cancel an appointment that was added through this API. Send the same external_reference used when it was created; Hermon marks the appointment Canceled — updating the lead status, clearing the meeting URL, and firing the cancellation notification and outbound webhook, exactly like canceling in the app. An optional next touchpoint can be scheduled for the team member given in next_follow_up.owner_id, the same as Log Call Outcome.

POST/api/external/appointments/cancel

Only appointments created via this API (source MANUAL) can be canceled here — bookings synced from Calendly, iClosed, or GoHighLevel are managed by those integrations. Cancelling is idempotent: sending it again for an already-canceled appointment simply re-applies the Canceled outcome.

Request Body

Field	Type	Required	Description
external_reference	string	Required	The booking ID you sent when the appointment was created. Identifies which appointment to cancel.
notes	string	Optional	Free-text note explaining the cancellation (e.g. "Canceled by attendee").
next_follow_up	object	Optional	Schedules a next touchpoint on the lead for the given owner. type, datetime and owner_id are all required when this object is sent. A team member has at most one open touchpoint per lead, so if the owner already has one it is rescheduled to these values.
next_follow_up.type	string (enum)	Conditional	Follow-up type. See Touch Point Type Values.
next_follow_up.datetime	string (ISO 8601)	Conditional	When the follow-up is due, in UTC or with an explicit offset (e.g. "2026-09-12T14:00:00Z").
next_follow_up.owner_id	string	Conditional	Clerk user ID of the team member who owns the follow-up. Must be an active member of the workspace (IDs from GET /api/external/team-members), otherwise the request fails with 400.

Code Examples

curl -X POST "https://api.hermon.io/api/external/appointments/cancel" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here" \
  -d '{
    "external_reference": "cal-ai-booking-123",
    "notes": "Canceled by attendee",
    "next_follow_up": {
      "type": "PHONE_CALL",
      "datetime": "2026-09-12T14:00:00Z",
      "owner_id": "user_2abcCloser"
    }
  }'

Response Example

json

{
  "status": "success",
  "message": "Appointment cancelled successfully",
  "data": {
    "id": "c76340d1-72a8-403e-b920-d6a2b526926c"
  }
}

Cancel Appointment by ID

Cancel an appointment by its Hermon appointment UUID, on any source. Hermon marks the appointment Canceled — updating the lead status, clearing the meeting URL, and firing the cancellation notification and outbound webhook, exactly like canceling in the app. An optional next touchpoint can be scheduled for the team member given in next_follow_up.owner_id, the same as Log Call Outcome.

POST/api/external/appointments/:id/cancel

Unlike POST /api/external/appointments/cancel (which takes an external_reference and only cancels appointments created through this API), this route cancels an appointment on any source — including bookings synced from Calendly, iClosed, or GoHighLevel — and propagates the cancellation to that provider. An appointment that is already CANCELED is rejected with 400 rather than re-firing the cancellation.

Path Parameters

:idRequired. The unique appointment UUID.

Request Body

Field	Type	Required	Description
notes	string	Optional	Free-text note explaining the cancellation, recorded against the lead and linked to this appointment (e.g. "Lead requested to cancel"). Maximum 10,000 characters.
next_follow_up	object	Optional	Schedules a next touchpoint on the lead for the given owner. type, datetime and owner_id are all required when this object is sent. A team member has at most one open touchpoint per lead, so if the owner already has one it is rescheduled to these values.
next_follow_up.type	string (enum)	Conditional	Follow-up type. See Touch Point Type Values.
next_follow_up.datetime	string (ISO 8601)	Conditional	When the follow-up is due, in UTC or with an explicit offset (e.g. "2026-09-12T14:00:00Z").
next_follow_up.owner_id	string	Conditional	Clerk user ID of the team member who owns the follow-up. Must be an active member of the workspace (IDs from GET /api/external/team-members), otherwise the request fails with 400.

Code Examples

curl -X POST "https://api.hermon.io/api/external/appointments/c76340d1-72a8-403e-b920-d6a2b526926c/cancel" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here" \
  -d '{
    "notes": "Lead requested to cancel",
    "next_follow_up": {
      "type": "PHONE_CALL",
      "datetime": "2026-09-12T14:00:00Z",
      "owner_id": "user_2abcCloser"
    }
  }'

Response Example

json

{
  "status": "success",
  "message": "Appointment cancelled successfully",
  "data": {
    "id": "c76340d1-72a8-403e-b920-d6a2b526926c"
  }
}

Error Responses

The appointment does not exist in your workspace.

json

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

The appointment is already canceled.

json

{
  "status": "error",
  "message": "Appointment is already cancelled"
}

List Appointments

Retrieve a paginated list of appointments. Results can be filtered by call category, outcome status role, lead, assigned setter, triager, or closer (host).

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
lead_id	string (UUID)	Optional	UUID of the lead to filter appointments by. Must be a valid UUID that exists in your org.
call_category	string	Optional	Comma-separated list of call categories (e.g. SALES_CALL, COACHING_CALL, TRIAGE_CALL).
outcome_role	string	Optional	Comma-separated list of outcome status roles (e.g. NEW_LEAD, APPOINTMENT_BOOKED, NO_SHOW, RESCHEDULED, CANCELED, PARTIAL_PAYMENT, WON, UNQUALIFIED, FOLLOW_UP, LOST).
setter	string	Optional	Email address of the setter to filter by.
triager	string	Optional	Email address of the triager to filter by.
closer	string	Optional	Email address of the closer (host) to filter by.
scheduled_from	string	Optional	Lower bound for schedule_time. Accepts YYYY-MM-DD or ISO 8601.
scheduled_to	string	Optional	Upper bound for schedule_time. Accepts YYYY-MM-DD or ISO 8601.
created_from	string	Optional	Lower bound for created_at. Accepts YYYY-MM-DD or ISO 8601.
created_to	string	Optional	Upper bound for created_at. Accepts YYYY-MM-DD or ISO 8601.
updated_from	string	Optional	Lower bound for updated_at. Accepts YYYY-MM-DD or ISO 8601.
updated_to	string	Optional	Upper bound for updated_at. Accepts YYYY-MM-DD or ISO 8601.

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&triager=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

{
  "success": true,
  "message": "Appointments fetched successfully",
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "lead": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone_e164": "+14155551234",
        "phone_country": "US",
        "touch_points": [
          {
            "id": "6f1c2b9e-3d4a-4f8b-9c2e-1a7d5e3b8c40",
            "owner": {
              "id": "user_2abcCloser",
              "first_name": "Jane",
              "last_name": "Smith",
              "profile_image_url": null,
              "role": "org:sales_reps"
            },
            "owner_id": "user_2abcCloser",
            "type": "PHONE_CALL",
            "due_at": "2026-06-15T14:00:00.000Z",
            "has_time": true,
            "note": null,
            "created_at": "2026-06-10T09:00:00.000Z"
          }
        ]
      },
      "schedule_time": "2026-02-10T15:00:00.000Z",
      "host": {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ29vZ2xlL2ltZ18zOWJ3NkxJaTFFSTdlM3Z4RHFhTFViUTZVeFMifQ",
        "id": "user_456def",
        "role": "org:admin"
      },
      "setter": {
        "first_name": "Alice",
        "last_name": "Jones",
        "email": "alice@example.com",
        "profile_image_url": null,
        "id": "user_123abc",
        "role": "org:member"
      },
      "triager": null,
      "meeting_url": "https://calendly.com/jane-smith/discovery",
      "appointment_type": "Discovery Call",
      "call_category": "SALES_CALL",
      "appointment_event_type": {
        "id": "evt_abc123",
        "provider": "CALENDLY",
        "owner_name": "Jane Smith"
      },
      "outcome": {
        "id": "status_won123",
        "name": "Closed Won",
        "role": "WON",
        "description": "Deal successfully closed",
        "text_color": "#14532D",
        "bg_color": "#DCFCE7",
        "created_at": "2025-12-01T09:00:00.000Z"
      },
      "notes": {
        "note": "Strong buying intent, ready to start immediately",
        "mention_users": []
      },
      "recording_url": "https://example.com/recordings/call-abc123",
      "no_show": false,
      "source": "CALENDLY",
      "external_reference": "CALY-abc123",
      "utm_source": "facebook",
      "utm_medium": "paid_social",
      "utm_campaign": "q1-2026-coaching",
      "utm_content": "video-ad-v2",
      "utm_term": null,
      "fathom": {
        "id": "fathom_xyz789",
        "fathom_call_id": "fathom-call-abc123",
        "ai_generated_title": "Discovery Call — Strong Interest in Premium Package",
        "ai_rationale": "Lead showed high engagement and asked specific questions about onboarding",
        "ai_suggested_outcome": "WON",
        "ai_confidence_score": 0.87,
        "appointment_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "created_at": "2026-02-10T16:30:00.000Z"
      },
      "created_at": "2026-02-08T10:00:00.000Z",
      "updated_at": "2026-02-10T16:35:00.000Z",
      "custom_fields": []
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "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	Basic lead info (id, first_name, last_name, email, phone_e164, phone_country, touch_points). See Appointment Lead Object.
schedule_time	string (ISO 8601)	UTC timestamp of the scheduled appointment.
host	object \| null	The closer/host conducting the call (first_name, last_name, email, profile_image_url, id, role).
setter	object \| null	Setter who booked the appointment (first_name, last_name, email, profile_image_url, id, role).
triager	object \| null	Triager assigned to the appointment (first_name, last_name, email, profile_image_url, id, role).
meeting_url	string \| null	Video/phone meeting URL.
appointment_type	string \| null	Name of the event type (e.g. "Discovery Call").
call_category	string (enum)	Category of the call (SALES_CALL, COACHING_CALL, TRIAGE_CALL).
appointment_event_type	object	Event type metadata (id, provider, owner_name).
outcome	object \| null	Outcome status (id, name, role, description, text_color, bg_color, created_at).
notes	object \| null	Latest note on the appointment (note, mention_users) [List API Only].
recording_url	string \| null	Call recording URL.
no_show	boolean	Whether the lead was a no-show.
source	string (enum)	Booking source (CALENDLY, ICLOSED, GOHIGHLEVEL, MANUAL).
external_reference	string \| null	Reference ID from the booking provider.
utm_source	string \| null	UTM source parameter [List API Only].
utm_medium	string \| null	UTM medium parameter [List API Only].
utm_campaign	string \| null	UTM campaign parameter [List API Only].
utm_content	string \| null	UTM content parameter [List API Only].
utm_term	string \| null	UTM term parameter [List API Only].
fathom	object \| null	Fathom AI call analysis (id, fathom_call_id, ai_generated_title, ai_rationale, ai_suggested_outcome, ai_confidence_score, appointment_id, created_at).
created_at	string (ISO 8601)	UTC timestamp when created.
updated_at	string (ISO 8601)	UTC timestamp when last updated.
custom_fields	array	Custom field values.
first_source	object	Lead's first attribution source [Details API Only].
last_source	object	Lead's last attribution source [Details API Only].
opt_ins	array	Up to 3 most recent opt-in submissions from the lead [Details API Only].

The detail endpoint does not include notes or UTM fields (utm_source, utm_medium, etc.) as those are list-only fields. The details response includes first_source, last_source, opt_ins (up to 3 most recent), and custom_fields instead.

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

{
  "success": true,
  "message": "Appointment fetched successfully",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "lead": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_e164": "+14155551234",
      "phone_country": "US",
      "touch_points": [
        {
          "id": "6f1c2b9e-3d4a-4f8b-9c2e-1a7d5e3b8c40",
          "owner": {
            "id": "user_2abcCloser",
            "first_name": "Jane",
            "last_name": "Smith",
            "profile_image_url": null,
            "role": "org:sales_reps"
          },
          "owner_id": "user_2abcCloser",
          "type": "PHONE_CALL",
          "due_at": "2026-06-15T14:00:00.000Z",
          "has_time": true,
          "note": null,
          "created_at": "2026-06-10T09:00:00.000Z"
        }
      ]
    },
    "schedule_time": "2026-02-10T15:00:00.000Z",
    "host": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ29vZ2xlL2ltZ18zOWJ3NkxJaTFFSTdlM3Z4RHFhTFViUTZVeFMifQ",
      "id": "user_456def",
      "role": "org:admin"
    },
    "setter": null,
    "triager": null,
    "meeting_url": "https://calendly.com/jane-smith/discovery",
    "appointment_type": "Discovery Call",
    "call_category": "SALES_CALL",
    "appointment_event_type": {
      "id": "evt_abc123",
      "provider": "CALENDLY",
      "owner_name": "Jane Smith"
    },
    "outcome": {
      "id": "status_won123",
      "name": "Closed Won",
      "role": "WON",
      "description": "Deal successfully closed",
      "text_color": "#14532D",
      "bg_color": "#DCFCE7",
      "created_at": "2025-12-01T09:00:00.000Z"
    },
    "recording_url": "https://example.com/recordings/call-abc123",
    "no_show": false,
    "source": "CALENDLY",
    "external_reference": "CALY-abc123",
    "fathom": null,
    "first_source": {
      "id": "src_abc123",
      "name": "Facebook Ad Campaign"
    },
    "last_source": {
      "id": "src_def456",
      "name": "Referral"
    },
    "custom_fields": [],
    "opt_ins": [
      {
        "id": "optin_xyz789",
        "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "source": "TYPEFORM",
        "provider_form_id": "form_abc123",
        "provider_form_name": "Coaching Application",
        "external_reference": "TYPEFORM-abc123",
        "created_at": "2026-01-15T09:00:00.000Z"
      }
    ],
    "created_at": "2026-02-08T10:00:00.000Z",
    "updated_at": "2026-02-10T16:35:00.000Z"
  }
}

Values Reference

Call Category Values

Value	Description
SALES_CALL	Sales discovery or closing call
COACHING_CALL	Coaching session
TRIAGE_CALL	Initial qualification/triage call

Status Role Values

Value	Description
NEW_LEAD	New/unqualified lead
APPOINTMENT_BOOKED	Appointment scheduled
NO_SHOW	Lead did not attend
RESCHEDULED	Appointment rescheduled
CANCELED	Appointment canceled
PARTIAL_PAYMENT	Partial payment received
WON	Deal won/closed
UNQUALIFIED	Lead disqualified
FOLLOW_UP	Requires follow-up
LOST	Deal lost

Appointment Source Values

Value	Description
CALENDLY	Booked via Calendly
ICLOSED	Booked via iClosed
GOHIGHLEVEL	Booked via GoHighLevel
MANUAL	Manually created

Nested Objects Reference

Appointment Lead Object

Field	Type	Description
id	string (UUID)	Lead ID
first_name	string	First name
last_name	string	Last name
email	string	Email address
phone_e164	string	Phone in E.164 format
phone_country	string	ISO 3166-1 alpha-2 country code
touch_points	array	Open next touchpoints on the lead (every owner), earliest due first. Same shape as the Touch Point Object on the Leads API.

User Object

Field	Type	Description
first_name	string	First name
last_name	string	Last name
email	string	Email address
profile_image_url	string	Profile image URL (null if none)
id	string	Clerk user ID
role	string	Organization role

Event Type Object

Field	Type	Description
id	string	Event type ID (null when no event type is set)
provider	string	Booking provider (e.g. CALENDLY, ICLOSED, GOHIGHLEVEL)
owner_name	string	Owner name in the booking provider

Outcome Object

Field	Type	Description
id	string	Status ID
name	string	Status display name
role	string (enum)	Status role
description	string	Status description
text_color	string	Hex color code for text
bg_color	string	Hex color code for background
created_at	string (ISO 8601)	When this status was created

Note Object

Field	Type	Description
note	string	Note text
mention_users	array	Users @mentioned in the note (Clerk user objects)

Fathom Object

Field	Type	Description
id	string	Record ID
fathom_call_id	string	Fathom platform call ID
ai_generated_title	string	AI-generated call title
ai_rationale	string	AI reasoning for the suggested outcome
ai_suggested_outcome	string	Suggested outcome status name
ai_confidence_score	number	Confidence score (0–1)
appointment_id	string	Parent appointment ID
created_at	string (ISO 8601)	When the record was created

Error Responses

400Missing or invalid field (Create)

json

{
  "status": "error",
  "message": "external_reference is required"
}

401Missing or invalid API key

json

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

404Resource not found

json

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

404No appointment for external_reference (Cancel)

json

{
  "status": "error",
  "message": "No appointment found for external_reference \"cal-ai-booking-123\""
}

409external_reference reused with a different time (Create)

json

{
  "status": "error",
  "message": "external_reference \"cal-ai-booking-123\" already maps to an appointment at a different time. Send a new external_reference for a new booking."
}

429Rate limit exceeded

json

{
  "status": "error",
  "message": "Rate limit exceeded for this organization. Retry after the number of seconds in the Retry-After header."
}