EZLeedsGet API Key

API Documentation

47 endpoints across 10 categories. Build integrations with the EZLeeds platform using our REST API.

Getting Started

Base URL

https://api.ezleeds.com/api/v1

Authentication

X-API-Key: your_key_here

Rate Limits

100 requests/min per API key

Example Request

curl -X GET https://api.ezleeds.com/api/v1/leads/ \
  -H "X-API-Key: your_key_here" \
  -H "Content-Type: application/json"

Lead Management

Ingest, list, update, and manage leads through their lifecycle.

7 endpoints
POST/leads/inbound

Ingest a new lead into the platform. Triggers qualification, dedup, and routing.

Auth:X-API-Key

Request Body

{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+17025551234",
  "state": "NV",
  "zip_code": "89101",
  "campaign_type": "legal_pi",
  "source": "landing_page_v3",
  "consent": {
    "consent_type": "tcpa_express_written",
    "consent_text": "I agree to be contacted...",
    "ip_address": "203.0.113.42",
    "page_url": "https://example.com/intake"
  }
}

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "qualified",
  "score": 87,
  "consent_certificate_id": "cert_abc123def456",
  "created_at": "2026-04-22T14:30:00Z"
}
GET/leads/

List leads with pagination, filtering by status, campaign, date range, and more.

Auth:X-API-Key

Response

{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "first_name": "Jane",
      "last_name": "Doe",
      "status": "delivered",
      "score": 87,
      "campaign_type": "legal_pi",
      "created_at": "2026-04-22T14:30:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 25
}
GET/leads/{id}

Get full details for a single lead including events, consent records, and buyer assignment.

Auth:X-API-Key

Response

{
  "id": "a1b2c3d4-...",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+17025551234",
  "state": "NV",
  "status": "delivered",
  "score": 87,
  "buyer_id": "buyer_xyz",
  "sold_price_cents": 35000,
  "events": [...],
  "consent_records": [...]
}
PATCH/leads/{id}

Update lead fields (status, contact info, notes). Creates an audit trail event.

Auth:X-API-Key

Request Body

{
  "status": "contacted",
  "notes": "Left voicemail, will follow up tomorrow."
}

Response

{
  "id": "a1b2c3d4-...",
  "status": "contacted",
  "updated_at": "2026-04-22T15:00:00Z"
}
PATCH/leads/{id}/internal

Admin-only update. Allows modifying protected fields like score, buyer assignment, and pricing.

Auth:X-API-Key (admin)

Request Body

{
  "score": 92,
  "buyer_id": "buyer_xyz",
  "sold_price_cents": 40000
}

Response

{
  "id": "a1b2c3d4-...",
  "score": 92,
  "buyer_id": "buyer_xyz",
  "updated_at": "2026-04-22T15:05:00Z"
}
POST/leads/{id}/accept

Buyer accepts the lead. Finalizes billing and triggers delivery confirmation.

Auth:X-API-Key

Response

{
  "id": "a1b2c3d4-...",
  "status": "accepted",
  "accepted_at": "2026-04-22T15:10:00Z",
  "billing_event_id": "bill_789"
}
POST/leads/{id}/return

Buyer returns the lead within the return window. Must include a reason.

Auth:X-API-Key

Request Body

{
  "reason": "invalid_phone",
  "notes": "Number disconnected on first dial."
}

Response

{
  "id": "a1b2c3d4-...",
  "status": "returned",
  "return_reason": "invalid_phone",
  "returned_at": "2026-04-22T15:30:00Z",
  "credit_issued": true
}

Campaigns

Create and manage lead generation campaigns with targeting criteria.

4 endpoints
POST/campaigns/

Create a new campaign with targeting criteria, budget, and delivery settings.

Auth:X-API-Key

Request Body

{
  "name": "NV Personal Injury Q2",
  "campaign_type": "legal_pi",
  "states": ["NV", "CA", "AZ"],
  "budget_cents": 5000000,
  "max_leads_per_day": 50,
  "delivery_webhook": "https://crm.example.com/leads"
}

Response

