Appointments API & Webhooks

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