REST API • v1

API Reference

The LeadLeap API gives you programmatic access to 30M+ B2B contacts, email validation, lead enrichment, and webhook events. Build data pipelines, automate outreach workflows, or power internal tooling with our REST API.

Base URL

https://api.leadleap.net/api/v1

Protocol

HTTPS only

Format

JSON (UTF-8)

Versioning

The API is versioned via the URL path (/api/v1/). We will never make breaking changes to a published version. When a new major version is released, the previous version remains available for at least 12 months with deprecation notices in response headers.

Authentication

All API requests require authentication using a Bearer token in the Authorization header. API keys have the format ll_<64 hex chars>.

Example request

curl "https://api.leadleap.net/api/v1/leads?country=US&sector=Technology" \
  -H "Authorization: Bearer ll_your_api_key_here"

Getting an API key

Log in to your LeadLeap dashboard
Navigate to Settings → API Keys
Click Generate Key and select the required scopes
Copy the key immediately — it is only shown once

Go to API Keys

Security note: Never expose API keys in client-side code. Keys are SHA-256 hashed in our database and cannot be recovered if lost. API access requires the Scale plan or higher.

Rate Limiting

Each API key has a per-minute rate limit (default: 60 req/min). Rate limit information is returned in every response.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (on 429 response)

429 Too Many Requests

{
  "data": null,
  "meta": {
    "request_id": "req_4f3a9b2c1d8e7f6a",
    "timestamp": "2026-02-26T14: 30: 00.000Z"
  },
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. You are allowed 60 requests per minute.",
    "status": 429,
    "retry_after": 12
  }
}

Response Format

All responses use a consistent envelope structure with data, meta, and error fields.

Success (2xx)

{
  "data": { ... },
  "meta": {
    "request_id": "req_4f3a9b2c1d8e7f6a",
    "timestamp": "2026-02-26T14: 30: 00.000Z",
    "total": 1250,
    "page": 1,
    "per_page": 25
  },
  "error": null
}

Error (4xx / 5xx)

{
  "data": null,
  "meta": {
    "request_id": "req_9e8d7c6b5a4f3e2d",
    "timestamp": "2026-02-26T14: 30: 01.000Z"
  },
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key.",
    "status": 401
  }
}

Endpoints

GET/leadsleads:read

Search and filter the LeadLeap database of 30M+ B2B contacts. Results are paginated and contact details (email, phone, LinkedIn) are masked unless the lead has been unlocked.

Query Parameters

Name	Type	Required	Description
`type`	`string`	No	Lead type: 'business' (default) or 'consumer'
`country`	`string`	No	Comma-separated country names (e.g., US,Canada)
`sector`	`string`	No	Broad sector (e.g., Technology,Healthcare)
`industry`	`string`	No	Granular industry (~95 categories)
`company_size`	`string`	No	Company size bracket (e.g., 1-10,11-50)
`size_range`	`string`	No	Revenue size range
`department`	`string`	No	Department (e.g., Engineering,Sales)
`job_level`	`string`	No	Job level (e.g., C-Level,Director,Manager)
`state`	`string`	No	US state (e.g., California,Texas)
`year_founded_min`	`integer`	No	Minimum year founded (e.g., 2010)
`year_founded_max`	`integer`	No	Maximum year founded (e.g., 2023)
`employee_count_min`	`integer`	No	Minimum employee count
`employee_count_max`	`integer`	No	Maximum employee count
`page`	`integer`	No	Page number, 1-indexed (default: 1)
`per_page`	`integer`	No	Results per page, max 100 (default: 25)

Example request

curl "https://api.leadleap.net/api/v1/leads?type=business&country=US&sector=Technology&department=Engineering&per_page=5" \
  -H "Authorization: Bearer ll_your_api_key"

Example response

{
  "data": [
    {
      "id": "c_7f3a2b9d1e8c5f4a",
      "company_name": "Acme Corp",
      "company_domain": "acme.com",
      "contact_name": "Sarah Mitchell",
      "first_name": "Sarah",
      "last_name": "Mitchell",
      "email": "sa***@acme.com",
      "phone": "+1415****78",
      "job_title": "Senior Software Engineer",
      "department": "Engineering",
      "industry": "Software & SaaS",
      "company_size": "51-200",
      "employee_count": 120,
      "country": "US",
      "state": "California",
      "city": "San Francisco",
      "ai_score": 87,
      "is_unlocked": false
    }
  ],
  "meta": {
    "request_id": "req_4f3a9b2c1d8e7f6a",
    "timestamp": "2026-02-26T14: 30: 00.000Z",
    "total": 142500,
    "page": 1,
    "per_page": 5,
    "total_pages": 28500
  },
  "error": null
}