{
  "id": "camp_abc123",
  "name": "NV Personal Injury Q2",
  "status": "active",
  "created_at": "2026-04-22T10:00:00Z"
}
GET/campaigns/

List all campaigns for the authenticated tenant.

Auth:X-API-Key

Response

{
  "items": [
    {
      "id": "camp_abc123",
      "name": "NV Personal Injury Q2",
      "status": "active",
      "leads_delivered": 127,
      "budget_remaining_cents": 3205000
    }
  ],
  "total": 3
}
GET/campaigns/{id}

Get campaign details including performance metrics and delivery stats.

Auth:X-API-Key

Response

{
  "id": "camp_abc123",
  "name": "NV Personal Injury Q2",
  "campaign_type": "legal_pi",
  "status": "active",
  "states": ["NV", "CA", "AZ"],
  "leads_delivered": 127,
  "leads_accepted": 118,
  "leads_returned": 9,
  "acceptance_rate": 0.929,
  "avg_cost_cents": 32500
}
PATCH/campaigns/{id}

Update campaign settings. Can pause, adjust budget, or modify targeting.

Auth:X-API-Key

Request Body

{
  "status": "paused",
  "max_leads_per_day": 25
}

Response

{
  "id": "camp_abc123",
  "status": "paused",
  "updated_at": "2026-04-22T16:00:00Z"
}

Buyers

Manage buyer profiles, matching criteria, and webhook endpoints.

5 endpoints
POST/buyers/

Register a new buyer with targeting preferences and delivery configuration.

Auth:X-API-Key

Request Body

{
  "name": "Acme Legal Partners",
  "campaign_types": ["legal_pi", "legal_mass_tort"],
  "states": ["NV", "CA"],
  "max_price_cents": 50000,
  "webhook_url": "https://acme.example.com/leads",
  "webhook_secret": "whsec_abc123"
}

Response

{
  "id": "buyer_xyz",
  "name": "Acme Legal Partners",
  "status": "active",
  "created_at": "2026-04-22T10:00:00Z"
}
GET/buyers/

List all registered buyers for the tenant.

Auth:X-API-Key

Response

{
  "items": [
    {
      "id": "buyer_xyz",
      "name": "Acme Legal Partners",
      "status": "active",
      "leads_purchased": 84,
      "total_spent_cents": 2730000
    }
  ],
  "total": 5
}
GET/buyers/match

Find buyers matching a specific lead profile. Used internally by the routing engine.

Auth:X-API-Key

Request Body

Query params: ?campaign_type=legal_pi&state=NV&zip_code=89101

Response

{
  "matches": [
    {
      "buyer_id": "buyer_xyz",
      "name": "Acme Legal Partners",
      "bid_cents": 35000,
      "exclusivity": "shared"
    }
  ]
}
GET/buyers/{id}

Get buyer details including performance metrics and active filters.

Auth:X-API-Key

Response

{
  "id": "buyer_xyz",
  "name": "Acme Legal Partners",
  "campaign_types": ["legal_pi", "legal_mass_tort"],
  "states": ["NV", "CA"],
  "leads_purchased": 84,
  "acceptance_rate": 0.94,
  "avg_response_time_ms": 1200
}
PATCH/buyers/{id}

Update buyer settings, targeting criteria, or webhook configuration.

Auth:X-API-Key

Request Body

{
  "states": ["NV", "CA", "AZ"],
  "max_price_cents": 55000
}

Response

{
  "id": "buyer_xyz",
  "states": ["NV", "CA", "AZ"],
  "updated_at": "2026-04-22T16:30:00Z"
}

Ping-Post

Real-time bidding protocol. Ping with anonymous lead data to get bids, then post the full lead to the winning buyer.

2 endpoints
POST/pingpost/ping

Send minimal (non-PII) lead data and receive buyer bids. Bids expire in 60 seconds.

Auth:X-Compliance-API-Key

Request Body

{
  "campaign_type": "legal_pi",
  "state": "NV",
  "zip_code": "89101",
  "source": "landing_page_v3"
}

Response

