Three ways in, one open field for everything else.

Every lead-ingest path — single create, CSV import, webhook — accepts the same email/firstName/lastName/company shape plus an open customFields object for anything else your personalization needs.

WarmHawk has three lead-ingest paths sharing one validation function: POST /v1/leads for a single authenticated create, POST /v1/leads/import for a CSV bulk upload, and the unauthenticated POST /v1/leads/webhook for live pipelines. All three carry an open customFields object, and DELETE /v1/leads/erase handles GDPR right-to-erasure by anonymizing PII while preserving aggregate counts.

Single create

The direct, authenticated entry point — reports suppression/duplicate conflicts as real errors the caller can act on:

curl -X POST https://app.yourcompany.com/v1/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "camp_g7h8i9",
    "email": "jane@prospect-co.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "company": "Prospect Co",
    "customFields": { "jobTitle": "VP Marketing", "recentNews": "closed a $12M Series A" }
  }'

201 with the created lead on success; 409 if the email is on the suppression list or already a lead on that campaign. List leads with GET /v1/leads?campaignId=camp_g7h8i9, which returns { leads, total }.

CSV bulk import

A real file upload — multipart/form-data, not a JSON body. Send a campaignId field alongside the CSV file field. Any column that isn’t email/firstName/lastName/company (case-insensitive) folds automatically into customFields:

curl -X POST https://app.yourcompany.com/v1/leads/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "campaignId=camp_g7h8i9" \
  -F "file=@leads.csv"

email,firstName,lastName,company,jobTitle,recentNews
jane@prospect-co.com,Jane,Doe,Prospect Co,VP Marketing,closed a $12M Series A

{ "imported": 1, "skippedDuplicate": 0, "skippedSuppressed": 0, "rejected": [] }

Capped at 50,000 rows and 10MB per file (413 past either). Every cell is CSV-injection-defended on ingest — a value starting with =, +, -, or @ is neutralized before it’s stored, so a malicious lead field can’t turn into a spreadsheet formula when you later export and open the data.

Webhook ingest — unauthenticated by design

Built for a live pipeline pushing rows continuously (Clay, Apollo, a form backend). No bearer token — rate-limited (30/min) instead, and it skips rather than errors on a suppressed or duplicate address, since an automated caller has no way to act on a 409:

curl -X POST https://app.yourcompany.com/v1/leads/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "camp_g7h8i9",
    "email": "jane@prospect-co.com",
    "firstName": "Jane",
    "company": "Prospect Co",
    "customFields": { "jobTitle": "VP Marketing" }
  }'

Returns 201 { status: "queued", leadId } on success, 200 { status: "skipped", reason: "duplicate" | "suppressed" } on a skip, or 422 { status: "rejected", reason } if required fields are missing.

GDPR erasure

curl -X DELETE https://app.yourcompany.com/v1/leads/erase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@prospect-co.com" }'

Every matching row (across every campaign) has its email/name/company/customFields overwritten with a non-reversible placeholder and piiErasedAt stamped — the row itself is kept so send/reply/campaign aggregate counts referencing it stay accurate. Returns { email, leadsErased }, vacuously succeeding with leadsErased: 0 if nothing matches. This is distinct from DELETE /v1/leads/:id, a real hard delete of one row by id, and from a manual suppress (POST /v1/leads/:id/suppress) — erasure removes data, suppression stops future sends; a lead who wants both needs both calls.

Write a 2-sentence opener to {{firstName}} at {{company}}, referencing that they
{{recentNews}}. Mention their stack ({{techStack}}) only if it's naturally relevant.
No generic filler, no invented facts.