POST/leads/unlockleads:unlock

Unlock a lead to reveal full contact details (email, phone, LinkedIn URL). Costs 1 credit. If the lead was previously unlocked, cached data is returned at no charge.

Request Body

Name	Type	Required	Description
`lead_id`	`string`	Yes	The lead ID from a search result

Example request

curl -X POST "https://api.leadleap.net/api/v1/leads/unlock" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_id": "c_7f3a2b9d1e8c5f4a"}'

Example response

{
  "data": {
    "id": "c_7f3a2b9d1e8c5f4a",
    "full_name": "Sarah Mitchell",
    "first_name": "Sarah",
    "last_name": "Mitchell",
    "email_primary": "[email protected]",
    "email_second": "[email protected]",
    "phone": "+14155551278",
    "company_phone": "+14155550100",
    "job_title": "Senior Software Engineer",
    "company_name": "Acme Corp",
    "company_domain": "acme.com",
    "linkedin_url": "https://linkedin.com/in/sarahmitchell",
    "industry": "Software & SaaS",
    "country": "US",
    "state": "California",
    "city": "San Francisco",
    "ai_score": 87
  },
  "meta": {
    "request_id": "req_8a7b6c5d4e3f2g1h",
    "timestamp": "2026-02-26T14: 31: 00.000Z",
    "credits_used": 1,
    "credits_remaining": 249,
    "cached": false
  },
  "error": null
}

POST/leads/exportleads:export

Export up to 500 leads as a CSV or JSON file download. Unlocked leads are included at no additional cost. Locked leads consume 1 credit each. Returns a file attachment with Content-Disposition.

Request Body

Name	Type	Required	Description
`lead_ids`	`string[]`	Yes	Array of lead IDs to export (max 500)
`format`	`string`	No	Export format: 'csv' (default) or 'json'

Example request

curl -X POST "https://api.leadleap.net/api/v1/leads/export" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_ids": ["c_7f3a2b9d", "c_1a2b3c4d", "c_5e6f7a8b"], "format": "csv"}' \
  --output leads-export.csv

Response headers includeX-Total-Leads,X-New-Unlocks, andX-Cached-Unlocks. The response body is the raw file content.

POST/leads/enrichleads:enrich

Retrieve the full enriched dataset for a contact from the MCP gateway. Returns all available fields including company description, LinkedIn IDs, and AI scores. Does not consume credits.

Request Body

Name	Type	Required	Description
`lead_id`	`string`	Yes	The lead ID to enrich

Example request

curl -X POST "https://api.leadleap.net/api/v1/leads/enrich" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_id": "c_7f3a2b9d1e8c5f4a"}'

Example response

{
  "data": {
    "id": "c_7f3a2b9d1e8c5f4a",
    "full_name": "Sarah Mitchell",
    "first_name": "Sarah",
    "middle_name": null,
    "last_name": "Mitchell",
    "email_primary": "[email protected]",
    "email_second": null,
    "phone": "+14155551278",
    "company_phone": "+14155550100",
    "job_title": "Senior Software Engineer",
    "job_level": "Senior",
    "department": "Engineering",
    "company_name": "Acme Corp",
    "company_domain": "acme.com",
    "company_size": "51-200",
    "employee_count": 120,
    "year_founded": 2015,
    "industry": "Software & SaaS",
    "sector": "Technology",
    "country": "US",
    "state": "California",
    "city": "San Francisco",
    "linkedin_url": "https://linkedin.com/in/sarahmitchell",
    "company_linkedin_url": "https://linkedin.com/company/acme-corp",
    "company_description": "Acme Corp builds enterprise automation tools...",
    "ai_score": 87
  },
  "meta": {
    "request_id": "req_5c4d3e2f1a0b9c8d",
    "timestamp": "2026-02-26T14: 32: 00.000Z",
    "lead_id": "c_7f3a2b9d1e8c5f4a",
    "enriched_at": "2026-02-26T14: 32: 00.000Z"
  },
  "error": null
}