{
  "ping_id": "ping_a1b2c3d4e5f6",
  "expires_at": "2026-04-22T14:31:00Z",
  "bids": [
    {
      "buyer_id": "buyer_xyz",
      "buyer_name": "Acme Legal",
      "bid_cents": 35000,
      "exclusivity": "shared"
    }
  ],
  "floor_price_cents": 25000
}
POST/pingpost/post

Deliver full lead data (with PII and consent) to the selected buyer from a previous ping.

Auth:X-Compliance-API-Key

Request Body

{
  "ping_id": "ping_a1b2c3d4e5f6",
  "buyer_id": "buyer_xyz",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+17025551234",
    "email": "[email protected]",
    "state": "NV",
    "zip_code": "89101"
  },
  "consent": {
    "consent_type": "tcpa_express_written",
    "consent_text": "I agree to be contacted...",
    "ip_address": "203.0.113.42",
    "page_url": "https://example.com/intake"
  }
}

Response

{
  "accepted": true,
  "lead_id": "a1b2c3d4-...",
  "buyer_id": "buyer_xyz",
  "price_cents": 35000,
  "consent_certificate_id": "cert_abc123",
  "delivery_status": "delivered"
}

Compliance

Pre-flight checks, consent verification, DNC lookups, and state-by-state rules.

6 endpoints
POST/compliance/check-outreach

Pre-flight compliance check before contacting a lead. Validates state rules, time windows, and consent.

Auth:X-Compliance-API-Key

Request Body

{
  "phone": "+17025551234",
  "state": "NV",
  "channel": "sms",
  "campaign_type": "legal_pi",
  "has_consent": true
}

Response

{
  "allowed": true,
  "checks": {
    "state_rules": "pass",
    "time_window": "pass",
    "consent_valid": "pass",
    "dnc_clear": "pass"
  },
  "warnings": []
}
POST/compliance/verify-consent

Verify a consent certificate is valid and has not been revoked.

Auth:X-Compliance-API-Key

Request Body

{
  "certificate_id": "cert_abc123def456"
}

Response

{
  "valid": true,
  "certificate": {
    "id": "cert_abc123def456",
    "consent_type": "tcpa_express_written",
    "channel": "web",
    "created_at": "2026-04-22T14:30:00Z",
    "is_active": true
  }
}
POST/compliance/record-consent

Record a new consent event with cryptographic certificate. TrustedForm equivalent.

Auth:X-Compliance-API-Key

Request Body

{
  "lead_id": "a1b2c3d4-...",
  "consent_type": "tcpa_express_written",
  "channel": "web",
  "mechanism": "web_form",
  "consent_text": "I agree to be contacted...",
  "ip_address": "203.0.113.42",
  "user_agent": "Mozilla/5.0...",
  "page_url": "https://example.com/intake"
}

Response

{
  "certificate_id": "cert_new789xyz",
  "created_at": "2026-04-22T14:30:00Z",
  "hash": "sha256:a1b2c3..."
}
GET/compliance/rules/{state}

Get compliance rules for a specific state (calling hours, consent requirements, restrictions).

Auth:X-Compliance-API-Key

Response

{
  "state": "CA",
  "calling_hours": { "start": "08:00", "end": "21:00", "timezone": "America/Los_Angeles" },
  "two_party_consent": true,
  "telemarketing_registration_required": true,
  "mini_tcpa": true,
  "additional_restrictions": [
    "California requires prior express written consent for autodialed calls"
  ]
}
GET/compliance/rules

Get compliance rules for all 50 states + DC.

Auth:X-Compliance-API-Key

Response

{
  "states": {
    "AL": { "calling_hours": {...}, "two_party_consent": false, ... },
    "AK": { ... },
    ...
  },
  "total": 51
}
POST/compliance/dnc-check

Check a phone number against federal and state Do-Not-Call registries.

Auth:X-Compliance-API-Key

Request Body

{
  "phone": "+17025551234",
  "state": "NV"
}

Response

{
  "on_dnc": false,
  "checks": {
    "federal_dnc": false,
    "state_dnc": false,
    "internal_dnc": false
  }
}

Billing

Usage tracking, invoices, credits, and payment management.

