Leads API Reference

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

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.
Rate Limiting: Requests are subject to organization-level rate limits. If exceeded, a 429 Too Many Requests error is returned.

List Leads

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

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
search	string	Optional	Find a lead by email (case-insensitive substring) or phone number (notation-insensitive). See Search.
source	string	Optional	Filter by lead source. See Lead Source Values.
status_role	string	Optional	Comma-separated list of status roles. See Status Role Values.
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 to filter by.
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_from. Accepts YYYY-MM-DD or ISO 8601.
updated_at	string	Optional	Upper bound for updated_at. Accepts YYYY-MM-DD or ISO 8601.

Search

Use searchto locate a specific lead by email or phone number — useful for resolving a lead's id before calling the detail, custom field, or status-update endpoints. It combines with the date-range filters and pagination, and a value that matches nothing returns an empty list.

Email — any value containing a non-phone character (a letter, @, ., etc.) is matched against the email, case-insensitively, as a substring. Both john and JOHN.DOE@example.com match john.doe@example.com.
Phone — a value made up only of digits, +, spaces, dashes, and parentheses is matched against the phone number. Leading zeros are ignored and local and international notations are treated as equivalent. For a lead stored as +31612345678, all of 0612345678, +31612345678, and 0031612345678 match. Name and custom-field matching are not supported.

Code Examples

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

Response Example

json