POST/email/validateemail:validate

Validate one or up to 100 email addresses for deliverability. Results are cached for 24 hours. Use email for single validation or emails array for bulk.

Request Body

Name	Type	Required	Description
`email`	`string`	No	Single email address to validate
`emails`	`string[]`	No	Array of email addresses for bulk validation (max 100)

Single validation

curl -X POST "https://api.leadleap.net/api/v1/email/validate" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Single validation response

{
  "data": {
    "email": "[email protected]",
    "is_valid": true,
    "reason": null,
    "cached": false
  },
  "meta": {
    "request_id": "req_2b1a0c9d8e7f6a5b",
    "timestamp": "2026-02-26T14: 33: 00.000Z",
    "cached": false
  },
  "error": null
}

Bulk validation

curl -X POST "https://api.leadleap.net/api/v1/email/validate" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["[email protected]", "invalid-email", "[email protected]"]}'

Bulk validation response

{
  "data": [
    { "email": "[email protected]", "is_valid": true, "reason": null, "cached": false },
    { "email": "invalid-email", "is_valid": false, "reason": "invalid_format", "cached": false },
    { "email": "[email protected]", "is_valid": true, "reason": null, "cached": false }
  ],
  "meta": {
    "request_id": "req_7f6e5d4c3b2a1098",
    "timestamp": "2026-02-26T14: 33: 30.000Z",
    "total": 3,
    "valid": 2,
    "invalid": 1,
    "cached_count": 0
  },
  "error": null
}

GET/webhookswebhooks:read

List all active webhook subscriptions for your account. The signing secret is never returned after creation.

Example request

curl "https://api.leadleap.net/api/v1/webhooks" \
  -H "Authorization: Bearer ll_your_api_key"

Example response

{
  "data": [
    {
      "id": "wh_4a3b2c1d0e9f8a7b",
      "name": "CRM Sync",
      "url": "https://hooks.zapier.com/hooks/catch/abc123",
      "events": ["lead.unlocked", "lead.exported"],
      "is_active": true,
      "failure_count": 0,
      "last_triggered_at": "2026-02-25T10: 15: 00.000Z",
      "created_at": "2026-01-10T09: 00: 00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_1c2d3e4f5a6b7c8d",
    "timestamp": "2026-02-26T14: 34: 00.000Z",
    "total": 1
  },
  "error": null
}

POST/webhookswebhooks:manage

Create a new webhook subscription. The signing secret is returned only once in the response — store it immediately to verify signatures.

Request Body

Name	Type	Required	Description
`name`	`string`	Yes	Descriptive name for this webhook
`url`	`string`	Yes	HTTPS endpoint URL to receive events
`events`	`string[]`	Yes	Array of event types to subscribe to

Example request

curl -X POST "https://api.leadleap.net/api/v1/webhooks" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead Notifications",
    "url": "https://hooks.myapp.com/leadleap",
    "events": ["lead.unlocked", "lead.exported", "email.replied"]
  }'

Example response (201)

