Leads Management API

Create, update, validate, and manage leads programmatically. Leads combine contact information with automated validation for email deliverability and website accessibility.

Overview

The Leads API provides comprehensive endpoints for:

Create Leads - Add single or bulk leads with auto-validation
Get Lead - Retrieve individual lead details
Update Lead - Modify lead information
List Leads - Query and filter leads with pagination
Validate Leads - Trigger validation for existing leads
Lead Stats - Aggregate statistics and metrics

Pricing

Operation	Cost (Stored)	Cost (Display)
Create Lead (with validation)	0.002 credits	2 credits
Update Lead (no validation)	0 credits	0 credits
Validate Existing Lead	0.002 credits	2 credits

What's Validated:

Email: Always validated (deliverability, catch-all, risk scoring)
Website: Only validated if website field is provided

New Users: Get 2,000 display credits (2.0 stored credits) on signup!

Rate Limits

Endpoint	Rate Limit
`/leads` POST (create)	10 requests/minute
`/leads` GET (list)	30 requests/minute
`/leads/{id}` GET	30 requests/minute
`/leads/{id}` PUT	10 requests/minute
`/leads/validate` POST	5 requests/minute
`/leads/bulk` POST	2 requests/minute

Create Lead

Create a new lead with automatic validation.

Endpoint: POST /v1/leads

Authentication: API Key or OAuth 2.0 Bearer Token

Validation Behavior

Automatic by default - Validation triggers automatically unless validate: false
Email: Always validated (required field)
Website: Only validated if provided
Credits: 0.002 per lead (deducted before validation starts)

Request

curl -X POST https://api.status-check.io/v1/leads \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "website": "example.com",
    "firstName": "John",
    "lastName": "Doe",
    "company": "Example Corp",
    "title": "CTO",
    "validate": true
  }'

Request Body

Field	Type	Required	Description
`email`	string	Yes	Email address (validated format)
`website`	string	No	Website URL (protocol optional, auto-normalized)
`firstName`	string	No	First name (1-100 chars)
`lastName`	string	No	Last name (1-100 chars)
`company`	string	No	Company name (max 200 chars)
`title`	string	No	Job title (max 100 chars)
`phone`	string	No	Phone number (max 50 chars)
`linkedIn`	string	No	LinkedIn profile URL (max 500 chars)
`twitter`	string	No	Twitter profile URL (max 500 chars)
`leadServiceCategory`	string	No	Service category (e.g., "SaaS", "E-commerce")
`leadServiceSubcategory`	string	No	Service subcategory
`campaign`	string	No	Campaign identifier
`tags`	array	No	User-defined tags
`notes`	string	No	Internal notes
`priority`	string	No	Priority: `low`, `normal`, `high`, `urgent` (default: `normal`)
`status`	boolean	No	Active/inactive lead (default: `true`)
`customFields`	object	No	Custom key-value pairs (max 50 fields, 1KB per value)
`validate`	boolean	No	Trigger auto-validation (default: `true`)

Response

