InsureSignal API

The InsureSignal API provides programmatic access to insurance lead data across all verticals. Search, filter, and purchase high-quality leads for group benefits, commercial P&C, personal lines, life & annuities, workers compensation, and specialty lines.

v1.0

Current Version

REST

API Style

JSON

Response Format

Base URL

https://api.insuresignal.com/api/v1

Authentication

The InsureSignal API uses API keys for authentication. Include your API key in the Authorization header of every request.

API Key Authentication

For most API endpoints, include your API key as a Bearer token in the Authorization header:

curl -X GET "https://api.insuresignal.com/api/v1/leads" \
  -H "Authorization: Bearer isk_your_api_key_here"

Getting an API Key

Log in to your InsureSignal account
Navigate to Dashboard → API Access
Click "Create New Key"
Select the permissions you need
Copy and securely store your API key (it is only shown once)

Permission Scopes

Scope	Description
leads:read	Search and view lead previews
leads:purchase	Purchase leads and access full contact info
webhooks:manage	Create, update, and delete webhooks
account:read	View account and billing information
account:write	Update account settings

Keep Your API Keys Secure

Never share API keys in public repositories, client-side code, or logs. If a key is compromised, rotate it immediately from the dashboard.

Rate Limiting

API requests are rate-limited to ensure fair usage and system stability. Limits are applied per API key.

Rate Limit Tiers

Free

60/minute

Basic API access

Professional

120/minute

Increased limits for growing businesses

Enterprise

Custom/minute

Unlimited or custom limits based on agreement

Response Headers

Rate limit information is included in response headers for every API request:

Header	Description
X-RateLimit-Limit	Maximum requests per minute for your tier
X-RateLimit-Remaining	Remaining requests in the current window
X-RateLimit-Reset	ISO timestamp when the rate limit resets

Handling Rate Limits

When you exceed the rate limit, you will receive a 429 status code. Implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = resetTime
        ? new Date(resetTime).getTime() - Date.now()
        : Math.pow(2, i) * 1000;  // Exponential backoff

      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Error Codes

All API errors follow a consistent JSON format for easy handling in your application.

Error Response Format

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable description of the error",
    "details": {
      // Optional additional context
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-20T15:00:00Z"
  }
}

Error Code Reference

Code	HTTP Status	Description
unauthorized	401	Missing or invalid authentication credentials
forbidden	403	Valid authentication but insufficient permissions for this action
not_found	404	The requested resource does not exist
validation_error	400	Request parameters failed validation
rate_limit_exceeded	429	Too many requests - please slow down
insufficient_credits	402	Account does not have enough credits for this purchase
lead_unavailable	409	Lead has already been purchased or is no longer available
internal_error	500	An unexpected server error occurred

Leads

Search, preview, and purchase insurance leads. Full contact information is only available after purchase.

API Keys

Manage API keys for programmatic access. These endpoints require session authentication (web login).

Webhooks

Configure webhook endpoints to receive real-time notifications for events like lead purchases and deliveries.

Verifying Webhook Signatures

All webhook payloads include a signature header for verification. Use your webhook secret to validate incoming requests:

import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// In your webhook handler:
app.post('/webhooks/insuresignal', (req, res) => {
  const signature = req.headers['x-insuresignal-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  const { event, data } = req.body;
  console.log(`Received ${event}`, data);

  res.status(200).send('OK');
});

Available Events

Event	Description
leads.purchased	Triggered when leads are successfully purchased
leads.delivered	Triggered when lead data has been delivered
subscription.created	Triggered when a new subscription is created
subscription.cancelled	Triggered when a subscription is cancelled
payment.succeeded	Triggered when a payment is successful
payment.failed	Triggered when a payment fails