Quickstart Guide

For a guide covering authentication, error handling and code samples to get started quickly, see the LeadIQ Public API Guide.

Main Features

The API consists of these main queries and mutations:

1. Contact Search: find a single person based on identifying information:
   • Person name and current (or past) companies.
   • LinkedIn profile.
   • Work email or personal email.
   • And more, see full list here.
2. Company Search: find a single company based on name, domain, country, linkedinUrl.
3. Advanced Search: find a list of people based on some broad search criterias e.g: job title, seniority, role, company size, location, etc. See ContactFilter and CompanyFilter.
   • groupedAdvancedSearch: resulting list of people are grouped into companies and returned.
   • flatAdvancedSearch: resulting list of people is returned as is.
4. Account: view your account details.
5. Submit Data Feedback: submit data correction patch.

Paginating Advanced Search

Both groupedAdvancedSearch and flatAdvancedSearch support two ways to page through results. They behave identically; only the cursor's contents differ, and you never need to look inside it.

Offset pagination (skip + limit) lets you jump directly to any page, but it gets slower the deeper you go, because every result before your page still has to be computed. For this reason skip + limit may not exceed 10,000; beyond that the request is rejected. Use it for browsing the first pages of a result set.

Cursor pagination (after) returns each next page in roughly constant time no matter how deep you are, and is the only way to read a result set larger than 10,000. Use it for exports, syncs, and any complete read of a search. It is also the only method that guarantees you see every record exactly once.

To use cursor pagination:

1. Request the first page with limit only (no skip, no after) and select the after field alongside your results.
2. Pass that after value back unchanged as the after input of the next request, keeping every filter and sort option identical. Do not set skip.
3. Repeat until the response returns no results, or after comes back null.

query {
  groupedAdvancedSearch(input: {
    companyFilter: {
      locations: [
        { country: "United States", areaLevel1: "California" }
      ]
    }
    limit: 100
  }) {
    totalCompanies
    companies { company { id name } }
    after { key value }
  }
}

query {
  groupedAdvancedSearch(input: {
    companyFilter: {
      locations: [
        { country: "United States", areaLevel1: "California" }
      ]
    }
    limit: 100
    after: [
      { key: "companySize", value: "841" }
      { key: "companyName", value: "Example Company" }
      { key: "companyId",   value: "MergedCompany-64651924e83811e4ee15fe6e" }
    ]
  }) {
    companies { company { id name } }
    after { key value }
  }
}

flatAdvancedSearch works exactly the same way. The only difference is that the cursor describes a person instead of a company.

Notes:

• Treat after as an opaque value. Its keys depend on the sort you requested, and its values come from indexed fields that may differ from what is displayed.
• Request the total (totalCompanies / totalPeople) on the first page only. It is expensive to compute, and for large result sets it is an approximation.
• Cursors do not expire and hold no server-side state, so a paging job can be paused and resumed later. They are not snapshots: if the underlying data changes while you page, results can shift slightly.

Prefer not to write code? The MCP Connector gives an AI assistant access to these same operations.

query {
  flatAdvancedSearch(input: {
    companyFilter: {
      locations: [
        { country: "United States", areaLevel1: "California" }
      ]
    }
    limit: 50
  }) {
    totalPeople
    people { id name title }
    after { key value }
  }
}

query {
  flatAdvancedSearch(input: {
    companyFilter: {
      locations: [
        { country: "United States", areaLevel1: "California" }
      ]
    }
    limit: 50
    after: [
      { key: "personSeniority",   value: "5" }
      { key: "personConnections", value: "4352" }
      { key: "personName",        value: "example person" }
      { key: "personId",          value: "PersonID-4d3e379c-3f40-4f90-b436-af9bf628f32f" }
      { key: "companyId",         value: "MergedCompany-5a1d839824000024005e2b09" }
    ]
  }) {
    people { id name title }
    after { key value }
  }
}

The LeadIQ MCP connector lets AI assistants and agents work with LeadIQ through the Model Context Protocol, an open standard for connecting AI tools to external services. You sign in with your LeadIQ account, and the assistant runs searches, enrichment, list management, and Salesforce exports for you. No API code needed.

Most MCP tools wrap operations documented on this page, so the GraphQL API material on filters, types, and pagination also describes what the assistant can do.

Server details

• Server URL: https://mcp.leadiq.com/mcp
• Transport: Streamable HTTP
• Authentication: OAuth 2.0. Sign in with your LeadIQ account; email/password and Google login are both supported.
• Client registration: dynamic. No client ID or secret to configure.
• Requirements: an active LeadIQ account and an MCP client that supports remote servers with OAuth.

What you can do over MCP

