Skip to content
LeadSonar LeadSonar Docs

LeadSonar for AI agents

Your agent can already write the email. LeadSonar tells it who to send it to.

Point any agent that can call an HTTP API at LeadSonar and it can size a market, shortlist the right people, check how well each one fits, and hand back a verified list for your sequencer, with the spending under your control.

Explore for free

Counting and browsing cost nothing. An agent can try twenty filter combinations to find the right audience before spending a single credit.

Never pays twice

Revealing someone you already own costs 0 credits, and exports skip people you already have. An agent re-running a task won’t double-charge you.

Fit, not just contacts

icp-score grades any contact A–D against a one-line description of your customer, from the company’s own website, in about a second.

Machine-readable end to end

One API key, JSON in and out, an OpenAPI spec for tool generation, and these docs as plain text at /llms.txt.

Hand this to your agent

Section titled “Hand this to your agent”

The fastest start: copy this prompt, paste your API key where it says, and give it to any agent that can make HTTP requests: Claude, ChatGPT, Cursor, or your own.

Prompt for your agent
You can use LeadSonar for me. LeadSonar is a B2B lead database: it finds people
at companies (mostly in the US) and their work email addresses.


How to use it
- Read the docs first: https://docs.leadsonar.io/llms-full.txt
- API spec (generate tools from it): https://docs.leadsonar.io/openapi.json
- Base URL: https://app.leadsonar.io — endpoints are under /api/v1/
- Send my key in the X-API-Key header: <PASTE YOUR LS_LIVE KEY HERE>


What costs money
- Free: counting (POST /api/v1/leads/search) and browsing masked results
  (POST /api/v1/leads/browse), plus GET /api/v1/credits.
- 1 credit per NEW person revealed (POST /api/v1/leads/reveal) or exported
  (POST /api/v1/leads/exports). People I already have are never charged again.


Rules
- Always count first and tell me the estimated_total before revealing or exporting.
- Ask me before anything that costs more than 100 credits.
- When filtering by job title, always send "exactMatch": true.
- If a count comes back 0, read the "filters" field in the response: an unknown
  value matches nothing instead of raising an error.
- The data is US-focused, and revenue bands come from headcount — say so if it matters.

What an agent can do with it

Section titled “What an agent can do with it”
TaskCallsCost
“How many heads of sales at US SaaS companies with 50–200 people?”POST /leads/searchFree
“Show me 25 of them.”POST /leads/browseFree
“Get contact details for these 10.”POST /leads/reveal1 credit per new person
“Build me a list of 2,000 for next month’s campaign.”POST /leads/exports1 credit per person delivered
“Is this lead a good fit for us?”POST /icp-score1 credit
“What does this company actually do?”POST /scrape/jobs1 credit per domain, refunded if the site returns no text

Set it up

Section titled “Set it up”

  1. Create an API key in the app under Settings → API Keys. Give the agent its own key, so its spending shows up separately and you can revoke it on its own.

  2. Give the agent the spec. Most agent frameworks can generate tools straight from an OpenAPI file:

    https://docs.leadsonar.io/openapi.json

    Or point it at the docs as plain text: /llms.txt (an index) or /llms-full.txt (every page in one file).

  3. Or define a few tools by hand. Four tools cover most work. Here they are in the tool format the Claude API uses; other frameworks take the same JSON Schema:

    [
      {
        "name": "count_leads",
        "description": "Count people matching filters. Free. Always call this before revealing or exporting. Use estimated_total for planning.",
        "input_schema": {
          "type": "object",
          "properties": {
            "jobTitles": { "type": "array", "items": { "type": "string" }, "description": "e.g. [\"Head of Sales\", \"VP Sales\"]" },
            "exactMatch": { "type": "boolean", "description": "Always true when jobTitles is set" },
            "excludeTitles": { "type": "array", "items": { "type": "string" } },
            "industry": { "type": "array", "items": { "type": "string" } },
            "companySize": { "type": "array", "items": { "type": "string", "enum": ["1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001+"] } },
            "country": { "type": "array", "items": { "type": "string" }, "description": "ISO codes. Data is US-focused." },
            "includeKeywords": { "type": "array", "items": { "type": "string" }, "description": "Matched against the company description, not titles" }
          }
        }
      },
      {
        "name": "browse_leads",
        "description": "List matching people with contact details masked. Free. Same filters as count_leads plus page and limit (max 1000).",
        "input_schema": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" } }, "additionalProperties": true }
      },
      {
        "name": "reveal_leads",
        "description": "Unlock contact details. Costs 1 credit per person not already revealed. Ask the user before revealing more than they approved.",
        "input_schema": { "type": "object", "properties": { "leadIds": { "type": "array", "items": { "type": "string" } } }, "required": ["leadIds"] }
      },
      {
        "name": "score_icp_fit",
        "description": "Grade one contact A-D against the user's ideal customer. 1 credit.",
        "input_schema": {
          "type": "object",
          "properties": {
            "first_name": { "type": "string" }, "last_name": { "type": "string" },
            "title": { "type": "string" }, "company": { "type": "string" }, "domain": { "type": "string" },
            "target_icp": { "type": "string", "description": "1-2 sentences, max 500 characters" }
          },
          "required": ["target_icp"]
        }
      }
    ]

    Map them to POST /api/v1/leads/search, /leads/browse, /leads/reveal and /icp-score, sending the key in the X-API-Key header.

  4. Give it the house rules (next section) in its system prompt.

Guardrails to put in the system prompt

Section titled “Guardrails to put in the system prompt”

Agents are good at spending money quickly. These rules keep them honest; copy them as-is:

You have access to the LeadSonar lead database.
- Searching and browsing are free. Revealing costs 1 credit per new person; exports cost 1 credit per person delivered.
- Always count first (count_leads). Report the estimated_total to the user before revealing or exporting.
- Never reveal or export more people than the user approved. If a request would cost more than 100 credits, ask first.
- When you filter by job title, always set exactMatch: true.
- If a count is 0, check the "filters" field in the response — an unknown filter value matches nothing rather than raising an error.
- The data is US-focused. Say so if the user asks for another country and the count is small.
- Revenue bands are derived from company headcount; don't treat them as reported revenue.

Read the docs as an agent

Section titled “Read the docs as an agent”

These docs are published for machines as well as people: