Lead API referenceREST API
for leads.
Suppliers post leads to one endpoint with a campaign key. Everything you can do in the dashboard is available over the REST API too, documented in an OpenAPI spec. You don't need an SDK.
Endpoints
Two kinds of access.
Lead submission uses a per-campaign API key. Everything under /api/v1 uses a signed-in user's session and respects that user's role and permissions. All on https://api.hawfinch.com.
Submit leads
For your suppliers and landing pages, with one POST per lead.
Submit one lead to a campaign, authenticated with the campaign's API key. Answers straight away with accepted or duplicate; routing then runs in the background.
The machine-readable OpenAPI spec for every endpoint. Public, no key needed.
Public health check returning status and the running version.
Leads
Read, search, export and act on leads with a signed-in session.
List leads with page-based pagination (up to 200 per page), filtered by campaign, status, search text and date range.
Full lead detail: custom fields, every delivery attempt with its outcome, and the raw incoming request.
Search with the full filter set. Use /api/v1/leads/export to download the matches as CSV.
Send leads back through routing, optionally skipping caps, active days, filters, suppression or buyer dedup.
Mark a lead as returned by the buyer, reversing its revenue.
Campaigns and reports
Set up campaigns and routing, and pull reports into your own tools.
List campaigns with their group and buyer counts.
Create a campaign. The response includes its new API key.
Update a campaign's settings. Changes apply to the next lead.
Add a delivery group, then attach buyers with /groups/{group_id}/destinations.
Group and pivot leads by campaign, buyer, supplier, source, status or date. GET /api/v1/reports returns the standard report.
Quick start
Send your first lead.
Copy the API key from your campaign's API tab, which also has ready-made curl, JavaScript and Python snippets, and send a lead.
$ curl -X POST https://api.hawfinch.com/api/leads/submit \ -H "X-API-Key: 9f3c41d7a2b84e6c91d05f7e3a6cb82e" \ -H "Content-Type: application/json" \ -d '{ "name": "John Doe", "email": "[email protected]", "phone": "07700900000", "source": "facebook_ads", "postcode": "LS6 2AB" }'
{
"success": true,
"lead_id": "3f6c2a1e-8b4d-4c9a-a7e2-5d0b9c1f4e83",
"status": "accepted"
}
// Already seen in this campaign:
{ "success": false, "status": "duplicate", ... }
// On one of the campaign's suppression lists:
{ "success": false, "status": "suppressed", ... }
Good to know
Keys, responses and routing.
The three things every integration needs to know.
Campaign API keys
Each campaign has its own key, and the key tells us which campaign a lead belongs to. Turn on "Require an API key" so leads without a valid key are refused. Resetting a key stops the old one working straight away.
Read the status field
Duplicates and suppressed leads come back as HTTP 200 with "success": false, so check status rather than the HTTP code. Problems such as an invalid key or an inactive campaign return a 4xx in problem+json format.
Routing happens after
The API answers as soon as the lead is accepted, then routing runs in the background, so the response doesn't say whether the lead sold. See every delivery attempt in the dashboard or with GET /api/v1/leads/{id}.
Start
building.
Your campaign's API key and ready-made snippets are on its API tab in the dashboard. The full reference for every endpoint is in the OpenAPI spec.