{
  "data": {
    "id": "wh_9e8f7a6b5c4d3e2f",
    "name": "Lead Notifications",
    "url": "https://hooks.myapp.com/leadleap",
    "events": ["lead.unlocked", "lead.exported", "email.replied"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2026-02-26T14: 35: 00.000Z"
  },
  "meta": {
    "request_id": "req_9a8b7c6d5e4f3a2b",
    "timestamp": "2026-02-26T14: 35: 00.000Z",
    "secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
    "warning": "Store the secret securely — it will not be shown again."
  },
  "error": null
}

Verifying webhook signatures

Each delivery includes an X-Webhook-Signature header with format sha256=<hmac>. Verify it using HMAC-SHA256 with your webhook secret.

400">"text-purple-400">import crypto 400">"text-purple-400">from 400">'crypto';

400">"text-purple-400">function verifySignature(body: string, signature: string, secret: string): boolean {
  400">"text-purple-400">const expected = 400">'sha256=' + crypto
    .createHmac(400">'sha256', secret)
    .update(body)
    .digest(400">'hex');
  400">"text-purple-400">return crypto.timingSafeEqual(
    Buffer.400">"text-purple-400">from(signature),
    Buffer.400">"text-purple-400">from(expected)
  );
}

DELETE/webhooks/{id}webhooks:manage

Soft-delete a webhook by setting it inactive. The webhook stops receiving events immediately.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	The webhook ID to delete

Example request

curl -X DELETE "https://api.leadleap.net/api/v1/webhooks/wh_9e8f7a6b5c4d3e2f" \
  -H "Authorization: Bearer ll_your_api_key"

Example response

{
  "data": {
    "id": "wh_9e8f7a6b5c4d3e2f",
    "deleted": true,
    "deleted_at": "2026-02-26T14: 36: 00.000Z"
  },
  "meta": {
    "request_id": "req_3d4e5f6a7b8c9d0e",
    "timestamp": "2026-02-26T14: 36: 00.000Z"
  },
  "error": null
}

GET/account/usageaccount:read

Retrieve plan details, credit usage, and period information for your account. Also accessible with the leads:read scope for convenience.

Example request

curl "https://api.leadleap.net/api/v1/account/usage" \
  -H "Authorization: Bearer ll_your_api_key"

Example response

{
  "data": {
    "plan": {
      "type": "scale",
      "price_monthly": 199,
      "has_api_access": true,
      "has_crm_integration": true,
      "max_webhooks": 50,
      "export_formats": ["csv", "json", "xlsx"]
    },
    "usage": {
      "leads_used": 1250,
      "leads_limit": 5000,
      "leads_remaining": 3750,
      "leads_usage_pct": 25,
      "emails_sent": 342,
      "emails_limit": 25000
    },
    "period": {
      "start": "2026-02-01T00: 00: 00.000Z",
      "end": "2026-03-01T00: 00: 00.000Z",
      "days_remaining": 3
    },
    "account": {
      "user_id": "usr_abc123",
      "full_name": "Alex Johnson",
      "company_name": "GrowthCo",
      "created_at": "2025-11-15T08: 00: 00.000Z"
    }
  },
  "meta": {
    "request_id": "req_6b7c8d9e0f1a2b3c",
    "timestamp": "2026-02-26T14: 37: 00.000Z"
  },
  "error": null
}

Error Codes

All errors follow the standard envelope format. Use the code field for programmatic handling, not the HTTP status alone.

HTTP Status	Code	Description
400	`BAD_REQUEST`	Request body or params are invalid or missing required fields
401	`UNAUTHORIZED`	API key is missing, invalid, or expired
402	`CREDITS_EXHAUSTED`	No lead credits remaining in the current billing period
403	`FORBIDDEN`	API key lacks the required scope for this endpoint
403	`PLAN_LIMIT`	Your plan does not support this feature or you have hit a plan limit
404	`NOT_FOUND`	The requested resource (lead, webhook, etc.) was not found
410	`GONE`	The resource exists but has been deleted
429	`RATE_LIMITED`	Per-key rate limit exceeded — check the Retry-After header
500	`INTERNAL_ERROR`	Unexpected server error — contact support if it persists

Webhook Events

All webhook payloads share the same envelope structure with an event, timestamp, data, and user_id.

Webhook payload structure

{
  "event": "lead.unlocked",
  "timestamp": "2026-02-26T14: 31: 00.000Z",
  "user_id": "usr_abc123",
  "data": {
    "lead_id": "c_7f3a2b9d1e8c5f4a",
    "company_name": "Acme Corp",
    "contact_name": "Sarah Mitchell"
  }
}

Event	Description
`lead.unlocked`	A lead was unlocked with credits
`lead.exported`	Leads were exported to CSV/JSON
`lead.enriched`	A lead was enriched via waterfall lookup
`sequence.started`	An email sequence was activated
`sequence.completed`	All contacts finished a sequence
`email.sent`	An outreach email was sent
`email.opened`	A recipient opened an email
`email.clicked`	A recipient clicked a link in an email
`email.replied`	A recipient replied to an email
`email.bounced`	An outreach email bounced
`contact.job_changed`	A contact changed jobs (detected via enrichment)
`crm_clean.completed`	A CRM cleaning job finished
`import.completed`	A CSV/data import finished
`enrichment.completed`	A bulk enrichment job finished

Need help?

Check the dashboard or reach out to our support team.

API Keys Dashboard Contact Support

REST API • v1

API Reference

Base URL

https://api.leadleap.net/api/v1

Protocol

HTTPS only

Format

JSON (UTF-8)

Versioning

Authentication

All API requests require authentication using a Bearer token in the Authorization header. API keys have the format ll_<64 hex chars>.

Example request

curl "https://api.leadleap.net/api/v1/leads?country=US&sector=Technology" \
  -H "Authorization: Bearer ll_your_api_key_here"

Getting an API key

Log in to your LeadLeap dashboard
Navigate to Settings → API Keys
Click Generate Key and select the required scopes
Copy the key immediately — it is only shown once

Go to API Keys

Security note: Never expose API keys in client-side code. Keys are SHA-256 hashed in our database and cannot be recovered if lost. API access requires the Scale plan or higher.

Rate Limiting

Each API key has a per-minute rate limit (default: 60 req/min). Rate limit information is returned in every response.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (on 429 response)

429 Too Many Requests

{
  "data": null,
  "meta": {
    "request_id": "req_4f3a9b2c1d8e7f6a",
    "timestamp": "2026-02-26T14: 30: 00.000Z"
  },
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. You are allowed 60 requests per minute.",
    "status": 429,
    "retry_after": 12
  }
}

