Leads API Reference

Fetch leads and query histories for contacts matching Hermon data records.

List Leads

Retrieve a paginated list of leads. Results can be filtered by source, status role, and assigned setter, closer, or triager.

GET/api/external/leads

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
source	string	Optional	Filter by lead source category (e.g. LANDING_PAGE, CALENDLY, MANUAL, TYPEFORM, WEBINAR, NEWSLETTER,OTHER).
status_role	string	Optional	Filter by status 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.

Code Examples

curl -X GET "https://api.hermon.io/api/external/leads?page=1&limit=10&source=LANDING_PAGE&status_role=NEW_LEAD&setter=sales-setter@mailinator.com&closer=hermon@mailinator.com&triage=triager@mailinator.com" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "status": "success",
  "message": "Leads fetched successfully",
  "data": [
    {
      "id": "896e4c72-e390-4baf-906f-395992266222",
      "first_name": "Abiodun",
      "last_name": null,
      "email": "jesufadeju@gmail.com",
      "phone_e164": "+491786614349",
      "phone_country": "DE",
      "source": "CALENDLY",
      "assigned_setter": null,
      "assigned_closer": null,
      "assigned_triager": null,
      "next_touch_point_date": null,
      "next_touch_point_type": null,
      "first_source": {
        "id": null,
        "name": null
      },
      "last_source": {
        "id": null,
        "name": null
      },
      "status": {
        "id": "4bb2ae65-8ab1-4695-b896-190711a07cd0",
        "name": "Call Booked",
        "role": "APPOINTMENT_BOOKED",
        "description": "Appointment scheduled",
        "text_color": "#ea34b0",
        "bg_color": "#fde8f7"
      },
      "latest_note": {
        "id": "b2d6229e-363f-4cf7-9bce-56e624174a74",
        "note": "Scheduled via Calendly",
        "appointment_id": "82e00a98-1f3e-4bfa-9d40-d67dda48cb58",
        "created_by": null,
        "created_at": "2026-05-26T08:17:38.409Z"
      },
      "created_at": "2026-05-26T08:17:38.326Z",
      "updated_at": "2026-05-26T08:17:38.356Z"
    },
    {
      "id": "3411df0b-8ca1-4fd3-82be-3738b2074d7b",
      "first_name": "Adrelon",
      "last_name": null,
      "email": "allaadrelon1994@gmail.com",
      "phone_e164": "+447876839010",
      "phone_country": "GB",
      "source": "CALENDLY",
      "assigned_setter": null,
      "assigned_closer": null,
      "assigned_triager": null,
      "next_touch_point_date": null,
      "next_touch_point_type": null,
      "first_source": {
        "id": null,
        "name": null
      },
      "last_source": {
        "id": null,
        "name": null
      },
      "status": {
        "id": "bac5eb24-e69f-410e-ad94-0185decad74a",
        "name": "Canceled",
        "role": "CANCELED",
        "description": "Lead cancelled, no reschedule",
        "text_color": "#E11D48",
        "bg_color": "#FFF1F2"
      },
      "latest_note": {
        "id": "1e7f8911-7450-455a-a987-080f62ca5559",
        "note": "Canceled via Calendly",
        "appointment_id": "7e4319bb-9e52-4792-9217-9485e75aef78",
        "created_by": null,
        "created_at": "2026-05-26T07:45:10.180Z"
      },
      "created_at": "2026-05-26T07:18:50.725Z",
      "updated_at": "2026-05-26T07:45:10.153Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2362,
    "totalPages": 237,
    "hasNext": true,
    "hasPrev": false
  }
}

Get Lead Details

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

GET/api/external/leads/:id

Path Parameters

:idRequired. The unique lead UUID.

Lead Object Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the lead.
first_name	string	Lead's first name.
last_name	string \| null	Lead's last name.
email	string	Lead's email address.
phone_e164	string \| null	Phone number in E.164 format.
phone_country	string \| null	ISO country code (e.g. DE, US).
source	string	Acquisition source category (e.g. LANDING_PAGE, CALENDLY, MANUAL, TYPEFORM, WEBINAR, NEWSLETTER,OTHER).
assigned_setter	string \| null	Email of the assigned setter.
assigned_closer	string \| null	Email of the assigned closer.
assigned_triager	string \| null	Email of the assigned triager.
next_touch_point_date	string \| null	ISO 8601 timestamp of the next planned contact.
next_touch_point_type	string \| null	Type of the next contact (e.g. WHATSAPP, EMAIL).
first_source	object	Initial lead source details (id, name).
last_source	object	Latest lead source details (id, name).
status	object	Current status details (id, name, role, description, text_color, bg_color).
latest_note	object \| null	Latest activity log note (id, note, appointment_id, created_by, created_at).
created_at	string	ISO 8601 timestamp of lead creation.
updated_at	string	ISO 8601 timestamp of last modification.
billing_details	object \| null	Billing metadata (business_name, address, zipcode, province, country, vat_number) [Details API Only].
ai_source_summary	string \| null	AI-generated lead journey intent summary [Details API Only].
counts	object	Aggregate metrics counts (notes, appointments, contracts, payments, opt_ins) [Details API Only].