{
  "success": true,
  "message": "Leads fetched successfully",
  "data": [
    {
      "id": "e799c30f-9da7-4fd7-9552-83b96a9bfac2",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_e164": "+14155551234",
      "phone_country": "US",
      "source": "LANDING_PAGE",
      "sales_status": {
        "id": "status_xyz123",
        "name": "New Lead",
        "role": "NEW_LEAD",
        "description": "Newly imported lead",
        "text_color": "#2563EB",
        "bg_color": "#DBEAFE"
      },
      "setter": null,
      "triager": null,
      "closer": null,
      "notes": [],
      "counts": {
        "notes": 0,
        "appointments": 1,
        "contracts": 0,
        "payments": 0,
        "opt_ins": 1,
        "deliveries": 0
      },
      "custom_fields": [
        {
          "id": "field_age",
          "name": "Age",
          "value": 30
        }
      ],
      "first_source": {
        "id": "src_fb",
        "name": "Facebook Ads"
      },
      "last_source": {
        "id": "src_fb",
        "name": "Facebook Ads"
      },
      "next_touch_point_at": "2026-02-10T15:00:00.000Z",
      "next_touch_point_type": "PHONE_CALL",
      "created_at": "2026-02-08T10:00:00.000Z",
      "updated_at": "2026-02-08T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "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	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 3166-1 alpha-2 country code derived from phone.
source	string (enum)	Lead source (e.g. CALENDLY, TYPEFORM, WEB_FORM). See Lead Source Values.
sales_status	object	Current status details. See Lead Status Object.
setter	object \| null	Assigned setter. See Lead User Object.
triager	object \| null	Assigned triager. See Lead User Object.
closer	object \| null	Assigned closer. See Lead User Object.
notes	array	Latest note(s) on the lead. See Lead Note Object.
counts	object	Total count of related resources. See Lead Counts Object.
custom_fields	array	Assigned custom field values. See Lead Custom Field Object.
first_source	object \| null	First marketing attribution source. See Lead Source Object.
last_source	object \| null	Last marketing attribution source. See Lead Source Object.
next_touch_point_at	string (ISO 8601) \| null	UTC timestamp of the next scheduled touchpoint.
next_touch_point_type	string (enum) \| null	Type of next touchpoint. See Lead Touch Point Type Values.
billing_details	object \| null	Billing information. See Lead Billing Details Object [Details API Only].
created_at	string (ISO 8601)	UTC timestamp of creation.
updated_at	string (ISO 8601)	UTC timestamp of last update.

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

{
  "success": true,
  "message": "Lead fetched successfully",
  "data": {
    "id": "e799c30f-9da7-4fd7-9552-83b96a9bfac2",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_e164": "+14155551234",
    "phone_country": "US",
    "source": "LANDING_PAGE",
    "sales_status": {
      "id": "status_xyz123",
      "name": "New Lead",
      "role": "NEW_LEAD",
      "description": "Newly imported lead",
      "text_color": "#2563EB",
      "bg_color": "#DBEAFE"
    },
    "setter": null,
    "triager": null,
    "closer": null,
    "notes": [],
    "counts": {
      "notes": 0,
      "appointments": 1,
      "contracts": 0,
      "payments": 0,
      "opt_ins": 1,
      "deliveries": 0
    },
    "custom_fields": [],
    "first_source": {
      "id": "src_fb",
      "name": "Facebook Ads"
    },
    "last_source": {
      "id": "src_fb",
      "name": "Facebook Ads"
    },
    "next_touch_point_at": "2026-02-10T15:00:00.000Z",
    "next_touch_point_type": "PHONE_CALL",
    "billing_details": {
      "id": "bill_xyz123",
      "business_name": "Doe Coaching LLC",
      "address": "123 Main St",
      "zipcode": "94105",
      "province": "CA",
      "country": "US",
      "vat_number": null,
      "created_at": "2026-02-08T10:00:00.000Z",
      "updated_at": "2026-02-08T10:00:00.000Z"
    },
    "created_at": "2026-02-08T10:00:00.000Z",
    "updated_at": "2026-02-08T10:30:00.000Z"
  }
}

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

{
  "success": true,
  "message": "Lead status updated successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": {
      "id": "status_xyz789",
      "name": "Follow-up Required",
      "role": "FOLLOW_UP"
    }
  }
}

Values Reference

Lead Source Values

Value	Description
CALENDLY	Calendly integration
ICLOSED	iClosed integration
GOHIGHLEVEL	GoHighLevel integration
MANUAL	Manually created
TYPEFORM	Typeform integration
WEBINAR	Webinar signup
NEWSLETTER	Newsletter subscription
LANDING_PAGE	Landing page submission
OTHER	Other source

Status Role Values

Value	Description
NEW_LEAD	New/unqualified lead
APPOINTMENT_BOOKED	Appointment scheduled
NO_SHOW	Lead did not attend appointment
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

Touch Point Type Values

Value	Description
PHONE_CALL	Phone call
WHATSAPP	WhatsApp message
EMAIL	Email
FOLLOW_UP_CALL	Follow-up phone call
PROPOSAL_REVIEW	Proposal review meeting
OTHER	Other touchpoint type

Nested Objects Reference

User Object Fields

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

Source Object Fields

Field	Type	Description
id	string	Marketing source ID
name	string	Marketing source name

Status Object Fields

Field	Type	Description
id	string	Status ID
name	string	Status display name
role	string	Status role (enum value)
description	string	Status description
text_color	string	Hex color code for text
bg_color	string	Hex color code for background

Billing Details Object Fields

Field	Type	Description
id	string	Billing details ID
business_name	string	Company/business name
address	string	Street address
zipcode	string	Postal/ZIP code
province	string	State/province
country	string	ISO 3166-1 alpha-2 country code
vat_number	string	VAT/tax ID number
created_at	string (ISO 8601)	When billing details were added
updated_at	string (ISO 8601)	When billing details were last updated

Note Object Fields

Field	Type	Description
note	string	Note content
mention_users	array	Users @mentioned in the note (always empty on list)

Counts Object Fields

Field	Type	Description
notes	integer	Number of notes
appointments	integer	Number of appointments
contracts	integer	Number of contracts
payments	integer	Number of payments
opt_ins	integer	Number of opt-in submissions
deliveries	integer	Number of delivery engagements

Custom Field Object Fields

Field	Type	Description
id	string	Custom field definition ID
name	string	Custom field name
value	any	Field value (type depends on field definition)

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