Appointments API & Webhooks

Send appointments from your own calendar

A source can send appointments that are already booked, from GoHighLevel or any other calendar tool, to the same ingest address it uses for leads. On an appointments campaign, a post with appointment_time is a booked appointment: it is delivered right away and marked booked.

curl -X POST https://app.leaddistro.ai/api/v1/ingest \
  -H "x-api-key: YOUR_SOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flo_campaign_id": "YOUR_CAMPAIGN_ID",
    "flo_supplier_id": "YOUR_SOURCE_ID",
    "first_name": "Maria",
    "last_name": "Garcia",
    "phone": "5551234567",
    "appointment_time": "2026-10-21T15:30:00-05:00",
    "appointment_timezone": "America/Chicago"
  }'

To update it later, the same source posts the person's phone or email with appointment_status set to showed, no_show or canceled. Lead Distro AI finds the appointment that source sent and updates it, replying 200 with "updated": true. No new lead is made and the source is not charged again. Sending the same booking twice replies with the first appointment. Step-by-step for GoHighLevel: Send GoHighLevel Appointments to Lead Distro AI.

Post an appointment status from a CRM

The buyer outcome webhook accepts an appointment status alongside everything else it already handles. The buyer authenticates with their own secret, so they can only touch their own leads.

curl -X POST https://www.leaddistro.ai/api/webhooks/buyer-outcome \
  -H "X-Buyer-Secret: BUYER_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "LEAD_UUID",
    "appointment_status": "showed"
  }'

Booking and attendance in one flow

A typical integration sends two calls. The first when the appointment is created, the second when the buyer knows whether it happened.

// 1. When the appointment is booked
{
  "lead_id": "LEAD_UUID",
  "appointment_status": "booked",
  "appointment_at": "2026-09-11T15:00:00-07:00"
}

// 2. After the appointment time passes
{
  "lead_id": "LEAD_UUID",
  "appointment_status": "showed"
}

Sending the same status twice is safe. A repeat of a status the lead already has is recognized and does not bill twice.

Reporting the review

If the buyer pays for appointments that showed up and qualified, a third call reports the review. It is a separate field, not another appointment status, so posting "appointment_status": "qualified" returns 400.

// 3. After someone reviews the appointment
{
  "lead_id": "LEAD_UUID",
  "appointment_qualified": "qualified"
}

The two marks can arrive in either order. If the review lands before the show is reported, nothing bills until the show arrives, and then it bills once. Send unqualified when the review decides the appointment was not worth paying for. If it had already been billed, the charge is reversed.

Call outcomes

If the booking comes out of a phone call rather than a calendar, post it as a call outcome instead. This needs no appointment feature enabled.

curl -X POST https://www.leaddistro.ai/api/v1/lead-update \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "LEAD_UUID",
    "call_outcome": "appointment_set"
  }'

Outcome stages

Both endpoints also accept a stage field carrying a custom outcome stage key, which is how you record an appointment without the billing add-on.

{
  "lead_id": "LEAD_UUID",
  "stage": "meeting_booked"
}

Error codes