Developers

API reference

Build Leadiy discovery, enrichment, scoring and outreach right into your own stack. A clean REST API with predictable resources, JSON everywhere, and secure API-key auth.

Get API keys

Leadiy API

A REST API to find businesses, enrich contacts, score opportunities and run outreach - programmatically.

The Leadiy API is organized around REST. It has predictable, resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP verbs, status codes and authentication.

Every request is made to the base URL below. All requests must be made over HTTPS - calls made over plain HTTP will fail, and requests without authentication will also fail.

This reference describes the planned v1 surface. Endpoints and payloads may evolve before general availability.

Introduction

# Base URL for all API requests
https://api.leadiy.com/v1

Authentication

Authenticate with a secret API key sent as a Bearer token.

The Leadiy API uses API keys to authenticate requests. You can create and manage your keys from your dashboard under Settings → API keys. Keep your secret keys safe: they carry the ability to spend points and act on your account.

Provide your key in the Authorization header as a Bearer token on every request. Never expose a secret key in client-side code, a public repository, or anywhere a user could read it.

Test keys are prefixed csq_test_ and live keys csq_live_. Test keys never spend real points.

Authentication

curl https://api.leadiy.com/v1/account \
  -H "Authorization: Bearer $LEADIY_API_KEY"

Making requests

Send JSON, get JSON. Standard verbs, standard status codes.

For POST and PATCH requests, send a JSON body and set the Content-Type header to application/json. GET requests take parameters in the query string. Successful responses return a 2xx status code and a JSON body.

Most write operations spend points - the response includes a points_spent field and an X-Points-Remaining header so you can track usage in real time.

Making requests

curl https://api.leadiy.com/v1/businesses/enrich \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "business_ids": ["biz_8Kd21"] }'

Errors

Conventional HTTP status codes plus a structured error object.

Leadiy uses standard HTTP status codes: 2xx for success, 4xx for a problem with the request (a missing parameter, a failed validation, insufficient points), and 5xx for a rare error on our end.

Every error response includes a JSON body with a machine-readable code, a human-readable message, and - for validation errors - the offending fields.

Code	Meaning
200 / 201	Success - the request worked.
400	Bad request - often a missing or invalid parameter.
401	Unauthorized - no valid API key provided.
402	Insufficient points to complete the request.
404	The requested resource doesn't exist.
429	Too many requests - you hit a rate limit.
500	Something went wrong on our end.

Errors

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "The \"location\" parameter is required.",
    "param": "location"
  }
}

Rate limits & points

Two limits to know: request rate, and your monthly points balance.

Requests are rate-limited per API key. If you exceed the limit you'll receive a 429 response - back off and retry with exponential backoff. Every response includes X-RateLimit-Remaining and X-RateLimit-Reset headers.

Separately, data and AI operations spend points from your plan's monthly balance (from 50 on Free up to 30,000 on Enterprise). Read-only calls like listing resources are free; searches, enrichment, scoring, analyses and AI generation spend points, always reported back in the response.

Rate limits & points

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 96
X-RateLimit-Reset: 1735689600
X-Points-Remaining: 1984

Pagination

List endpoints are cursor-paginated.

All top-level list endpoints accept a limit (default 20, max 100) and a starting_after cursor. The response includes has_more and, when true, the id to pass as the next starting_after.

Iterate by passing the last object's id as starting_after until has_more is false.

Pagination

curl "https://api.leadiy.com/v1/lead-lists?limit=20&starting_after=list_9Fa02" \
  -H "Authorization: Bearer $LEADIY_API_KEY"

Businesses

Search real businesses by category and location, and retrieve a single business by id.

Search businesses

GET/businesses/search

Returns businesses matching a category and location. The number of results is capped by your plan (5 on Free up to 500 on Enterprise). Spends points.

Parameters

categorystringrequired

Business category, e.g. "restaurants", "dentists".

locationstringrequired

City, region or area to search within.

limitintegeroptional

Max results to return (bounded by your plan).

GET /businesses/search

curl "https://api.leadiy.com/v1/businesses/search?category=restaurants&location=Los%20Angeles&limit=25" \
  -H "Authorization: Bearer $LEADIY_API_KEY"

Response

{
  "object": "list",
  "points_spent": 8,
  "data": [
    {
      "id": "biz_8Kd21",
      "name": "Bella Napoli Pizzeria",
      "category": "Italian Restaurant",
      "rating": 4.7,
      "address": "1421 Sunset Blvd, Los Angeles, CA",
      "website": "bellanapoli.com",
      "phone": "+1 213-555-0142"
    }
  ],
  "has_more": true
}