5 endpoints
GET/billing/usage

Get current billing period usage summary.

Auth:X-API-Key

Response

{
  "period": "2026-04",
  "leads_purchased": 127,
  "total_spend_cents": 4127500,
  "credits_remaining_cents": 872500,
  "avg_cost_per_lead_cents": 32500
}
GET/billing/invoices

List invoices with status and payment details.

Auth:X-API-Key

Response

{
  "items": [
    {
      "id": "inv_001",
      "period": "2026-03",
      "amount_cents": 3850000,
      "status": "paid",
      "paid_at": "2026-04-01T00:00:00Z"
    }
  ]
}
POST/billing/credits/add

Add credits to a tenant account (admin only).

Auth:X-API-Key (admin)

Request Body

{
  "amount_cents": 1000000,
  "reason": "Promotional credit"
}

Response

{
  "balance_cents": 1872500,
  "credit_id": "cred_abc123"
}
GET/billing/transactions

List all billing transactions (charges, credits, refunds).

Auth:X-API-Key

Response

{
  "items": [
    {
      "id": "txn_001",
      "type": "charge",
      "amount_cents": 35000,
      "description": "Lead #a1b2c3d4 delivered",
      "created_at": "2026-04-22T14:30:00Z"
    }
  ],
  "total": 89
}
POST/billing/refund

Issue a refund for a returned or invalid lead.

Auth:X-API-Key (admin)

Request Body

{
  "lead_id": "a1b2c3d4-...",
  "reason": "invalid_phone"
}

Response

{
  "refund_id": "ref_xyz789",
  "amount_cents": 35000,
  "status": "processed"
}

Sequences

Multi-step outreach sequences combining email, SMS, and calls.

6 endpoints
POST/sequences/

Create a new outreach sequence with multiple steps.

Auth:X-API-Key

Request Body

{
  "name": "PI Intake Follow-Up",
  "steps": [
    { "channel": "sms", "delay_minutes": 0, "template": "Hi {{first_name}}..." },
    { "channel": "email", "delay_minutes": 30, "template_id": "tpl_welcome" },
    { "channel": "call", "delay_minutes": 120 }
  ]
}

Response

{
  "id": "seq_abc123",
  "name": "PI Intake Follow-Up",
  "steps": 3,
  "status": "active"
}
GET/sequences/

List all sequences for the tenant.

Auth:X-API-Key

Response

{
  "items": [
    { "id": "seq_abc123", "name": "PI Intake Follow-Up", "steps": 3, "enrolled": 42, "status": "active" }
  ]
}
GET/sequences/{id}

Get sequence details including step definitions and performance metrics.

Auth:X-API-Key

Response

{
  "id": "seq_abc123",
  "name": "PI Intake Follow-Up",
  "steps": [...],
  "enrolled": 42,
  "completed": 28,
  "conversion_rate": 0.38
}
POST/sequences/{id}/enroll

Enroll a lead into a sequence.

Auth:X-API-Key

Request Body

{
  "lead_id": "a1b2c3d4-..."
}

Response

{
  "enrollment_id": "enr_xyz",
  "sequence_id": "seq_abc123",
  "lead_id": "a1b2c3d4-...",
  "next_step_at": "2026-04-22T14:30:00Z"
}
POST/sequences/{id}/pause

Pause the sequence. No new steps will execute until resumed.

Auth:X-API-Key

Response

{
  "id": "seq_abc123",
  "status": "paused"
}
DELETE/sequences/{id}/enrollments/{lead_id}

Remove a lead from a sequence.

Auth:X-API-Key

Response

{
  "removed": true,
  "lead_id": "a1b2c3d4-..."
}

Domains

Manage sending domains for email deliverability (SPF, DKIM, DMARC).

5 endpoints
POST/domains/

Register a new sending domain and get DNS records to configure.

Auth:X-API-Key

Request Body

{
  "domain": "mail.acmelegal.com"
}

Response

