API Documentation & Code Examples | Autonomous Leads

Complete API documentation for Autonomous Leads with code examples in curl, Node.js, PHP, and Python. HMAC-signed webhooks, rate limits, and background processing.

Developer-First API

Built for developers, designed for scale

RESTful Design

Clean, intuitive API endpoints

HMAC Security

Signed webhooks & authentication

Background Processing

Async jobs with real-time updates

Available SDKs

Node.js

Python

PHP

Ruby

Rate Limits

Standard endpoints:100/min

Job creation:10/min

Enterprise:Higher limits

Get your API key

RESTful API with comprehensive documentation

Our API is designed for developers, with clear documentation, code examples, and SDKs for all major languages.

RESTful Design

Clean, intuitive API design following REST principles with comprehensive HTTP status codes.

HMAC Security

All webhook deliveries are signed with HMAC-SHA256 for authenticity and security.

Background Processing

Research jobs run asynchronously with real-time status updates and progress tracking.

Comprehensive Docs

Detailed documentation with code examples in multiple languages and interactive API explorer.

Core API endpoints

Everything you need to integrate knockd with your application.

POST

/v1/jobs

Create a new research job with idempotency support. Jobs run in the background and can be monitored via webhooks.

Request Body

JSON

{
  "prompt": "Find enterprise SaaS companies in Toronto with 100+ employees",
  "parameters": {
    "depth": "deep",
    "sources": ["LinkedIn", "Crunchbase", "Company Websites"],
    "filters": {
      "industry": ["Software", "Technology", "SaaS"],
      "role": ["CTO", "VP Engineering", "Head of Product"],
      "geography": ["Toronto", "GTA"],
      "company_size": ["100-500", "500-1000", "1000+"]
    }
  },
  "webhook_url": "https://your-app.com/webhooks/knockd",
  "idempotency_key": "unique-key-123"
}

Response

JSON

{
  "id": "job_123456789",
  "status": "queued",
  "created_at": "2025-01-15T10:30:00Z",
  "estimated_completion": "2025-01-15T10:35:00Z",
  "webhook_url": "https://your-app.com/webhooks/knockd"
}

GET

/v1/jobs/{id}

Get the current status and progress of a research job.

Response

JSON

{
  "id": "job_123456789",
  "status": "completed",
  "progress": 100,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:35:00Z",
  "prospects_found": 247,
  "prospects_accepted": 189,
  "duplicates_removed": 58
}

Status Values

queued - Job is queued for processing
running - Job is currently running
completed - Job completed successfully
failed - Job failed with error

GET

/v1/jobs/{id}/results

Retrieve the results of a completed job with cursor-based pagination.

Query Parameters

cursor - Pagination cursor
limit - Number of results (max 100)

Response

JSON

{
  "data": [
    {
      "id": "prospect_123",
      "name": "Sarah Johnson",
      "company": "TechCorp Inc.",
      "title": "Director of IT",
      "email": "sarah.johnson@techcorp.com",
      "phone": "+1 (555) 123-4567",
      "location": "Toronto, ON",
      "score": 92,
      "source": "LinkedIn",
      "created_at": "2025-01-15T10:35:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6InByb3NwZWN0XzEyNCJ9",
    "has_more": true
  }
}

POST

/v1/dedupe/check

Check if prospects already exist in your database before creating a research job.

Request Body

JSON

{
  "prospects": [
    {
      "email": "sarah.johnson@techcorp.com",
      "company": "TechCorp Inc."
    },
    {
      "email": "mike@dataflow.com",
      "company": "DataFlow Systems"
    }
  ]
}

Response

JSON

{
  "results": [
    {
      "email": "sarah.johnson@techcorp.com",
      "company": "TechCorp Inc.",
      "exists": true,
      "duplicate_id": "existing_123"
    },
    {
      "email": "mike@dataflow.com",
      "company": "DataFlow Systems",
      "exists": false
    }
  ]
}

POST

/v1/suppressions

Manage suppression lists to avoid contacting prospects who shouldn't be targeted.

Request Body

JSON

{
  "action": "add",
  "suppressions": [
    {
      "email": "unsubscribe@example.com",
      "reason": "unsubscribed"
    },
    {
      "domain": "competitor.com",
      "reason": "competitor"
    }
  ]
}

Response

JSON

{
  "success": true,
  "added_count": 2,
  "total_suppressions": 1247
}

Additional features

Enterprise-grade features for production applications.

HMAC-Signed Webhooks

All webhook deliveries are signed with HMAC-SHA256 to ensure authenticity and prevent tampering.

JavaScript

// Verify webhook signature
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

• 100 requests per minute for most endpoints
• 10 requests per minute for job creation
• Rate limit headers included in responses
• Higher limits available for Enterprise customers

Background Processing

Research jobs run in the background with comprehensive status tracking and progress updates.

• Jobs run asynchronously
• Real-time progress updates
• Automatic retry on failure
• Dead letter queue for failed jobs

SDKs Available

Official SDKs for all major programming languages with comprehensive documentation.

• Node.js / JavaScript
• Python
• PHP
• Ruby
• Go

Ready to integrate?

Get your API key and start building with knockd today.