Retrieve a business

GET/businesses/{id}

Fetches a single business, including any enriched fields you've added.

Parameters

idstringrequired

The business id.

GET /businesses/{id}

curl https://api.leadiy.com/v1/businesses/biz_8Kd21 \
  -H "Authorization: Bearer $LEADIY_API_KEY"

Response

{
  "id": "biz_8Kd21",
  "name": "Bella Napoli Pizzeria",
  "category": "Italian Restaurant",
  "rating": 4.7,
  "website": "bellanapoli.com",
  "email": "hello@bellanapoli.com",
  "enriched": true
}

Enrichment

Append verified emails and richer company detail to businesses you've found.

Enrich businesses

POST/businesses/enrich

Finds and verifies contact emails and fills in extra detail for the given businesses using AI extraction. Spends points per business.

Parameters

business_idsstring[]required

Ids of businesses to enrich.

POST /businesses/enrich

curl https://api.leadiy.com/v1/businesses/enrich \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_ids":["biz_8Kd21","biz_3Lp77"]}'

Response

{
  "object": "list",
  "points_spent": 6,
  "data": [
    {
      "id": "biz_8Kd21",
      "email": "hello@bellanapoli.com",
      "email_status": "verified",
      "employees": 24,
      "socials": {
        "instagram": "@bellanapoli"
      },
      "enriched": true
    }
  ]
}

Opportunities

Score and rank businesses by how strong an opportunity they are for your offer.

Find opportunities

POST/opportunities/find

Runs the AI Opportunity Score across the given businesses for your offer, returning a 0–100 score, a summary and specific opportunities for each. Spends points per business.

Parameters

business_idsstring[]required

Businesses to score.

instructionstringrequired

What you offer and who benefits most.

anglestringoptional

Opportunity angle to sharpen scoring, e.g. "Poor SEO".

POST /opportunities/find

curl https://api.leadiy.com/v1/opportunities/find \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_ids":["biz_8Kd21"],"instruction":"restaurants that could grow with better social media and local marketing","angle":"No social media"}'

Response

{
  "object": "list",
  "points_spent": 10,
  "data": [
    {
      "id": "biz_8Kd21",
      "score": 94,
      "summary": "Strong ratings but almost no social presence - quick wins available.",
      "opportunities": [
        {
          "title": "Local social campaigns",
          "level": "HIGH"
        }
      ]
    }
  ]
}

Sales Intelligence

Read buying intent and growth signals, estimate deal value and get the best contact.

Analyze accounts

POST/sales-intel/analyze

Evaluates each account's lead quality, buying intent, growth signals and estimated deal value, and recommends the best contact and channel. Spends points per account.

Parameters

business_idsstring[]required

Accounts to analyze.

POST /sales-intel/analyze

curl https://api.leadiy.com/v1/sales-intel/analyze \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_ids":["biz_8Kd21"]}'

Response

{
  "object": "list",
  "points_spent": 12,
  "data": [
    {
      "id": "biz_8Kd21",
      "lead_quality": 87,
      "intent": "high",
      "signals": [
        "hiring",
        "ad_spend_up"
      ],
      "deal_value": "$8k–12k/yr",
      "best_contact": {
        "role": "Owner",
        "channel": "email"
      }
    }
  ]
}

Market

Size a market by category and location - size, saturation and top segments.

Analyze a market

POST/market/analyze

Analyzes the businesses that make up a market and returns its size, saturation and segment breakdown. Spends points based on scan depth.

Parameters

categorystringrequired

Market category.

locationstringrequired

Market location.

POST /market/analyze

curl https://api.leadiy.com/v1/market/analyze \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"coffee shops","location":"Los Angeles"}'

Response

{
  "id": "mkt_2Qa19",
  "size": 3240,
  "saturation": "medium",
  "growth_yoy": 0.12,
  "segments": [
    {
      "name": "Specialty cafes",
      "count": 1180
    }
  ],
  "points_spent": 20
}

Competitors

Benchmark businesses side by side to find the gaps.

Compare competitors

POST/competitors/analyze

Evaluates each business across presence, reputation and more, and ranks them for comparison. Spends points.

Parameters

business_idsstring[]required

Businesses to benchmark.

POST /competitors/analyze

curl https://api.leadiy.com/v1/competitors/analyze \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_ids":["biz_8Kd21","biz_3Lp77","biz_5Rt44"]}'

Response