{
  "id": "lead_abc123",
  "email": "john@example.com",
  "website": "https://example.com",
  "firstName": "John",
  "lastName": "Doe",
  "company": "Example Corp",
  "title": "CTO",
  "validationStatus": "new",
  "leadDeliverabilityRating": 0,
  "emailValid": null,
  "domainHttpStatus": null,
  "created": "2025-01-15T10:30:00Z",
  "updated": "2025-01-15T10:30:00Z",
  "source": "manual",
  "customFields": {},
  "metadata": {
    "validate": true
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique lead identifier
`email`	string	Email address
`website`	string	Normalized website URL
`validationStatus`	string	Status: `new`, `processing`, `valid`, `invalid`, `risky`
`leadDeliverabilityRating`	number	Quality score 0-100 (calculated after validation)
`emailValid`	boolean	Email deliverability (null until validated)
`emailCatchAll`	boolean	Catch-all domain detected
`emailService`	string	Email provider (e.g., "Google", "Microsoft")
`domainHttpStatus`	number	HTTP status code (null until validated)
`domainFinalUrl`	string	Final URL after redirects
`domainSslValid`	boolean	SSL certificate validity
`domainResponseTimeMs`	number	Response time in milliseconds
`created`	datetime	Creation timestamp
`updated`	datetime	Last updated timestamp
`source`	string	Lead source: `manual`, `api`, `csv`, `google_sheets`

Custom Fields

{
  "email": "john@acme.com",
  "company": "Acme Corp",
  "customFields": {
    "industry": "SaaS",
    "employeeCount": "50-100",
    "leadSource": "Trade Show",
    "lastContactDate": "2025-01-10"
  }
}

Limits:

Max 50 custom fields per lead
Max 100 characters per field name
Max 1KB per field value (when serialized)

Validation Options

Skip Validation (No Credits Deducted):

{
  "email": "john@example.com",
  "validate": false
}

Auto-Fill Website from Email Domain:

If no website provided, you can manually add it or leave empty:

{
  "email": "john@example.com"
  // Website validation skipped (no website field)
}

Get Lead

Retrieve a single lead by ID.

Endpoint: GET /v1/leads/{leadId}

Authentication: API Key or OAuth 2.0 Bearer Token

Request

curl -X GET https://api.status-check.io/v1/leads/lead_abc123 \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "id": "lead_abc123",
  "email": "john@example.com",
  "website": "https://example.com",
  "validationStatus": "valid",
  "leadDeliverabilityRating": 95,
  "emailValid": true,
  "emailCatchAll": false,
  "emailService": "Google",
  "domainHttpStatus": 200,
  "domainFinalUrl": "https://example.com/",
  "domainSslValid": true,
  "domainResponseTimeMs": 245.67,
  "created": "2025-01-15T10:30:00Z",
  "updated": "2025-01-15T10:35:00Z"
}

Update Lead

Update an existing lead's information.

Endpoint: PUT /v1/leads/{leadId}

Authentication: API Key or OAuth 2.0 Bearer Token

Note: Updating does NOT trigger re-validation. Use /validate endpoint to re-validate.

Request

curl -X PUT https://api.status-check.io/v1/leads/lead_abc123 \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "VP of Engineering",
    "notes": "Follow up next week",
    "tags": ["qualified", "enterprise"]
  }'

Request Body

All fields are optional. Only include fields you want to update.

Field	Type	Description
`firstName`	string	First name
`lastName`	string	Last name
`email`	string	Email address
`phone`	string	Phone number
`company`	string	Company name
`title`	string	Job title
`website`	string	Website URL
`linkedIn`	string	LinkedIn URL
`twitter`	string	Twitter URL
`campaign`	string	Campaign identifier
`tags`	array	Tags
`notes`	string	Notes
`priority`	string	Priority level
`status`	boolean	Active status
`customFields`	object	Custom fields (merged with existing)

Response

{
  "id": "lead_abc123",
  "title": "VP of Engineering",
  "notes": "Follow up next week",
  "tags": ["qualified", "enterprise"],
  "updated": "2025-01-15T11:00:00Z"
}

List Leads

Query and filter leads with pagination.

Endpoint: GET /v1/leads

Authentication: API Key or OAuth 2.0 Bearer Token

Request

curl -X GET "https://api.status-check.io/v1/leads?limit=50&emailValid=true&minDeliverabilityRating=80" \
  -H "X-API-Key: sk_your_api_key"

Query Parameters

Parameter	Type	Description
`limit`	number	Results per page (1-100, default: 50)
`offset`	number	Skip N results (for pagination, default: 0)
`emailValid`	boolean	Filter by email validity
`minDeliverabilityRating`	number	Minimum quality score (0-100)
`validationStatus`	string	Filter by status: `new`, `processing`, `valid`, `invalid`, `risky`

Response