Response Format

All responses use a consistent envelope structure with data, meta, and error fields.

Success (2xx)

{
  "data": { ... },
  "meta": {
    "request_id": "req_4f3a9b2c1d8e7f6a",
    "timestamp": "2026-02-26T14: 30: 00.000Z",
    "total": 1250,
    "page": 1,
    "per_page": 25
  },
  "error": null
}

Error (4xx / 5xx)

{
  "data": null,
  "meta": {
    "request_id": "req_9e8d7c6b5a4f3e2d",
    "timestamp": "2026-02-26T14: 30: 01.000Z"
  },
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key.",
    "status": 401
  }
}

Endpoints

GET/leadsleads:read

Search and filter the LeadLeap database of 30M+ B2B contacts. Results are paginated and contact details (email, phone, LinkedIn) are masked unless the lead has been unlocked.

Query Parameters

Name	Type	Required	Description
`type`	`string`	No	Lead type: 'business' (default) or 'consumer'
`country`	`string`	No	Comma-separated country names (e.g., US,Canada)
`sector`	`string`	No	Broad sector (e.g., Technology,Healthcare)
`industry`	`string`	No	Granular industry (~95 categories)
`company_size`	`string`	No	Company size bracket (e.g., 1-10,11-50)
`size_range`	`string`	No	Revenue size range
`department`	`string`	No	Department (e.g., Engineering,Sales)
`job_level`	`string`	No	Job level (e.g., C-Level,Director,Manager)
`state`	`string`	No	US state (e.g., California,Texas)
`year_founded_min`	`integer`	No	Minimum year founded (e.g., 2010)
`year_founded_max`	`integer`	No	Maximum year founded (e.g., 2023)
`employee_count_min`	`integer`	No	Minimum employee count
`employee_count_max`	`integer`	No	Maximum employee count
`page`	`integer`	No	Page number, 1-indexed (default: 1)
`per_page`	`integer`	No	Results per page, max 100 (default: 25)

Example request

curl "https://api.leadleap.net/api/v1/leads?type=business&country=US&sector=Technology&department=Engineering&per_page=5" \
  -H "Authorization: Bearer ll_your_api_key"

Example response

{
  "data": [
    {
      "id": "c_7f3a2b9d1e8c5f4a",
      "company_name": "Acme Corp",
      "company_domain": "acme.com",
      "contact_name": "Sarah Mitchell",
      "first_name": "Sarah",
      "last_name": "Mitchell",
      "email": "sa***@acme.com",
      "phone": "+1415****78",
      "job_title": "Senior Software Engineer",
      "department": "Engineering",
      "industry": "Software & SaaS",
      "company_size": "51-200",
      "employee_count": 120,
      "country": "US",
      "state": "California",
      "city": "San Francisco",
      "ai_score": 87,
      "is_unlocked": false
    }
  ],
  "meta": {
    "request_id": "req_4f3a9b2c1d8e7f6a",
    "timestamp": "2026-02-26T14: 30: 00.000Z",
    "total": 142500,
    "page": 1,
    "per_page": 5,
    "total_pages": 28500
  },
  "error": null
}