{
  "object": "list",
  "points_spent": 14,
  "data": [
    {
      "id": "biz_8Kd21",
      "rank": 1,
      "score": 88,
      "leader": true,
      "gaps": [
        "no retargeting"
      ]
    }
  ]
}

Lead Lists

Create and manage named lists of businesses.

List lead lists

GET/lead-lists

Returns your lead lists, most recent first. Cursor-paginated. Free.

Parameters

limitintegeroptional

Max lists to return (max 100).

GET /lead-lists

curl "https://api.leadiy.com/v1/lead-lists?limit=20" \
  -H "Authorization: Bearer $LEADIY_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "list_9Fa02",
      "name": "Downtown restaurants · Q3",
      "count": 18,
      "tags": [
        "hot",
        "food"
      ]
    }
  ],
  "has_more": false
}

Create a lead list

POST/lead-lists

Creates an empty lead list you can add businesses to. Free.

Parameters

namestringrequired

List name.

descriptionstringoptional

Optional description.

tagsstring[]optional

Optional tags.

POST /lead-lists

curl https://api.leadiy.com/v1/lead-lists \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Downtown restaurants · Q3","description":"Dine-in prospects","tags":["hot","food"]}'

Response

{
  "id": "list_9Fa02",
  "name": "Downtown restaurants · Q3",
  "count": 0
}

Add businesses to a list

POST/lead-lists/{id}/businesses

Adds one or more businesses to a lead list. Free.

Parameters

idstringrequired

The lead list id.

business_idsstring[]required

Businesses to add.

POST /lead-lists/{id}/businesses

curl https://api.leadiy.com/v1/lead-lists/biz_8Kd21/businesses \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_ids":["biz_8Kd21","biz_3Lp77"]}'

Response

{
  "id": "list_9Fa02",
  "count": 2,
  "added": 2
}

Contacts

Your built-in CRM - contacts, activities and tasks.

Create a contact

POST/contacts

Creates a contact, optionally from an existing business. Free.

Parameters

business_idstringoptional

Link the contact to a business.

statusstringoptional

new · contacted · proposal · won · lost.

POST /contacts

curl https://api.leadiy.com/v1/contacts \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_id":"biz_8Kd21","status":"new"}'

Response

{
  "id": "con_7Zx90",
  "business_id": "biz_8Kd21",
  "status": "new"
}

Log an activity

POST/contacts/{id}/activities

Adds an activity (call, email, note) to a contact's timeline. Free.

Parameters

idstringrequired

The contact id.

typestringrequired

call · email · note.

bodystringrequired

Activity content.

POST /contacts/{id}/activities

curl https://api.leadiy.com/v1/contacts/biz_8Kd21/activities \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"note","body":"Spoke with the owner - send Q3 proposal Friday."}'

Response

{
  "id": "act_1Bc23",
  "contact_id": "con_7Zx90",
  "type": "note"
}

Outreach

Generate personalized outreach for a business with AI.

Generate a message

POST/outreach/generate

Drafts a personalized message for a business on the chosen channel, tone and language. Spends points per generation.

Parameters

business_idstringrequired

The prospect to write to.

channelstringrequired

cold_email · follow_up · linkedin · whatsapp · sms · call_script.

tonestringoptional

professional · friendly · persuasive …

languagestringoptional

One of 20+ supported languages.

instructionstringoptional

Extra guidance for the draft.

POST /outreach/generate

curl https://api.leadiy.com/v1/outreach/generate \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_id":"biz_8Kd21","channel":"cold_email","tone":"friendly","language":"English","instruction":"offer a free social audit, keep it warm"}'

Response

{
  "id": "out_4Dd56",
  "channel": "cold_email",
  "subject": "A quick idea for Bella Napoli",
  "body": "Hi Bella Napoli - loved your 4.7★ reviews…",
  "points_spent": 3
}

Templates

Reusable email templates with merge fields.

List templates

GET/templates

Returns your saved email templates. Free.

GET /templates

curl https://api.leadiy.com/v1/templates \
  -H "Authorization: Bearer $LEADIY_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "tpl_6Ee78",
      "name": "Intro - restaurants",
      "subject": "A quick idea for {{business.name}}"
    }
  ],
  "has_more": false
}

Create a template

POST/templates

Creates a reusable template with merge fields like {{business.name}}. Free.

Parameters

namestringrequired

Template name.

subjectstringrequired

Subject line (supports merge fields).

bodystringrequired

HTML or text body (supports merge fields).

POST /templates

curl https://api.leadiy.com/v1/templates \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Intro - restaurants","subject":"A quick idea for {{business.name}}","body":"Hi {{business.name}}, I came across your work…"}'