{
  "id": "dom_abc",
  "domain": "mail.acmelegal.com",
  "status": "pending_verification",
  "dns_records": [
    { "type": "TXT", "name": "mail.acmelegal.com", "value": "v=spf1 include:..." },
    { "type": "CNAME", "name": "ezl._domainkey.mail.acmelegal.com", "value": "..." },
    { "type": "TXT", "name": "_dmarc.mail.acmelegal.com", "value": "v=DMARC1; p=none" }
  ]
}
GET/domains/

List all registered domains with verification status.

Auth:X-API-Key

Response

{
  "items": [
    { "id": "dom_abc", "domain": "mail.acmelegal.com", "status": "verified", "verified_at": "2026-04-20T..." }
  ]
}
GET/domains/{id}

Get domain details and current DNS verification status.

Auth:X-API-Key

Response

{
  "id": "dom_abc",
  "domain": "mail.acmelegal.com",
  "status": "verified",
  "spf_valid": true,
  "dkim_valid": true,
  "dmarc_valid": true
}
POST/domains/{id}/verify

Trigger DNS verification check for a domain.

Auth:X-API-Key

Response

{
  "id": "dom_abc",
  "status": "verified",
  "spf_valid": true,
  "dkim_valid": true,
  "dmarc_valid": true,
  "verified_at": "2026-04-22T17:00:00Z"
}
DELETE/domains/{id}

Remove a sending domain.

Auth:X-API-Key

Response

{
  "deleted": true,
  "domain": "mail.acmelegal.com"
}

Reports

Analytics and reporting for leads, campaigns, and billing.

4 endpoints
GET/reports/dashboard

Get dashboard summary metrics for the current period.

Auth:X-API-Key

Response

{
  "period": "2026-04",
  "leads_total": 342,
  "leads_qualified": 298,
  "leads_delivered": 271,
  "acceptance_rate": 0.93,
  "revenue_cents": 8817500,
  "avg_lead_cost_cents": 32500
}
GET/reports/campaigns

Performance breakdown by campaign.

Auth:X-API-Key

Response

{
  "campaigns": [
    {
      "id": "camp_abc123",
      "name": "NV Personal Injury Q2",
      "leads": 127,
      "accepted": 118,
      "returned": 9,
      "revenue_cents": 4127500
    }
  ]
}
GET/reports/buyers

Performance breakdown by buyer.

Auth:X-API-Key

Response

{
  "buyers": [
    {
      "id": "buyer_xyz",
      "name": "Acme Legal Partners",
      "leads_purchased": 84,
      "acceptance_rate": 0.94,
      "total_spent_cents": 2730000
    }
  ]
}
GET/reports/export

Export leads or transactions as CSV.

Auth:X-API-Key

Response

Content-Type: text/csv

id,first_name,last_name,status,score,...
a1b2c3d4,Jane,Doe,delivered,87,...

Webhook Testing

Test your webhook endpoint before going live. Validate signatures and inspect payloads.

3 endpoints
POST/webhook-test/send

Send a test webhook payload to your endpoint with HMAC signature.

Auth:None (public)

Request Body

{
  "url": "https://crm.example.com/leads",
  "secret": "whsec_abc123"
}

Response

{
  "status_code": 200,
  "response_body": "OK",
  "latency_ms": 142,
  "signature_sent": "sha256=a1b2c3d4...",
  "success": true
}
POST/webhook-test/validate

Validate an HMAC webhook signature against a payload and secret.

Auth:None (public)

Request Body

{
  "payload": "{\"lead_id\": \"a1b2c3d4-...\"}",
  "signature": "sha256=a1b2c3d4...",
  "secret": "whsec_abc123"
}

Response

{
  "valid": true,
  "expected_signature": "sha256=a1b2c3d4..."
}
GET/webhook-test/sample-payload

Get the exact JSON payload format that will be sent to your webhook.

Auth:None (public)

Response

{
  "event": "lead.delivered",
  "timestamp": "2026-04-22T14:30:00Z",
  "data": {
    "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+17025551234",
    "state": "NV",
    "zip_code": "89101",
    "campaign_type": "legal_pi",
    "score": 87,
    "consent_certificate_id": "cert_abc123def456",
    "sold_price_cents": 35000
  }
}