POST/leads/unlockleads:unlock

Unlock a lead to reveal full contact details (email, phone, LinkedIn URL). Costs 1 credit. If the lead was previously unlocked, cached data is returned at no charge.

Request Body

Name	Type	Required	Description
`lead_id`	`string`	Yes	The lead ID from a search result

Example request

curl -X POST "https://api.leadleap.net/api/v1/leads/unlock" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_id": "c_7f3a2b9d1e8c5f4a"}'

Example response

{
  "data": {
    "id": "c_7f3a2b9d1e8c5f4a",
    "full_name": "Sarah Mitchell",
    "first_name": "Sarah",
    "last_name": "Mitchell",
    "email_primary": "[email protected]",
    "email_second": "[email protected]",
    "phone": "+14155551278",
    "company_phone": "+14155550100",
    "job_title": "Senior Software Engineer",
    "company_name": "Acme Corp",
    "company_domain": "acme.com",
    "linkedin_url": "https://linkedin.com/in/sarahmitchell",
    "industry": "Software & SaaS",
    "country": "US",
    "state": "California",
    "city": "San Francisco",
    "ai_score": 87
  },
  "meta": {
    "request_id": "req_8a7b6c5d4e3f2g1h",
    "timestamp": "2026-02-26T14: 31: 00.000Z",
    "credits_used": 1,
    "credits_remaining": 249,
    "cached": false
  },
  "error": null
}

POST/leads/exportleads:export

Export up to 500 leads as a CSV or JSON file download. Unlocked leads are included at no additional cost. Locked leads consume 1 credit each. Returns a file attachment with Content-Disposition.

Request Body

Name	Type	Required	Description
`lead_ids`	`string[]`	Yes	Array of lead IDs to export (max 500)
`format`	`string`	No	Export format: 'csv' (default) or 'json'

Example request

curl -X POST "https://api.leadleap.net/api/v1/leads/export" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_ids": ["c_7f3a2b9d", "c_1a2b3c4d", "c_5e6f7a8b"], "format": "csv"}' \
  --output leads-export.csv

Response headers includeX-Total-Leads,X-New-Unlocks, andX-Cached-Unlocks. The response body is the raw file content.

POST/leads/enrichleads:enrich

Retrieve the full enriched dataset for a contact from the MCP gateway. Returns all available fields including company description, LinkedIn IDs, and AI scores. Does not consume credits.

Request Body

Name	Type	Required	Description
`lead_id`	`string`	Yes	The lead ID to enrich

Example request

curl -X POST "https://api.leadleap.net/api/v1/leads/enrich" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_id": "c_7f3a2b9d1e8c5f4a"}'

Example response

{
  "data": {
    "id": "c_7f3a2b9d1e8c5f4a",
    "full_name": "Sarah Mitchell",
    "first_name": "Sarah",
    "middle_name": null,
    "last_name": "Mitchell",
    "email_primary": "[email protected]",
    "email_second": null,
    "phone": "+14155551278",
    "company_phone": "+14155550100",
    "job_title": "Senior Software Engineer",
    "job_level": "Senior",
    "department": "Engineering",
    "company_name": "Acme Corp",
    "company_domain": "acme.com",
    "company_size": "51-200",
    "employee_count": 120,
    "year_founded": 2015,
    "industry": "Software & SaaS",
    "sector": "Technology",
    "country": "US",
    "state": "California",
    "city": "San Francisco",
    "linkedin_url": "https://linkedin.com/in/sarahmitchell",
    "company_linkedin_url": "https://linkedin.com/company/acme-corp",
    "company_description": "Acme Corp builds enterprise automation tools...",
    "ai_score": 87
  },
  "meta": {
    "request_id": "req_5c4d3e2f1a0b9c8d",
    "timestamp": "2026-02-26T14: 32: 00.000Z",
    "lead_id": "c_7f3a2b9d1e8c5f4a",
    "enriched_at": "2026-02-26T14: 32: 00.000Z"
  },
  "error": null
}