Response

{
  "id": "tpl_6Ee78",
  "name": "Intro - restaurants"
}

Campaigns

Create, send and track outreach campaigns from your connected email.

Create a campaign

POST/campaigns

Creates a campaign from a lead list and a template. Requires a connected SMTP sender. Free to create; sending spends points.

Parameters

namestringrequired

Campaign name.

lead_list_idstringrequired

Recipients source list.

template_idstringrequired

Template to send.

schedulestringoptional

ISO 8601 time to send; omit to send now.

POST /campaigns

curl https://api.leadiy.com/v1/campaigns \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"LA cafes - March","lead_list_id":"list_9Fa02","template_id":"tpl_6Ee78","schedule":"2026-03-14T09:00:00Z"}'

Response

{
  "id": "cmp_2Ff90",
  "status": "scheduled",
  "recipients": 48
}

Send a campaign

POST/campaigns/{id}/send

Sends (or launches the scheduled send of) a campaign. Spends points per recipient.

Parameters

idstringrequired

The campaign id.

POST /campaigns/{id}/send

curl https://api.leadiy.com/v1/campaigns/biz_8Kd21/send \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY"

Response

{
  "id": "cmp_2Ff90",
  "status": "sending",
  "recipients": 48,
  "points_spent": 48
}

Retrieve a campaign

GET/campaigns/{id}

Returns a campaign with live stats - sent, opened, clicked and replied. Free.

Parameters

idstringrequired

The campaign id.

GET /campaigns/{id}

curl https://api.leadiy.com/v1/campaigns/biz_8Kd21 \
  -H "Authorization: Bearer $LEADIY_API_KEY"

Response

{
  "id": "cmp_2Ff90",
  "status": "sent",
  "stats": {
    "sent": 48,
    "opened": 31,
    "clicked": 12,
    "replied": 9
  }
}

Reports

Generate branded, shareable reports from your research.

Generate a report

POST/reports/generate

Builds a polished report (market, competitor, website audit or opportunity summary). Spends points based on depth. Returns a URL to the finished report.

Parameters

typestringrequired

market · competitor · website · opportunity.

market_idstringoptional

Source object id for the report.

brandingbooleanoptional

Include your logo and branding.

POST /reports/generate

curl https://api.leadiy.com/v1/reports/generate \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"market","market_id":"mkt_2Qa19","branding":true}'

Response

{
  "id": "rpt_3Gg12",
  "type": "market",
  "status": "ready",
  "url": "https://api.leadiy.com/v1/reports/rpt_3Gg12.pdf",
  "points_spent": 15
}

Account

Your plan, points balance and usage.

Retrieve account

GET/account

Returns your current plan, points balance and result limits. Free.

GET /account

curl https://api.leadiy.com/v1/account \
  -H "Authorization: Bearer $LEADIY_API_KEY"

Response

{
  "id": "acct_0Aa11",
  "plan": "growth",
  "points_remaining": 1984,
  "points_included": 2000,
  "max_results": 50,
  "renews_at": "2026-04-01T00:00:00Z"
}

Webhooks

Subscribe to events so your systems react in real time.

Create a webhook endpoint

POST/webhooks

Registers a URL to receive event notifications. We POST a signed JSON payload to your URL when subscribed events occur.

Parameters

urlstringrequired

HTTPS URL to receive events.

eventsstring[]required

Event types to subscribe to.

POST /webhooks

curl https://api.leadiy.com/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer $LEADIY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/leadiy","events":["campaign.replied","enrichment.completed"]}'

Response

{
  "id": "whk_5Hh34",
  "url": "https://example.com/hooks/leadiy",
  "secret": "whsec_••••",
  "status": "active"
}

Event types

Your endpoint receives a signed POST for each subscribed event. Verify the signature with the secret from your webhook endpoint before trusting a payload.

search.completedA business search finished.

enrichment.completedAn enrichment job finished.

opportunity.scoredOpportunity scoring completed for a batch.

campaign.sentA campaign finished sending.

campaign.openedA recipient opened a campaign email.

campaign.repliedA recipient replied to a campaign.

report.readyA generated report is ready to download.

Example event payload

{
  "id": "evt_9Kk56",
  "type": "campaign.replied",
  "created": 1735689600,
  "data": {
    "campaign_id": "cmp_2Ff90",
    "contact_id": "con_7Zx90",
    "snippet": "Sounds great - Thursday works."
  }
}

Ready to build?

Create a free account, generate your API keys from Settings â†’ API keys, and make your first call in minutes.

Get API keys Read the guides