Submit Endpoint

POST lead data to Hermon from any external source. Hermon creates or updates the lead automatically, storing UTM data, Q&A, and traffic attribution.

POST/api/opt-in/submit

Headers

Content-Type:application/json

x-api-key:sk_live_your_key_here

Request Body

Field	Type	Required	Description
email	string	Required	Lead's email address
first_name	string	Required	Lead's first name
source	string	Required	Lead source enum — see sources page
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.

Responses

201New lead created

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