{
  "leads": [
    {
      "id": "lead_abc123",
      "email": "john@example.com",
      "validationStatus": "valid",
      "leadDeliverabilityRating": 95
    },
    {
      "id": "lead_def456",
      "email": "jane@acme.com",
      "validationStatus": "valid",
      "leadDeliverabilityRating": 88
    }
  ],
  "total": 150,
  "hasMore": true,
  "nextOffset": 50
}

Pagination Example

async function getAllLeads() {
  let offset = 0;
  const limit = 100;
  const allLeads = [];

  while (true) {
    const response = await fetch(
      `https://api.status-check.io/v1/leads?limit=${limit}&offset=${offset}`,
      { headers: { 'X-API-Key': apiKey } }
    );

    const data = await response.json();
    allLeads.push(...data.leads);

    if (!data.hasMore) break;
    offset = data.nextOffset;
  }

  return allLeads;
}

Validate Leads

Trigger validation for existing leads.

Endpoint: POST /v1/leads/validate

Authentication: API Key or OAuth 2.0 Bearer Token

Validation Behavior

Email: Always validated (required)
Website: Only validated if lead has website field
Credits: 0.002 per lead (deducted upfront)
Processing: Synchronous for domain, async for email (with background polling)

Request

curl -X POST https://api.status-check.io/v1/leads/validate \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "leadIds": ["lead_abc123", "lead_def456", "lead_ghi789"]
  }'

Request Body

Field	Type	Required	Description
`leadIds`	array	Yes	Lead IDs to validate (1-500 max)
`webhookUrl`	string	No	Optional webhook for async completion (external API users only)

Response

{
  "batchId": "batch_xyz789",
  "status": "processing",
  "createdAt": "2025-01-15T10:30:00Z",
  "pollUrl": "/v1/batches/batch_xyz789"
}

Response Fields

Field	Type	Description
`batchId`	string	Validation batch identifier
`status`	string	Status: `processing`, `completed`, `failed`
`createdAt`	datetime	Batch creation timestamp
`pollUrl`	string	URL to poll for results (external API users)

Polling for Results

curl -X GET https://api.status-check.io/v1/batches/batch_xyz789 \
  -H "X-API-Key: sk_your_api_key"

Response:

{
  "batchId": "batch_xyz789",
  "status": "completed",
  "totalLeads": 3,
  "completedLeads": 3,
  "validLeads": 2,
  "invalidLeads": 1,
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:31:30Z"
}

Bulk Create Leads

Create multiple leads in a single request.

Endpoint: POST /v1/leads/bulk

Authentication: API Key or OAuth 2.0 Bearer Token

Rate Limit: 2 requests/minute (max 500 leads per request)

Request

curl -X POST https://api.status-check.io/v1/leads/bulk \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "email": "john@example.com",
        "firstName": "John",
        "company": "Example Corp"
      },
      {
        "email": "jane@acme.com",
        "firstName": "Jane",
        "company": "Acme Inc"
      }
    ],
    "validate": true
  }'

Request Body

Field	Type	Required	Description
`leads`	array	Yes	Array of lead objects (1-500 max)
`validate`	boolean	No	Auto-validate all leads (default: `true`)

Response

{
  "created": 2,
  "failed": 0,
  "batchId": "batch_abc123",
  "leads": [
    {
      "id": "lead_abc123",
      "email": "john@example.com",
      "status": "created"
    },
    {
      "id": "lead_def456",
      "email": "jane@acme.com",
      "status": "created"
    }
  ]
}

Error Responses

400 Bad Request

{
  "detail": "A lead with this email already exists in your account"
}

402 Payment Required

{
  "detail": "Insufficient credits. You need 0.002 credits to validate this lead, but you have 0.0 credits. Purchase credits to continue."
}

404 Not Found