POST/email/validateemail:validate

Validate one or up to 100 email addresses for deliverability. Results are cached for 24 hours. Use email for single validation or emails array for bulk.

Request Body

Name	Type	Required	Description
`email`	`string`	No	Single email address to validate
`emails`	`string[]`	No	Array of email addresses for bulk validation (max 100)

Single validation

curl -X POST "https://api.leadleap.net/api/v1/email/validate" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Single validation response

{
  "data": {
    "email": "[email protected]",
    "is_valid": true,
    "reason": null,
    "cached": false
  },
  "meta": {
    "request_id": "req_2b1a0c9d8e7f6a5b",
    "timestamp": "2026-02-26T14: 33: 00.000Z",
    "cached": false
  },
  "error": null
}

Bulk validation

curl -X POST "https://api.leadleap.net/api/v1/email/validate" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["[email protected]", "invalid-email", "[email protected]"]}'

Bulk validation response

{
  "data": [
    { "email": "[email protected]", "is_valid": true, "reason": null, "cached": false },
    { "email": "invalid-email", "is_valid": false, "reason": "invalid_format", "cached": false },
    { "email": "[email protected]", "is_valid": true, "reason": null, "cached": false }
  ],
  "meta": {
    "request_id": "req_7f6e5d4c3b2a1098",
    "timestamp": "2026-02-26T14: 33: 30.000Z",
    "total": 3,
    "valid": 2,
    "invalid": 1,
    "cached_count": 0
  },
  "error": null
}

GET/webhookswebhooks:read

List all active webhook subscriptions for your account. The signing secret is never returned after creation.

Example request

curl "https://api.leadleap.net/api/v1/webhooks" \
  -H "Authorization: Bearer ll_your_api_key"

Example response

{
  "data": [
    {
      "id": "wh_4a3b2c1d0e9f8a7b",
      "name": "CRM Sync",
      "url": "https://hooks.zapier.com/hooks/catch/abc123",
      "events": ["lead.unlocked", "lead.exported"],
      "is_active": true,
      "failure_count": 0,
      "last_triggered_at": "2026-02-25T10: 15: 00.000Z",
      "created_at": "2026-01-10T09: 00: 00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_1c2d3e4f5a6b7c8d",
    "timestamp": "2026-02-26T14: 34: 00.000Z",
    "total": 1
  },
  "error": null
}

POST/webhookswebhooks:manage

Create a new webhook subscription. The signing secret is returned only once in the response — store it immediately to verify signatures.

Request Body

Name	Type	Required	Description
`name`	`string`	Yes	Descriptive name for this webhook
`url`	`string`	Yes	HTTPS endpoint URL to receive events
`events`	`string[]`	Yes	Array of event types to subscribe to

Example request

curl -X POST "https://api.leadleap.net/api/v1/webhooks" \
  -H "Authorization: Bearer ll_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead Notifications",
    "url": "https://hooks.myapp.com/leadleap",
    "events": ["lead.unlocked", "lead.exported", "email.replied"]
  }'

Example response (201)