Code Examples

curl -X GET "https://api.hermon.io/api/external/leads/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": "Lead fetched successfully",
  "data": {
    "id": "e799c30f-9da7-4fd7-9552-83b96a9bfac2",
    "first_name": "Chris",
    "last_name": null,
    "email": "cpulf1@gmail.com",
    "phone_e164": "+61492817298",
    "phone_country": "AU",
    "source": "CALENDLY",
    "assigned_setter": null,
    "assigned_closer": null,
    "assigned_triager": null,
    "next_touch_point_date": null,
    "next_touch_point_type": null,
    "first_source": {
      "id": "90ef88c2-fa06-4703-84ec-369f7745219d",
      "name": "Other"
    },
    "last_source": {
      "id": "90ef88c2-fa06-4703-84ec-369f7745219d",
      "name": "Other"
    },
    "status": {
      "id": "bac5eb24-e69f-410e-ad94-0185decad74a",
      "name": "Canceled",
      "role": "CANCELED",
      "description": "Lead cancelled, no reschedule",
      "text_color": "#E11D48",
      "bg_color": "#FFF1F2"
    },
    "latest_note": {
      "id": "9e4f7616-b26e-4e79-a4de-380919aabd32",
      "note": "Canceled via Calendly",
      "appointment_id": "c76340d1-72a8-403e-b920-d6a2b526926c",
      "created_by": null,
      "created_at": "2026-05-23T10:31:16.626Z"
    },
    "created_at": "2026-05-22T11:32:04.329Z",
    "updated_at": "2026-05-23T10:31:16.601Z",
    "billing_details": {
      "id": "33f274cd-8128-41ae-8bc8-945307e17629",
      "business_name": "",
      "address": "nikopl;",
      "zipcode": "382350",
      "province": "Alberta",
      "country": "IN",
      "vat_number": "",
      "created_at": "2026-05-22T12:59:53.938Z",
      "updated_at": "2026-05-22T12:59:53.938Z"
    },
    "ai_source_summary": "The journey begins with an opt-in from a phone-setting source on May 22, 2026, for a qualification call related to the Millionaire Commerce program. This indicates a proactive interest in exploring coaching opportunities. The intent level is now assessed as medium, reflecting a desire for further engagement.",
    "counts": {
      "notes": 2,
      "appointments": 1,
      "contracts": 1,
      "payments": 1,
      "opt_ins": 1
    }
  }
}

List Statuses

GET/api/external/statuses

Status Object Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the status.
name	string	The label or display name of the status.
role	string	The backend status role classification (e.g. APPOINTMENT_BOOKED, CANCELED, PARTIAL_PAYMENT, NEW_LEAD).
type	string	Indicates the scope of the status (e.g. BOTH, LEAD, OPPORTUNITY).
description	string	Brief description of the status.
text_color	string	The hex color code for the status text.
bg_color	string	The hex color code for the status background.

Code Examples

curl -X GET "https://api.hermon.io/api/external/statuses" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "status": "success",
  "message": "Statuses fetched successfully",
  "data": [
    {
      "id": "4bb2ae65-8ab1-4695-b896-190711a07cd0",
      "name": "Call Booked",
      "role": "APPOINTMENT_BOOKED",
      "type": "BOTH",
      "description": "Appointment scheduled",
      "text_color": "#ea34b0",
      "bg_color": "#fde8f7"
    },
    {
      "id": "bac5eb24-e69f-410e-ad94-0185decad74a",
      "name": "Canceled",
      "role": "CANCELED",
      "type": "BOTH",
      "description": "Lead cancelled, no reschedule",
      "text_color": "#E11D48",
      "bg_color": "#FFF1F2"
    },
    {
      "id": "6e5f52e5-2b78-4e0b-8f58-226344420a37",
      "name": "Deposit",
      "role": "PARTIAL_PAYMENT",
      "type": "BOTH",
      "description": "Partial payment received, contract pending",
      "text_color": "#FF9E00",
      "bg_color": "#FEF8E6"
    },
    {
      "id": "6acae8f7-941a-4dae-ac2b-e1cc5c7d3d25",
      "name": "Fresh Lead",
      "role": "NEW_LEAD",
      "type": "BOTH",
      "description": "Entery Leval",
      "text_color": "#E11D48",
      "bg_color": "#FFF1F2"
    }
  ]
}

Update Lead Status

Update the status of a specific lead by providing a valid status UUID.

PATCH/api/external/leads/:id/status

Path Parameters

:idRequired. The unique lead UUID.

Headers

Content-Type:application/json

Request Body Fields

Field	Type	Required	Description
status_id	string (UUID)	Required	The unique UUID of the status to assign to the lead.

Code Examples

curl -X PATCH "https://api.hermon.io/api/external/leads/24567881-3574-4aa9-82b2-d7837efa10e5/status" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here" \
  -d '{
    "status_id": "4bb2ae65-8ab1-4695-b896-190711a07cd0"
  }'

Response Example

json

{
  "status": "success",
  "message": "Lead status updated successfully",
  "data": {
    "id": "24567881-3574-4aa9-82b2-d7837efa10e5"
  }
}

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"
}