{
  "detail": "Lead not found"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Code Examples

Python

import requests

API_KEY = "sk_your_api_key"
BASE_URL = "https://api.status-check.io/v1"

# Create lead with validation
response = requests.post(
    f"{BASE_URL}/leads",
    headers={"X-API-Key": API_KEY},
    json={
        "email": "john@example.com",
        "website": "example.com",
        "firstName": "John",
        "company": "Example Corp",
        "validate": True
    }
)

lead = response.json()
print(f"Lead created: {lead['id']}")

# List high-quality leads
response = requests.get(
    f"{BASE_URL}/leads",
    headers={"X-API-Key": API_KEY},
    params={
        "emailValid": True,
        "minDeliverabilityRating": 80,
        "limit": 100
    }
)

leads = response.json()
print(f"Found {len(leads['leads'])} quality leads")

JavaScript/Node.js

const API_KEY = 'sk_your_api_key';
const BASE_URL = 'https://api.status-check.io/v1';

// Create lead
async function createLead(email, website) {
  const response = await fetch(`${BASE_URL}/leads`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email,
      website,
      validate: true,
    }),
  });

  const lead = await response.json();
  console.log(`Lead created: ${lead.id}`);
  return lead;
}

// Validate existing leads
async function validateLeads(leadIds) {
  const response = await fetch(`${BASE_URL}/leads/validate`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ leadIds }),
  });

  const batch = await response.json();
  console.log(`Validation batch: ${batch.batchId}`);
  return batch;
}

// Usage
await createLead('john@example.com', 'example.com');
await validateLeads(['lead_abc123', 'lead_def456']);

Best Practices

1. Use Bulk Creation for Large Imports

# Instead of creating leads one by one
for lead_data in leads:
    create_lead(lead_data)  # ❌ Slow, hits rate limits

# Use bulk endpoint
create_leads_bulk(leads)  # ✅ Fast, single request

2. Skip Validation for Draft Leads

{
  "email": "draft@example.com",
  "validate": false
}

Validate later when lead is qualified:

POST /v1/leads/validate
{"leadIds": ["lead_draft123"]}

3. Filter by Quality Score

GET /v1/leads?emailValid=true&minDeliverabilityRating=80

4. Use Custom Fields for Filtering

{
  "email": "john@example.com",
  "customFields": {
    "industry": "SaaS",
    "deal_size": "enterprise",
    "engagement_score": 85
  }
}

Validation API - Standalone validation endpoints
Webhooks - Webhook notifications
Lead Stats API - Analytics and metrics
Credits API - Credit balance and usage
Lead Management - Validation process and quality scoring

Support

Questions about the Leads API?

Email: support@status-check.io
Dashboard: app.status-check.io
API Docs: api.status-check.io/docs

Overview​

Pricing​

Rate Limits​

Create Lead​

Validation Behavior​

Request​

Request Body​

Response​

Response Fields​

Custom Fields​

Validation Options​

Get Lead​

Request​

Response​

Update Lead​

Request​

Request Body​

Response​

List Leads​

Request​

Query Parameters​

Response​

Pagination Example​

Validate Leads​

Validation Behavior​

Request​

Request Body​

Response​

Response Fields​

Polling for Results​

Bulk Create Leads​

Request​

Request Body​

Response​

Error Responses​

400 Bad Request​

402 Payment Required​

404 Not Found​

422 Validation Error​

Code Examples​

Python​

JavaScript/Node.js​

Best Practices​

1. Use Bulk Creation for Large Imports​

2. Skip Validation for Draft Leads​

3. Filter by Quality Score​

4. Use Custom Fields for Filtering​

Related Documentation​

Support​

Overview

Pricing

Rate Limits

Create Lead

Validation Behavior

Request

Request Body

Response

Response Fields

Custom Fields

Validation Options

Get Lead

Request

Response

Update Lead

Request

Request Body

Response

List Leads

Request

Query Parameters

Response

Pagination Example

Validate Leads

Validation Behavior

Request

Request Body

Response

Response Fields

Polling for Results

Bulk Create Leads

Request

Request Body

Response

Error Responses

400 Bad Request

402 Payment Required

404 Not Found

422 Validation Error

Code Examples

Python

JavaScript/Node.js

Best Practices

1. Use Bulk Creation for Large Imports

2. Skip Validation for Draft Leads

3. Filter by Quality Score

4. Use Custom Fields for Filtering

Related Documentation

Support