Handled CRM

Lead ingestion API

Give this page to the external research agent. It documents the single endpoint used to create leads in the CRM.

Endpoint

POST /api/leads

Authentication

Send Authorization: Bearer YOUR_AGENT_API_SECRET. The value must match the app's AGENT_API_SECRET.

Success response

Returns JSON with id and created_at on success.

Required fields

Field	Type	Notes
company	string	Company name
score	number	Lead score, typically 0-100
classification	string	One of the supported qualification labels
report_markdown	string	Full markdown report body

Optional fields are accepted for contact info, social metrics, archetype, soft flags, and agent_message_id. Archetype is already accepted today as the top-level archetype field.

Template override fields

The sender can optionally provide an email_payload block to override the default archetype assignment for a specific lead.

"email_payload": {
  "email_template_id": "qualified_calendly",
  "cta_variant": "calendly",
  "lead_status": "qualified",
  "classification": "Qualified – High Value",
  "archetype": "Exciting Growth Lead",
  "partner_type": null,
  "recipient": {
    "first_name": "John",
    "full_name": "John Smith",
    "email": "john@example.com"
  },
  "company": {
    "name": "Example Co",
    "website": "https://example.com",
    "vertical": "skincare"
  },
  "email_vars": {
    "archetype_line": "scaling skincare brands",
    "observation": "Noticed your recent expansion into retail.",
    "calendly_link": "https://calendly.com/example"
  }
}

Sample payload

{
  "company": "Acme Skincare",
  "contact_name": "Jane Smith",
  "contact_email": "jane@acmeskincare.com",
  "contact_phone": "+1 555 123 4567",
  "website": "https://acmeskincare.com",
  "score": 87,
  "classification": "Qualified – High Value",
  "archetype": "Exciting Growth Lead",
  "lead_type": "brand",
  "report_markdown": "# Acme Skincare — Qualified – High Value · 87/100\n\nFull markdown report here...",
  "instagram_handle": "@acmeskincare",
  "instagram_followers": "47k",
  "tiktok_handle": "@acmeskincare",
  "tiktok_followers": "12k",
  "soft_flags": "",
  "agent_message_id": "gmail-message-id-string"
}

Example request

curl -X POST "https://your-domain.com/api/leads" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AGENT_API_SECRET" \
  --data '{
  "company": "Acme Skincare",
  "contact_name": "Jane Smith",
  "contact_email": "jane@acmeskincare.com",
  "contact_phone": "+1 555 123 4567",
  "website": "https://acmeskincare.com",
  "score": 87,
  "classification": "Qualified – High Value",
  "archetype": "Exciting Growth Lead",
  "lead_type": "brand",
  "report_markdown": "# Acme Skincare — Qualified – High Value · 87/100\n\nFull markdown report here...",
  "instagram_handle": "@acmeskincare",
  "instagram_followers": "47k",
  "tiktok_handle": "@acmeskincare",
  "tiktok_followers": "12k",
  "soft_flags": "",
  "agent_message_id": "gmail-message-id-string"
}'

Replace https://your-domain.com with your live Vercel domain and replace YOUR_AGENT_API_SECRET with the shared bearer secret configured for this app.

Accepted values

lead_type

brand or partner

status

Created rows default to new. The sender does not need to provide this.

classification

Qualified – High Value, Qualified – Medium Value, Qualified – Low Value, Not Qualified, Rejected, Partner – High Value, Partner – Low Value

archetype

Exciting Growth Lead, Established Multi-Channel Lead, Scaling DTC Lead, or null