Developer Platform · REST API v1.0 Reference

How do you integrate Enrich B2B lead enrichment and scraping via REST API v1?

The Enrich REST API v1 enables developers to programmatically query SMTP-verified B2B leads, filter website-less or 80%+ confidence prospects, submit custom batch orders, and trigger asynchronous scraping workflows using standard HTTP Bearer authentication and JSON webhooks.

Generate API Keys
API-01

Bearer Token Authentication

Standard HTTP Authorization header with isolated workspace tenant security.

API-02

Granular Permission Scopes

Provision keys with explicit read, write, or delete privileges.

API-03

Specialized Query Segments

Dedicated routes for /nowebsite, /confidence80, and /careerleads.

API-04

Asynchronous Webhook Callbacks

Non-blocking extraction tasks with signed JSON POST completion payloads.

Quickstart Implementation

How do you authenticate and query the REST API v1?

All V1 endpoints authenticate via standard HTTP Bearer tokens and return UTF-8 JSON payloads. Keys can be scoped to read, write, or delete inside your workspace settings.

Required Request Header
Authorization: Bearer YOUR_API_KEY

Base URL: https://enrich.leadske.com/api/v1

# 1. Query SMTP-Verified Leads (80%+ Confidence)
curl -X GET "https://enrich.leadske.com/api/v1/leads?page=1&limit=25&verified=true&minConfidence=80" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Submit a Custom Lead Extraction Batch Order
curl -X POST "https://enrich.leadske.com/api/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "niche": "Commercial Roofing Contractors",
    "location": "Miami, FL",
    "leadCount": 1000,
    "sources": ["google_maps", "website_crawler", "google_search"],
    "attributes": {
      "verifiedEmail": true,
      "directPhone": true,
      "decisionMakerRole": true,
      "outreachCopy": true
    },
    "customer": {
      "fullName": "Jane Doe",
      "workEmail": "jane@company.com",
      "companyName": "Acme Revenue"
    }
  }'

# 3. Trigger an Asynchronous Prospecting & Enrichment Job
curl -X POST "https://enrich.leadske.com/api/v1/automations/agentic" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Extract HVAC contractors in Dallas TX, verify work emails, and draft custom opening lines.",
    "callbackUrl": "https://your-domain.com/webhooks/enrich"
  }'
REST API v1 Specification

Which endpoints are available in the Enrich API?

Explore all 11 production endpoints below, including parameter schemas, required permission scopes, and sample JSON responses.

GET/api/v1/leads
Scope:read

List & Search Enriched Leads

Fetches a paginated, filterable collection of enriched B2B leads associated with your workspace API key.

Execution behavior: Returns an array of normalized lead objects sorted newest first, isolated to your authenticated workspace account.

Request Parameters

ParameterTypeRequiredDescription
pagenumberOptionalPage number for pagination (default: 1).
limitnumberOptionalRecords per page (default: 100).
sourcestringOptionalFilter by origin pipeline (e.g., 'google_maps', 'yellow_pages').
verifiedbooleanOptionalSet to true to return only SMTP-verified email rows.
minConfidencenumberOptionalFilter leads with confidence score >= threshold (e.g., 80).
Response Example (200 / 201 JSON)
{
  "success": true,
  "leads": [
    {
      "_id": "66c3a1b8e4b0123456789abc",
      "name": "Marco Rodriguez",
      "email": "m.rodriguez@apexroofingmia.com",
      "company": "Apex Commercial Roofing",
      "phone": "+13055550192",
      "website": "https://apexroofingmia.com",
      "confidence": 96,
      "verified": true,
      "source": "google_maps"
    }
  ],
  "pagination": { "page": 1, "limit": 100, "total": 450, "pages": 5 }
}
POST/api/v1/leads
Scope:write

Create New Lead Record

Inserts a single enriched lead record into your workspace database.

Execution behavior: Validates the payload and associates the created record with your authenticated user ID. Returns HTTP 201 Created.

Request Parameters

ParameterTypeRequiredDescription
namestringOptionalDecision-maker full name.
emailstringOptionalWork email address.
phonestringOptionalE.164 phone number.
companystringOptionalBusiness or organization name.
websitestringOptionalCorporate domain URL.
locationstringOptionalCity, state, or country.
titlestringOptionalExecutive role or job title.
Request Body (JSON)
{
  "name": "Elena Rostova",
  "email": "elena@biscayneexteriors.com",
  "company": "Biscayne Exterior Systems",
  "phone": "+13055550148",
  "website": "https://biscayneexteriors.com",
  "title": "Operations Director",
  "source": "api_import"
}
Response Example (200 / 201 JSON)
{
  "success": true,
  "lead": {
    "_id": "66c3a9f0e4b0987654321def",
    "name": "Elena Rostova",
    "email": "elena@biscayneexteriors.com",
    "company": "Biscayne Exterior Systems",
    "source": "api_import"
  }
}
GET/api/v1/leads/:id
Scope:read

