API Reference

RESTful APIs built for high-volume lead operations. Authentication, endpoints, and examples.

Quick Start

Submit your first lead in under a minute. Grab your API key from the dashboard and make a single POST request.

request
$ curl -X POST https://api.hawfinch.com/v1/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+447700900000"
  }'
response — 201 Created
{
  "success": true,
  "data": {
    "lead_id": "ld_9f8a7b6c5d4e3f2a",
    "status": "accepted",
    "created_at": "2025-06-15T14:32:07Z",
    "processing_ms": 8
  },
  "message": "Lead submitted successfully"
}

Core Endpoints

Everything you need to manage leads, campaigns, and reporting through a single, consistent API surface.

POST

/v1/leads

Submit a new lead with contact details, source attribution, and custom fields. Validates and routes in real time.

GET

/v1/leads/{id}

Retrieve full lead details including validation status, routing history, and disposition timeline.

GET

/v1/campaigns

List all campaigns with filtering by status, date range, and source. Supports pagination and sorting.

POST

/v1/campaigns

Create a new campaign with routing rules, caps, schedules, and acceptance criteria in a single call.

GET

/v1/reports

Generate real-time reports across leads, revenue, and campaign performance with sub-second query times.

GET

/v1/status

Check system health, API latency, and uptime metrics. Returns current operational status for all services.

Authentication & Limits

Secure, token-based auth with generous rate limits designed for enterprise-scale integrations.

API Key Authentication

All requests require a Bearer token in the Authorization header. Generate keys from your dashboard with granular permission scopes.

Authorization: Bearer sk_live_...

Rate Limits

Standard plans include 10,000 requests per minute. Rate limit headers are included in every response for real-time tracking.

Requests / min 10,000
Burst capacity 15,000
Enterprise Unlimited

API Versioning

All endpoints are versioned via the URL path. We maintain backward compatibility for at least 12 months after a new version ships.

Current v1 (stable)
Preview v2 (beta)
Deprecation 12 months

Official SDKs

Drop-in client libraries so you can skip the boilerplate and start shipping leads in minutes.

Node.js

npm install @hawfinch/sdk

// Submit a lead
const hawfinch = require('@hawfinch/sdk');
const lead = await hawfinch.leads.create({
  email: '[email protected]'
});

Python

pip install hawfinch

# Submit a lead
import hawfinch
client = hawfinch.Client("sk_live_...")
lead = client.leads.create(
  email="[email protected]"
)

PHP

composer require hawfinch/sdk

// Submit a lead
use Hawfinch\Client;
$client = new Client('sk_live_...');
$lead = $client->leads->create([
  'email' => '[email protected]'
]);

Ready to integrate?

Get your API key and start submitting leads in under five minutes. Full sandbox environment included.

Get API Key