• Enrich contacts you already know by LinkedIn URL, work email, or name + company: verified work emails, phone numbers, title, seniority, and employer. Up to 10 per request.
• Enrich companies by domain, name, or LinkedIn: firmographics, technology categories, revenue, funding, NAICS/SIC, and parent company. Up to 10 per request.
• Prospect for new people with ICP filters (title, seniority, role, industry, company size, revenue, funding, location, technologies), sorted and paginated.
• Build account lists: companies matching firmographic and technographic criteria, each with full firmographics and a count of matching contacts.
• Track job changes and promotions, including filters on the previous title and previous company.
• Manage prospect lists: create and browse lists, save prospects into them, and search everything you have saved. Free.
• Verify email deliverability for any address, or re-verify a saved prospect's email (0.1 UC per check).
• Export saved prospects to Salesforce as Leads or Contacts, through the same pipeline as the LeadIQ web app, with duplicate detection and confirmation before anything is written.
• Check your credit balance, live unlock costs, and the signed-in account at any time. Free.

The connector also ships a guided icp prompt. It walks you through defining an ideal customer profile, running the search, and saving the top matches into a prospect list, with the credit cost disclosed and approved up front.

Connect from Claude

1. Open Claude and go to Settings → Connectors → Add custom connector.
2. Name it LeadIQ and enter the server URL https://mcp.leadiq.com/mcp.
3. Save, click Connect, and log in with your LeadIQ email/password or Google login.

Once connected, make sure LeadIQ is toggled ON in the chat's connector menu.

Enterprise SSO note: if your organization enforces enterprise SSO (for example, your company's Google domain is linked to LeadIQ), clicking "Sign in with Google" may show an error. Enter your email address directly instead; the password field will appear and you can log in with your credentials.

Connect from ChatGPT

Requires a paid ChatGPT plan (Plus, Team, or Enterprise).

1. Go to Settings → Apps & Connectors and enable Developer Mode. This is required for third-party MCP connectors.
2. Back in Apps & Connectors, click Create App. Name it LeadIQ, enter the server URL https://mcp.leadiq.com/mcp, and pick OAuth authentication.
3. Save the app. If LeadIQ does not appear right away, log out and back into ChatGPT, or refresh the page.
4. Start a new chat and add LeadIQ as a capability from the connector menu.

Connect from Microsoft Copilot

LeadIQ MCP is a certified connector across Copilot Studio, Power Automate, Power Apps, and Logic Apps.

1. Open the connector gallery and search for "LeadIQ".
2. Select the LeadIQ MCP connector and choose Create connection.
3. Sign in with your LeadIQ account when prompted. No client ID or secret is required; authentication uses OAuth 2.0.
4. Add the LeadIQ MCP action to your flow or agent. Any of the seventeen tools can be called from this single action.

Copilot Studio, Power Apps, and Power Automate list it as a Premium connector; Logic Apps lists it as Standard. Government cloud regions (GCC, GCC High, DoD) and Azure China are not currently supported.

# Streamable HTTP, OAuth 2.0
https://mcp.leadiq.com/mcp

How credits work over MCP

Paid tools bill for data that is actually returned, drawing from the same Universal Credits (UC) as the rest of your plan. Billing is per data point:

Data point	Cost
Profile: name, title, seniority, LinkedIn URL, and the employer's name	0.1 UC per record
Verified work email	1 UC per person
Direct phone	10 UC per person
Company firmographics: domain, industry, size, and more	3 UC per company
Email verification, and re-verification of a saved prospect	0.1 UC per check

The larger unlocks replace the profile fee rather than stacking on top of it, so a person returned with both email and phone costs 11 UC, not 11.1. Company firmographics are charged per company, so a person holding two current positions costs 6 UC of company data, not 3.

• The assistant states the estimated cost before a paid call, and asks for your consent before large ones.
• If you unlocked a data point in the past year, looking it up again is free.
• List management and saved-prospect access never consume credits. Email verification is not free, but at 0.1 UC per check it is the cheapest thing here.
• Exact rates vary by plan. Ask "What's my LeadIQ credit balance and what do unlocks cost?" to see the live rates, which are the ones that apply.

Example prompts

• "What can LeadIQ do?"
• "Enrich jane@acme.com and save her to my Q3 Outbound list"
• "Find VPs of Sales at US software companies with 100-500 employees that use Salesforce"
• "Build me an account list: fintechs with 200+ employees that have a Head of Payments"
• "Who became a VP of Marketing at a healthcare company in the last 90 days?"
• "Verify these three emails before I send my sequence"
• "Export John Smith from my Q3 Outbound list to Salesforce"
• "What's my LeadIQ credit balance?"

Notes and support

• Results depend on available data and verification status.
• Enrichment is batched at up to 10 contacts or companies per request.
• Salesforce export requires a connected Salesforce account and export enabled for your team in LeadIQ.
• Questions? Contact api@leadiq.com.

FindPeople, 25 results, profile only
  25 x 0.1 UC  =  2.5 UC
FindCompanies, 25 accounts with firmographics
  25 x 3 UC    =   75 UC
EnrichPeople, 10 people, verified email
  10 x 1 UC    =   10 UC
EnrichPeople, 10 people, email and phone
  10 x 11 UC   =  110 UC
EnrichCompanies, 10 companies
  10 x 3 UC    =   30 UC