Opt-Ins & Submit API Reference

POST external lead submission data directly into Hermon, and query historical traffic records, UTM attributions, logs, and form submissions.

Submit Endpoint

POST/api/opt-in/submit

Headers

Content-Type:application/json

x-api-key:sk_live_your_key_here

Request Body Fields

Field	Type	Required	Description
email	string	Required	Lead's email address
first_name	string	Required	Lead's first name
source	string	Required	source must be one of: CALENDLY, MANUAL, TYPEFORM, WEBINAR, NEWSLETTER, LANDING_PAGE, OTHER
last_name	string	Optional	Lead's last name
phone_e164	string	Optional	Phone in E.164 format (e.g. +14155552671)
phone_country	string	Optional	ISO country code. Required if phone_e164 provided
provider_form_id	string	Optional	Your form's unique identifier
provider_form_name	string	Optional	Your form's display name
external_reference	string	Optional	Your unique submission ID for idempotency
questions_answers	array	Optional	Q&A pairs from your form (max 50)
traffic	object	Optional	UTM parameters and referrer data

questions_answers item

json

{
  "question": "What is your biggest challenge?",
  "answer": "Generating consistent leads",
  "position": 0
}

traffic object

json

{
  "utm_source": "facebook",
  "utm_medium": "paid",
  "utm_campaign": "q1-coaching",
  "utm_content": "video-ad-1",
  "utm_term": "coaching program",
  "referrer": "https://facebook.com",
  "landing_page": "https://yoursite.com/apply"
}

If traffic.utm_content starts with user_ (a Clerk user ID), Hermon automatically assigns that user as the setter on the lead. This enables automated setter attribution from ad tracking.

Submit Responses

201New lead created via opt-in

json

{
  "status": "success",
  "message": "Lead created via opt-in",
  "data": {
    "opt_in_id": "uuid",
    "lead_id": "uuid",
    "is_new_lead": true
  }
}

200Existing lead updated

json

{
  "status": "success",
  "message": "Opt-in recorded for existing lead",
  "data": {
    "opt_in_id": "uuid",
    "lead_id": "uuid",
    "is_new_lead": false
  }
}

401Missing or invalid API key

json

{
  "status": "error",
  "message": "Invalid or revoked API key"
}

400Validation failure

json

{
  "status": "error",
  "message": "source must be one of: CALENDLY, MANUAL, TYPEFORM, WEBINAR, NEWSLETTER, LANDING_PAGE, OTHER",
}

429Rate limit exceeded

json

{
  "status": "error",
  "message": "Too many requests"
}

Idempotency

Pass external_reference with a unique ID from your system. If the same external_reference + source combination is submitted again, Hermon returns the existing opt-in record without creating a duplicate.

json

{
  "email": "john@example.com",
  "first_name": "John",
  "source": "LANDING_PAGE",
  "external_reference": "typeform-submission-abc123"
}

List Opt-Ins Records

List Opt-Ins

Retrieve a paginated list of opt-ins. Results can be filtered by source and associated lead UUID.

GET/api/external/opt-ins

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 submission source (e.g. LANDING_PAGE, CALENDLY, MANUAL, TYPEFORM, WEBINAR, NEWSLETTER,OTHER).
lead_id	string (UUID)	Optional	Filter by associated lead UUID.

Code Examples

curl -X GET "https://api.hermon.io/api/external/opt-ins?page=1&limit=10&source=CALENDLY&lead_id=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": "Opt-ins fetched successfully",
  "data": [
    {
      "id": "abdde996-c84b-4673-8204-a7e0f3cab618",
      "lead_id": "896e4c72-e390-4baf-906f-395992266222",
      "source": "CALENDLY",
      "provider_form_id": null,
      "provider_form_name": "Millionaire Commerce - Qualification call (MA)",
      "external_reference": "https://api.calendly.com/scheduled_events/248a2fb0-2ce3-4891-91ca-08c4bf715246/invitees/dfe5c266-6ae0-4e4b-80de-8b025097b75a",
      "created_at": "2026-05-26T08:17:38.439Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2703,
    "totalPages": 271,
    "hasNext": true,
    "hasPrev": false
  }
}

Get Opt-In Details

Fetch detailed information for a single opt-in submission record by its unique UUID.

GET/api/external/opt-ins/:id

Path Parameters

:idRequired. The unique opt-in UUID.

Opt-In Object Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the opt-in record.
lead_id	string (UUID)	Associated lead unique identifier.
source	string	Origin source category (e.g. LANDING_PAGE, CALENDLY, MANUAL, TYPEFORM, WEBINAR, NEWSLETTER,OTHER).
provider_form_id	string \| null	External provider form unique identifier.
provider_form_name	string \| null	External provider form display name.
external_reference	string \| null	External provider reference link or identifier.
question_answers	array	Submitted question-answer pairs (id, question, answer, position) [Details API Only].
traffic_attribution	object	Attributed traffic analytics (utm_source, utm_medium, utm_campaign, utm_content, utm_term, referrer, landing_page) [Details API Only].
created_at	string	ISO 8601 timestamp when the opt-in was recorded.

Code Examples

curl -X GET "https://api.hermon.io/api/external/opt-ins/522b1759-d354-472c-8fb2-1a9bbc69eb9b" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "status": "success",
  "message": "Opt-in fetched successfully",
  "data": {
    "id": "522b1759-d354-472c-8fb2-1a9bbc69eb9b",
    "lead_id": "29f94ab7-37fb-46b9-bda1-4cc594225da2",
    "source": "CALENDLY",
    "provider_form_id": null,
    "provider_form_name": "Qualification call - Millionaire Commerce (ST)",
    "external_reference": "https://api.calendly.com/scheduled_events/b3d8ad9c-b082-44ed-ac4c-aa3f05559574/invitees/b8c46aee-2453-47c9-97bd-6fb35b142f6a",
    "created_at": "2026-05-26T00:09:54.465Z",
    "question_answers": [
      {
        "id": "a9c3f245-f0d0-4aeb-b4d3-87d7de7023e5",
        "question": "Please share anything that will help prepare for our meeting.",
        "answer": "New to this ",
        "position": 0
      },
      {
        "id": "8a50d0d8-745f-4c4a-9e4b-bb67a852d8ae",
        "question": "What is your Instagram?",
        "answer": "Mustaxsadeq123@gmail.com",
        "position": 1
      }
    ],
    "traffic_attribution": {
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_content": null,
      "utm_term": null,
      "referrer": null,
      "landing_page": null
    }
  }
}

Management Errors

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