Fetch Single Lead by ID

Retrieves complete 24-column metadata for a single lead by its MongoDB ObjectId.

Execution behavior: Enforces tenant isolation and returns HTTP 404 if the record does not exist.

Request Parameters

ParameterTypeRequiredDescription
idstringRequiredUnique MongoDB ObjectId of the lead.
Response Example (200 / 201 JSON)
{
  "success": true,
  "lead": {
    "_id": "66c3a1b8e4b0123456789abc",
    "name": "Marco Rodriguez",
    "email": "m.rodriguez@apexroofingmia.com",
    "company": "Apex Commercial Roofing",
    "confidence": 96,
    "verified": true
  }
}
PUT/api/v1/leads/:id
Scope:write

Update Lead Attributes by ID

Updates verification status, confidence rating, or custom notes on an existing lead.

Execution behavior: Applies partial JSON updates to the specified lead document. Requires write scope.

Request Parameters

ParameterTypeRequiredDescription
idstringRequiredUnique MongoDB ObjectId of the lead.
Request Body (JSON)
{
  "verified": true,
  "confidence": 98,
  "notes": "Synced to HubSpot sequence Q4."
}
Response Example (200 / 201 JSON)
{
  "success": true,
  "lead": {
    "_id": "66c3a1b8e4b0123456789abc",
    "verified": true,
    "confidence": 98,
    "notes": "Synced to HubSpot sequence Q4."
  }
}
DELETE/api/v1/leads/:id
Scope:delete

Delete Lead Record by ID

Permanently removes a lead document from your workspace collection.

Execution behavior: Requires explicit delete permission scope on the Bearer token.

Request Parameters

ParameterTypeRequiredDescription
idstringRequiredUnique MongoDB ObjectId of the lead.
Response Example (200 / 201 JSON)
{
  "success": true,
  "message": "Lead deleted successfully"
}
POST/api/orders
Scope:public / write

Submit Custom Lead Extraction Order

Calculates itemized per-lead pricing with volume discounts and queues a new extraction order in MongoDB.

Execution behavior: Powers the 3-step Hero Order Wizard and programmatic batch orders. Automatically computes volume discounts (5% to 30%) and returns an orderId (e.g., ENR-XXXX-XXXXX).

Request Parameters

ParameterTypeRequiredDescription
nichestringRequiredTarget industry or business category.
locationstringRequiredTarget city, state, or country.
leadCountnumberRequiredRequested number of verified leads (50 – 100,000).
sourcesstring[]OptionalSelected scraper pipelines (e.g., ['google_maps', 'website_crawler']).
attributesobjectOptionalBoolean flags for verifiedEmail, directPhone, decisionMakerRole, outreachCopy.
customerobjectRequiredCustomer object containing fullName, workEmail, phone, companyName, notes.
Request Body (JSON)
{
  "niche": "Roofing Contractors",
  "location": "Miami, FL",
  "leadCount": 1000,
  "sources": ["google_maps", "website_crawler", "google_search"],
  "attributes": {
    "verifiedEmail": true,
    "directPhone": true,
    "decisionMakerRole": true,
    "outreachCopy": false
  },
  "customer": {
    "fullName": "Jane Doe",
    "workEmail": "jane@company.com",
    "companyName": "Acme Outbound"
  }
}
Response Example (200 / 201 JSON)
{
  "success": true,
  "orderId": "ENR-9K2M-7X4PQ",
  "message": "Your lead enrichment order has been submitted."
}
GET/api/v1/leads/nowebsite
Scope:read

Query Website-Less Local Businesses

Retrieves active local businesses that have verified phone numbers and addresses on Google Maps but no website domain.

Execution behavior: Built for web design agencies, SEO consultants, and digital marketing teams prospecting businesses that need a website.

Request Parameters

ParameterTypeRequiredDescription
pagenumberOptionalPage number (default: 1).
limitnumberOptionalRecords per page (default: 100).
Response Example (200 / 201 JSON)
{
  "success": true,
  "leads": [
    {
      "_id": "66c3b012e4b0112233445566",
      "company": "Metro Mechanical Services",
      "phone": "+12145550188",
      "website": null,
      "location": "Dallas, TX"
    }
  ],
  "pagination": { "page": 1, "limit": 100, "total": 120, "pages": 2 }
}
GET/api/v1/leads/confidence80
Scope:read

Query High-Confidence Verified Leads (80%+)

Returns only leads that have passed SMTP verification with an enrichment confidence score of 80% or higher.

Execution behavior: Protects cold email sender domains by filtering out unverified catch-all or low-confidence records.

Request Parameters

ParameterTypeRequiredDescription
pagenumberOptionalPage number (default: 1).
limitnumberOptionalRecords per page (default: 100).
minConfidencenumberOptionalCustom minimum threshold (default: 80).
Response Example (200 / 201 JSON)
{
  "success": true,
  "leads": [
    {
      "_id": "66c3c555e4b0998877665544",
      "name": "David Kim",
      "company": "Apex Logistics",
      "email": "dkim@apexlogistics.com",
      "confidence": 95,
      "verified": true
    }
  ]
}
GET/api/v1/careerleads
Scope:read

Query Active Hiring & Job-Board Intent Leads

Fetches companies actively advertising open roles across major job boards (Indeed, Google Jobs, LinkedIn).

Execution behavior: Ideal for recruiting agencies, staffing firms, and B2B SaaS teams targeting companies with active hiring budgets.

Request Parameters

ParameterTypeRequiredDescription
pagenumberOptionalPage number (default: 1).
limitnumberOptionalRecords per page (default: 100).
Response Example (200 / 201 JSON)
{
  "success": true,
  "leads": [
    {
      "_id": "66c3d888e4b0776655443322",
      "company": "Horizon Tech",
      "email": "careers@horizontech.io",
      "website": "https://horizontech.io",
      "notes": "Hiring: Senior Fullstack Engineer | Platform: Indeed"
    }
  ]
}
POST/api/v1/automations/agentic
Scope:write

Schedule Automated Extraction & Enrichment Task

Triggers an asynchronous background extraction, website crawl, and outreach generation task with webhook delivery.

Execution behavior: Parses your natural-language extraction prompt, executes non-blocking background scraping, and POSTs the enriched dataset to your callbackUrl.

Request Parameters

ParameterTypeRequiredDescription
promptstringRequiredExtraction instruction specifying target niche, location, and enrichment goals.
callbackUrlstringOptionalHTTPS endpoint to receive the completed JSON webhook payload.
webhookMetadataobjectOptionalCustom key-value metadata echoed back in the webhook delivery.
Request Body (JSON)
{
  "prompt": "Extract commercial HVAC contractors in Dallas TX, verify owner emails, and generate opening lines.",
  "callbackUrl": "https://your-app.com/api/webhooks/enrich-complete",
  "webhookMetadata": { "campaignId": "cmp_dallas_hvac" }
}
Response Example (200 / 201 JSON)
{
  "success": true,
  "message": "Workflow scheduled successfully",
  "taskId": "66c3e999e4b04433221100aa",
  "status": "parsing"
}
GET/api/v1/automations/agentic/:id
Scope:read

Poll Automated Task Status & Results

Retrieves live execution state, step logs, enriched lead rows, and webhook delivery status for a scheduled task.

Execution behavior: Returns status ('parsing', 'running', 'completed', 'failed') along with the full results array once finished.

Request Parameters

ParameterTypeRequiredDescription
idstringRequiredTask ID returned when scheduling the workflow.
Response Example (200 / 201 JSON)
{
  "success": true,
  "task": {
    "id": "66c3e999e4b04433221100aa",
    "status": "completed",
    "leadsCount": 42,
    "webhookStatus": "delivered"
  },
  "results": {
    "leads": [
      { "company": "SunBelt Mechanical", "email": "owner@sunbeltmech.com" }
    ]
  }
}
Standardized Error Handling

What HTTP status codes does the Enrich API return?

All Enrich API routes use conventional HTTP status codes paired with machine-readable JSON { "success": false, "error": "..." } bodies for deterministic retry logic.

HTTP CodeStatus LabelResolution & Cause
200 / 201OK / CreatedRequest succeeded and returned the requested lead array, order ID, or task confirmation.
400Bad RequestMissing required parameters (e.g., niche, workEmail, or prompt) or malformed JSON payload.
401UnauthorizedMissing, expired, or invalid Bearer API token in the Authorization header.
403ForbiddenAuthenticated API key lacks the required permission scope (read, write, or delete).
404Not FoundTarget lead ObjectId or task ID does not exist or belongs to another workspace.
429Too Many RequestsRate limit exceeded. Standard workspace limit is 100 requests per minute.
Enterprise API & Custom Rate Limits

Building a high-volume integration or custom webhook pipeline?

Speak with our API engineering team for higher per-minute rate limits, dedicated scraper concurrency, or custom JSON schemas.