{
  "data": {
    "id": "wh_9e8f7a6b5c4d3e2f",
    "name": "Lead Notifications",
    "url": "https://hooks.myapp.com/leadleap",
    "events": ["lead.unlocked", "lead.exported", "email.replied"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2026-02-26T14: 35: 00.000Z"
  },
  "meta": {
    "request_id": "req_9a8b7c6d5e4f3a2b",
    "timestamp": "2026-02-26T14: 35: 00.000Z",
    "secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
    "warning": "Store the secret securely — it will not be shown again."
  },
  "error": null
}

Verifying webhook signatures

Each delivery includes an X-Webhook-Signature header with format sha256=<hmac>. Verify it using HMAC-SHA256 with your webhook secret.

400">"text-purple-400">import crypto 400">"text-purple-400">from 400">'crypto';

400">"text-purple-400">function verifySignature(body: string, signature: string, secret: string): boolean {
  400">"text-purple-400">const expected = 400">'sha256=' + crypto
    .createHmac(400">'sha256', secret)
    .update(body)
    .digest(400">'hex');
  400">"text-purple-400">return crypto.timingSafeEqual(
    Buffer.400">"text-purple-400">from(signature),
    Buffer.400">"text-purple-400">from(expected)
  );
}

DELETE/webhooks/{id}webhooks:manage

Soft-delete a webhook by setting it inactive. The webhook stops receiving events immediately.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	The webhook ID to delete

Example request

curl -X DELETE "https://api.leadleap.net/api/v1/webhooks/wh_9e8f7a6b5c4d3e2f" \
  -H "Authorization: Bearer ll_your_api_key"

Example response

{
  "data": {
    "id": "wh_9e8f7a6b5c4d3e2f",
    "deleted": true,
    "deleted_at": "2026-02-26T14: 36: 00.000Z"
  },
  "meta": {
    "request_id": "req_3d4e5f6a7b8c9d0e",
    "timestamp": "2026-02-26T14: 36: 00.000Z"
  },
  "error": null
}

GET/account/usageaccount:read

Retrieve plan details, credit usage, and period information for your account. Also accessible with the leads:read scope for convenience.

Example request

curl "https://api.leadleap.net/api/v1/account/usage" \
  -H "Authorization: Bearer ll_your_api_key"

Example response

{
  "data": {
    "plan": {
      "type": "scale",
      "price_monthly": 199,
      "has_api_access": true,
      "has_crm_integration": true,
      "max_webhooks": 50,
      "export_formats": ["csv", "json", "xlsx"]
    },
    "usage": {
      "leads_used": 1250,
      "leads_limit": 5000,
      "leads_remaining": 3750,
      "leads_usage_pct": 25,
      "emails_sent": 342,
      "emails_limit": 25000
    },
    "period": {
      "start": "2026-02-01T00: 00: 00.000Z",
      "end": "2026-03-01T00: 00: 00.000Z",
      "days_remaining": 3
    },
    "account": {
      "user_id": "usr_abc123",
      "full_name": "Alex Johnson",
      "company_name": "GrowthCo",
      "created_at": "2025-11-15T08: 00: 00.000Z"
    }
  },
  "meta": {
    "request_id": "req_6b7c8d9e0f1a2b3c",
    "timestamp": "2026-02-26T14: 37: 00.000Z"
  },
  "error": null
}

Error Codes

All errors follow the standard envelope format. Use the code field for programmatic handling, not the HTTP status alone.

HTTP Status	Code	Description
400	`BAD_REQUEST`	Request body or params are invalid or missing required fields
401	`UNAUTHORIZED`	API key is missing, invalid, or expired
402	`CREDITS_EXHAUSTED`	No lead credits remaining in the current billing period
403	`FORBIDDEN`	API key lacks the required scope for this endpoint
403	`PLAN_LIMIT`	Your plan does not support this feature or you have hit a plan limit
404	`NOT_FOUND`	The requested resource (lead, webhook, etc.) was not found
410	`GONE`	The resource exists but has been deleted
429	`RATE_LIMITED`	Per-key rate limit exceeded — check the Retry-After header
500	`INTERNAL_ERROR`	Unexpected server error — contact support if it persists

Webhook Events

All webhook payloads share the same envelope structure with an event, timestamp, data, and user_id.

Webhook payload structure

{
  "event": "lead.unlocked",
  "timestamp": "2026-02-26T14: 31: 00.000Z",
  "user_id": "usr_abc123",
  "data": {
    "lead_id": "c_7f3a2b9d1e8c5f4a",
    "company_name": "Acme Corp",
    "contact_name": "Sarah Mitchell"
  }
}

Event	Description
`lead.unlocked`	A lead was unlocked with credits
`lead.exported`	Leads were exported to CSV/JSON
`lead.enriched`	A lead was enriched via waterfall lookup
`sequence.started`	An email sequence was activated
`sequence.completed`	All contacts finished a sequence
`email.sent`	An outreach email was sent
`email.opened`	A recipient opened an email
`email.clicked`	A recipient clicked a link in an email
`email.replied`	A recipient replied to an email
`email.bounced`	An outreach email bounced
`contact.job_changed`	A contact changed jobs (detected via enrichment)
`crm_clean.completed`	A CRM cleaning job finished
`import.completed`	A CSV/data import finished
`enrichment.completed`	A bulk enrichment job finished

Need help?

Check the dashboard or reach out to our support team.

API Keys Dashboard Contact Support