Developer Platform API

List & Search Leads

Fetches a paginated, filterable collection of enriched leads associated with your API key. Supports multi-parameter filtering by source, verification status, and confidence score thresholds.

How it works: Returns array of lead objects sorted by newest first. Includes full pagination details (page, limit, total count, total pages). Automatically isolated to your user account.

Parameters:

{
  "success": true,
  "leads": [
    {
      "_id": "66c3a1b8e4b0123456789abc",
      "name": "Alex Mercer",
      "email": "alex@nexus.co.ke",
      "company": "Nexus Solutions",
      "phone": "+254712345678",
      "website": "https://nexus.co.ke",
      "confidence": 92,
      "verified": true,
      "source": "google_maps",
      "createdAt": "2026-08-20T18:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 450,
    "pages": 5
  }
}

Create New Lead

Inserts a new enriched lead record into your CRM database.

How it works: Validates request payload and associates the newly created lead directly with your authenticated API user ID. Returns HTTP status 201 Created on success.

Parameters:

Request Body (JSON):

{
  "name": "Sarah Connor",
  "email": "sarah@cyberdyne.com",
  "company": "Cyberdyne Systems",
  "phone": "+14155550199",
  "website": "https://cyberdyne.com",
  "title": "Head of Operations",
  "source": "api_import"
}

{
  "success": true,
  "lead": {
    "_id": "66c3a9f0e4b0987654321def",
    "userId": "usr_9988776655",
    "name": "Sarah Connor",
    "email": "sarah@cyberdyne.com",
    "company": "Cyberdyne Systems",
    "phone": "+14155550199",
    "website": "https://cyberdyne.com",
    "title": "Head of Operations",
    "source": "api_import",
    "createdAt": "2026-08-20T19:00:00.000Z"
  }
}

Fetch Lead Details by ID

Retrieves complete details of a single lead by its unique database ID.

How it works: Ensures security by enforcing that the target lead belongs to the authenticated user ID. Returns HTTP 404 if the lead does not exist or belongs to another user.

Parameters:

{
  "success": true,
  "lead": {
    "_id": "66c3a1b8e4b0123456789abc",
    "name": "Alex Mercer",
    "email": "alex@nexus.co.ke",
    "company": "Nexus Solutions",
    "phone": "+254712345678",
    "website": "https://nexus.co.ke",
    "confidence": 92,
    "verified": true,
    "source": "google_maps"
  }
}

Update Lead by ID

Updates specific fields on an existing lead record.

How it works: Applies partial or full field updates to the lead record. Requires write permission scope on your API key.

Parameters:

Request Body (JSON):

{
  "verified": true,
  "confidence": 98,
  "notes": "Contacted via WhatsApp, interested in enterprise plan."
}

{
  "success": true,
  "lead": {
    "_id": "66c3a1b8e4b0123456789abc",
    "name": "Alex Mercer",
    "verified": true,
    "confidence": 98,
    "notes": "Contacted via WhatsApp, interested in enterprise plan."
  }
}

Delete Lead by ID

Permanently removes a lead record from your database.

How it works: Requires an API key generated with the explicit 'delete' permission scope. Deletions are immediate and unrecoverable.

Parameters:

{
  "success": true,
  "message": "Lead deleted successfully"
}

Get Unbuilt / Website-Less Leads

Retrieves leads that do not currently have a website domain (where domain is null, empty string, or missing).

How it works: Specifically designed for web design agencies, SEO freelancers, and digital growth agencies seeking prospects who need a modern web presence. Supports pagination.

Parameters:

{
  "success": true,
  "leads": [
    {
      "_id": "66c3b012e4b0112233445566",
      "company": "Kamburu Bakery",
      "email": "info@kamburubakery.co.ke",
      "phone": "+254700112233",
      "website": null,
      "location": "Nairobi, Kenya"
    }
  ],
  "pagination": { "page": 1, "limit": 100, "total": 120, "pages": 2 }
}

Get High-Confidence Leads (80%+)

Queries high-grade leads with data enrichment confidence rating >= 80%.

How it works: Filters out unverified or low-confidence contact entries to protect cold email sender domain reputation and maximize campaign deliverability.

Parameters:

{
  "success": true,
  "leads": [
    {
      "_id": "66c3c555e4b0998877665544",
      "name": "David Kim",
      "company": "Apex Logistics",
      "email": "dkim@apexlogistics.com",
      "confidence": 95,
      "verified": true
    }
  ],
  "pagination": { "page": 1, "limit": 100, "total": 310, "pages": 4 }
}

Get Job Board / Hiring Career Leads

Fetches leads extracted from active hiring campaigns across major job platforms (e.g. Indeed, LinkedIn Jobs).

How it works: Provides companies actively spending on hiring talent. Formats response with normalized company info, contact numbers, emails, and notes indicating advertised job roles, locations, and source platforms.

Parameters:

{
  "success": true,
  "leads": [
    {
      "_id": "66c3d888e4b0776655443322",
      "name": "Horizon Tech",
      "company": "Horizon Tech",
      "email": "careers@horizontech.io",
      "phone": "+254722334455",
      "website": "https://horizontech.io",
      "notes": "Hiring for: Senior Fullstack Engineer | Location: Nairobi | Platform: Indeed",
      "createdAt": "2026-08-20T17:45:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 100, "total": 85, "pages": 1 }
}

Schedule AI Agentic Prospecting Task

Triggers an autonomous AI background agent powered by DeepSeek AI to execute end-to-end prospecting workflows.

How it works: Parses your plain-text prompt instruction (e.g. 'Scrape software firms in Westlands, enrich owner emails, draft customized cold emails'), initializes an Agentic Task, runs non-blocking background execution, and posts final outputs to your specified webhook callbackUrl upon completion.

Parameters:

Request Body (JSON):

{
  "prompt": "Find tech startups hiring sales reps in Nairobi, enrich contact emails, and generate personalized cold email outreach.",
  "callbackUrl": "https://your-app.com/api/webhooks/agentic-result",
  "webhookMetadata": { "campaignId": "cmp_2026_q3" }
}

{
  "success": true,
  "message": "Agentic workflow scheduled successfully",
  "taskId": "66c3e999e4b04433221100aa",
  "status": "parsing"
}

Get AI Agentic Task Status & Results

Polls execution status, real-time logs, metrics, enriched leads, and generated content for an AI Agentic Task.

How it works: Returns live execution state ('parsing', 'running', 'completed', 'failed'), real-time step logs, metrics (leadsCount, emailsSent, smsSent), webhook delivery status, and full enriched output payloads once completed.

Parameters:

{
  "success": true,
  "task": {
    "id": "66c3e999e4b04433221100aa",
    "prompt": "Find tech startups hiring sales reps in Nairobi...",
    "status": "completed",
    "leadsCount": 15,
    "emailsSent": 0,
    "smsSent": 0,
    "logs": [
      "Initiated Agentic Mode workflow via Public API.",
      "Analyzing assignment prompt with DeepSeek AI...",
      "Scraping targeted business directory...",
      "Enrichment completed successfully."
    ],
    "webhookStatus": "delivered",
    "createdAt": "2026-08-20T19:30:00.000Z"
  },
  "results": {
    "leads": [
      { "_id": "66c3f111...", "company": "CloudKaya", "email": "founder@cloudkaya.co.ke" }
    ],
    "generatedContent": [
      { "leadId": "66c3f111...", "subject": "Growth Partnership", "body": "Hi CloudKaya team..." }
    ]
  }
}