Skip to content

Instantly share code, notes, and snippets.

@hmseeb

hmseeb/retell-integration-guide.md

Last active March 26, 2026 17:47
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save hmseeb/52ec73990d0fc4da32b7bdc19a50dcd2 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save hmseeb/52ec73990d0fc4da32b7bdc19a50dcd2 to your computer and use it in GitHub Desktop.
Download ZIP
PPL Lead Mgmt v4.0 - Retell Integration Guide
Raw
retell-integration-guide.md

PPL Lead Mgmt v4.0 - Retell Integration Guide

Retell Integration Guide - PPL Lead Management v4.0

Overview

When a lead calls in via Retell AI, the system identifies the lead, checks broker availability, attempts transfer, and falls back to callback scheduling if the broker is unavailable. Every call outcome is logged for reporting.

API Endpoints

1. Lead Lookup

Identify the caller and get their assigned broker's availability.

GET https://ppl-leadr-mgmt.vercel.app/api/leads/lookup?phone={{caller_phone}}

Response (200):

{
  "lead": {
    "id": "uuid",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+18325524781",
    "email": "john@example.com",
    "vertical": "MCA",
    "credit_score": 654,
    "funding_amount": 75000,
    "status": "assigned"
  },
  "broker": {
    "id": "uuid",
    "first_name": "Rich",
    "last_name": "Ciufo",
    "phone": "+16313064045",
    "email": "clearstepcapital@gmail.com",
    "availability": {
      "contact_hours": "business_hours",
      "timezone": "America/New_York",
      "weekend_pause": false
    }
  }
}

Response (404): Lead not found for this phone number.

2. Book Callback

When broker is unavailable, book a callback after asking the lead for a preferred time.

POST https://ppl-leadr-mgmt.vercel.app/api/callbacks
Content-Type: application/json

Body:

{
  "lead_id": "uuid (from lookup response)",
  "broker_id": "uuid (from lookup response)",
  "scheduled_time": "2026-03-26T15:00:00Z (ISO 8601)"
}

Response (201):

{
  "id": "uuid",
  "lead_id": "uuid",
  "broker_id": "uuid",
  "scheduled_time": "2026-03-26T15:00:00+00:00",
  "status": "pending",
  "created_at": "2026-03-25T13:26:31Z"
}

Side effect: Fires callback_created webhook to broker's CRM immediately.

3. List Callbacks

Query existing callbacks with optional filters. Useful for checking if a callback already exists for a lead.

GET https://ppl-leadr-mgmt.vercel.app/api/callbacks

Query Parameters:

Param Type Description
lead_id uuid Filter by lead
broker_id uuid Filter by broker
status string pending, completed, or cancelled
from ISO datetime Scheduled time >= this
to ISO datetime Scheduled time <= this
limit number Results per page (default 50, max 100)
offset number Skip N results (default 0)

Response (200):

{
  "data": [
    {
      "id": "uuid",
      "lead_id": "uuid",
      "broker_id": "uuid",
      "scheduled_time": "2026-03-27T10:00:00+00:00",
      "status": "pending",
      "notes": null,
      "created_at": "2026-03-25T19:06:45Z",
      "updated_at": "2026-03-25T19:06:45Z",
      "lead_name": "John Doe",
      "broker_name": "Rich Ciufo"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Example: Check if lead already has a pending callback:

GET /api/callbacks?lead_id={{lead_id}}&status=pending

4. Cancel Callback (optional)

DELETE https://ppl-leadr-mgmt.vercel.app/api/callbacks/{{callback_id}}

Response (200): Callback marked as cancelled.

Side effect: Fires callback_cancelled webhook to broker's CRM.

5. Log Call Outcome

Log every call outcome after the call ends. Required for reporting dashboard.

Multiple logs per broker-lead pair are supported. The same lead and broker can have many call logs with different outcomes. Each call creates a separate log entry, so you can track the full journey (e.g., no_answer -> callback_booked -> transferred).

POST https://ppl-leadr-mgmt.vercel.app/api/call-logs
Content-Type: application/json

Body:

{
  "lead_id": "uuid",
  "broker_id": "uuid",
  "outcome": "transferred",
  "duration": 45,
  "retell_call_id": "retell-unique-call-id"
}

Valid outcomes:

Outcome When to use
transferred Call successfully transferred to broker
callback_booked Broker unavailable, callback scheduled
no_answer No one picked up / lead hung up
voicemail Call went to voicemail

Response (201): Call log created.

Response (400): Invalid outcome value or missing required fields.

Example: A lead's call journey over multiple calls:

Call # retell_call_id Outcome What happened
1 ret_abc123 no_answer First attempt, no pickup
2 ret_def456 callback_booked Lead called back, broker busy, callback scheduled
3 ret_ghi789 transferred Callback call, successfully connected

Each of these is a separate POST /api/call-logs request. All three are tracked and counted in reporting.

Call Flow

Lead calls in
  |
  v
[1] GET /api/leads/lookup?phone={{caller_phone}}
  |
  |-- 404: Lead not found -> handle gracefully, end call
  |
  |-- 200: Lead found with broker
        |
        v
      Check broker.availability
        |
        |-- Available -> Transfer call to broker.phone
        |     |
        |     |-- Success -> [5] POST /api/call-logs (outcome: "transferred")
        |     |-- Failed  -> Fall through to callback flow
        |
        |-- Unavailable (or transfer failed)
              |
              v
            Check existing: GET /api/callbacks?lead_id={{id}}&status=pending
              |
              |-- Already has pending callback -> inform lead, end call
              |
              |-- No existing callback:
                    |
                    v
                  Retell asks: "When would you like a callback?"
                  Lead provides a time
                    |
                    v
                  [2] POST /api/callbacks (scheduled_time from lead)
                    |
                    v
                  [5] POST /api/call-logs (outcome: "callback_booked")

Availability Logic

The broker.availability object tells you when the broker accepts calls:

contact_hours Meaning
anytime Always available
business_hours 9 AM - 5 PM in broker's timezone
custom Custom window (check custom_hours_start/end)
  • timezone: Broker's timezone (e.g., America/New_York)
  • weekend_pause: If true, broker doesn't take calls on weekends

Automatic Webhook Notifications

After Retell books a callback, the system handles notifications:

Event When Webhook Type
Booking confirmed Immediately callback_created
Reminder ~15 min before scheduled time callback_reminder
Time to call At scheduled time callback_due
Cancelled On cancellation callback_cancelled

All webhooks POST to the broker's crm_webhook_url with this payload:

{
  "type": "callback_created",
  "callback_id": "uuid",
  "scheduled_time": "2026-03-26T15:00:00Z",
  "lead": {
    "id": "uuid",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+18325524781",
    "email": "john@example.com",
    "vertical": "MCA",
    "credit_score": 654,
    "funding_amount": 75000
  },
  "broker": {
    "id": "uuid",
    "first_name": "Rich",
    "last_name": "Ciufo",
    "phone": "+16313064045",
    "email": "clearstepcapital@gmail.com"
  }
}

Reporting

All call outcomes and callbacks are visible on the admin dashboard at /calls:

  • KPI cards: total calls, transferred, callbacks booked, no answer, voicemail
  • Stacked bar chart with date range filtering
  • Broker filter to scope all data
  • Upcoming callbacks table
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment