API Docs

REST and MCP access to the GetLeads contact and company databases, enrichment, signals and live-lead products.

Getting started

Base URL: https://app.getleads.io. Send your API key as Authorization: Bearer glb_live_<keyId>_<secret> or X-API-Key. GET /api/health is public; the other REST endpoints require a key. Generate a key at app.getleads.io/api-keys.

Rate limits

The default is 100 requests per minute per account, shared across its API keys. A 429 response includes Retry-After; wait before retrying. Higher limits are available by arrangement. A batch of 100 people is one request, so request rate and records processed are different measurements.

Field naming

Use the public field names returned by GET /api/v1/contacts/columns or the get_available_columns MCP tool. Pass those names in columns, and read results using the response-key mapping below. REST search responses use storage names for some fields; CSV/MCP labels use the public names. Omit columns for the default selection; filtered fields can also be included. Availability varies by record.

Several names refer to the same field: education / education_json, certifications / certifications_json, company_linkedin_url / current_employer_linkedin_url, and direct_dial / direct_phone. Use one name from each pair. main_industry is the normalized industry label; company_industry is the source label.

contact_id is no longer available. Use the person's LinkedIn URL and the identifying data in the record when joining results to your own inputs. Do not infer an input/output match from row position alone.

Common mistakes

• Use enrichment for people you already have: batches of LinkedIn URLs, work emails, or names with a company. Use search to discover people.
• Company search accepts company filters. Use contact search for titles, seniority and other person filters.
• A stored work email is not necessarily verified: UNKNOWN and CATCH_ALL are distinct from VALID. Verify before sending.
• Use exact employee-profile bounds for a hard numeric cutoff. Size-band bounds select overlapping bands.
• Reverse lookup from a phone number is pending. Mobile, direct-dial and company-phone fields are available on records where populated.

HTTP errors

Read the returned message, error and code fields when present. A timeout does not prove that a billed job was never accepted; check its status before submitting it again.

Billing & limits

Plan credits: contact/company search and export, lookups, enrichment and signals. One credit buys one returned record, not one email or one populated field. A matched profile can have no work email. A genuine no-match enrichment should not consume a record credit; inspect the returned success counters and output. Counts, field catalogues and enum values are free. Unlimited accounts use fair-use budgets rather than a finite plan-credit balance.

Prepaid wallet: company followers, profile monitoring, one-time post scrapes and website visitor identification. Wallet cash is separate from plan credits.

Defaults for unlimited accounts are 500,000 rows per UTC day and 6,000,000 per UTC calendar month across search, export and enrichment; account-specific limits can differ. GET /api/v1/usage/fair-use or MCP get_fair_use is authoritative for your account. Exports contain at most 50,000 rows each. REST contact search serves up to 5,000 rows per page; MCP contact search serves up to 100. JSON enrichment batches accept up to 100 people. Large CSVs should use the asynchronous flow.

Health

GET /api/health reports service liveness. GET /api/v1/contacts/health reports database availability and record_count; the count describes records rather than independently deduplicated people.

Production counts checked 29 October 2026: 542,413,703 contact records, 125,227,278 with a work email, 136,275,365 with a personal email and 88,830,227 with a mobile number. These are populated-field counts, not accuracy or deliverability measurements.

Database search

POST/api/v1/contacts/search

Use structured filters inside filters, with limit, offset, columns, max_per_company and optional where_sql alongside it. Flat filters are also accepted. Different filters AND together; values inside one list filter OR together. Use a predicate for OR across different fields.

curl -sS 'https://app.getleads.io/api/v1/contacts/search' \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"filters":{"domains":["hubspot.com"],"require_email":true},"columns":["full_name","current_title","work_email","email_status"],"limit":10}'

Read contacts, returned, has_more and next_offset. Advance with the returned offset, stopping when has_more is false. Use the count endpoint for audience size rather than treating a page's total_available as the full population. If total_available_is_minimum or total_matching_is_minimum is true, the associated number is a lower bound.

POST/api/v1/contacts/search/count

The same filters, without retrieving contacts. Free. Read total_matching and any minimum/estimate flag.

curl -sS 'https://app.getleads.io/api/v1/contacts/search/count' \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"filters":{"domains":["hubspot.com"],"require_email":true}}'

POST/api/v1/contacts/search/export

Start an asynchronous CSV export with the same filters and columns. Optional max_rows is at most 50,000; max_per_company limits contacts per company. The response contains export_id.

GET/api/v1/contacts/search/export/{export_id}

Poll until job_status is completed or failed. On completion download export_url; the link is temporary. Read the actual CSV headers, and preserve original identifiers when joining it to a customer file. Split searches larger than 50,000 into disjoint segments before starting exports.

Company search

Find companies first, then find people at those companies. These endpoints return one row per LinkedIn company page, rather than one row per contact. Search and export cost 1 plan credit per company returned; counts and the column catalogue are free. Company lookup costs 1 credit on a match and 0 on a miss.

Use the same base URL and authentication as contact search: https://app.getleads.io and Authorization: Bearer $GETLEADS_API_KEY.

Company filters and fields

Pass at least one supported filter or where_sql. REST accepts filters at the top level or inside filters; limit, offset, columns, max_rows and where_sql belong at the top level. Different filters combine with AND; values within an array combine with OR.

Use GET /api/v1/contacts/filter-values?field=industries (or company_size, revenue, headquarters_countries, funding_types) for enum values. Size bounds select overlapping LinkedIn size bands; use the exact-headcount filters for a hard numeric cutoff. The company catalogue below lists available fields and their filter parameters.

Person filters return 400, including job_titles, seniority, job_functions, countries, and email-presence filters. For company location, use headquarters_countries, not countries. To qualify people, use contact search. Company search already returns one row per company, so do not pass max_per_company.

GET/api/v1/companies/columns

Free company-only field catalogue. Each entry includes canonical_name, clickhouse_column, label, description, type, searchable, exportable and filter_params. Use exportable fields in columns and searchable fields in where_sql. This is the catalogue for company requests; get_available_columns over MCP returns the broader contact-and-company catalogue.

curl -sS "https://app.getleads.io/api/v1/companies/columns" \
  -H "Authorization: Bearer $GETLEADS_API_KEY"

POST/api/v1/companies/search/count

Free distinct-company count with the same company filters as search. Returns total_matching and credits_used: 0, without company records. Count before searching or exporting.

curl -sS -X POST "https://app.getleads.io/api/v1/companies/search/count" \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_linkedin_urls":["https://www.linkedin.com/company/hubspot"]}'

{
  "ok": true,
  "total_matching": 1,
  "credits_used": 0,
  "creditsRemaining": null,
  "message": "Found 1 matching companies."
}

POST/api/v1/companies/search

Returns a companies array. REST defaults to 1,000 rows, with a 5,000-row maximum; larger limit values are clamped to 5,000. MCP search_companies defaults to 100 and rejects a limit above 100.

curl -sS -X POST "https://app.getleads.io/api/v1/companies/search" \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"company_linkedin_urls":["https://www.linkedin.com/company/hubspot"]},"columns":["company_name","company_domain","company_linkedin_url"],"limit":1}'

The response includes total_available, query_credits_used, creditsRemaining, offset, limit, returned and has_more. When has_more is true, pass the returned next_offset as the next request's offset, keeping the filters unchanged. Stop when has_more is false. Use count for the match total and export for a CSV.

REST rows use underlying field names; MCP rows and CSV headers use canonical names. The requested columns can use canonical names or display labels. The company identifier and contact_count may also appear in JSON even when not requested.

For example, the REST request above returns co_name: "HubSpot", org_domain: "hubspot.com" and current_company_linkedin_url: "https://www.linkedin.com/company/hubspot"; the equivalent MCP request returns company_name, company_domain and company_linkedin_url.

POST/api/v1/companies/search/export

Starts an asynchronous company CSV export. Pass the same company filters, optional columns, and optional max_rows (1–50,000). Costs 1 credit per company exported, subject to your plan's fair-usage limits. The initial response is 202 with export_id and job_status: "queued".

curl -sS -X POST "https://app.getleads.io/api/v1/companies/search/export" \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_linkedin_urls":["https://www.linkedin.com/company/hubspot"],"columns":["company_name","company_domain","company_linkedin_url"],"max_rows":1}'

GET/api/v1/companies/search/export/{export_id}

Poll the ID returned by the export request every few seconds while job_status is queued or running. When it is completed, download export_url. Read expires_in_seconds for the download lifetime; the current production response reports 604800 (7 days).

curl -sS "https://app.getleads.io/api/v1/companies/search/export/$EXPORT_ID" \
  -H "Authorization: Bearer $GETLEADS_API_KEY"

The completed response includes rows_exported, rows_available, query_credits_used, creditsRemaining and cap information such as rows_capped_by_credits and cap_reason. CSV headers use canonical names; parse with a CSV reader and access fields by header. The example export produces:

company_name,company_domain,company_linkedin_url
HubSpot,hubspot.com,https://www.linkedin.com/company/hubspot

GET/api/v1/companies/lookup

Look up one company's firmographic profile. Supply exactly one query parameter: domain or company_name. Supplying both returns 400. A match returns found: true and a company object; a miss returns 200 with found: false, company: null and query_credits_used: 0.

curl -sS --get "https://app.getleads.io/api/v1/companies/lookup" \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  --data-urlencode "domain=hubspot.com"

To look up by name, replace domain=hubspot.com with company_name=HubSpot. REST lookup uses the same underlying field names as company search; MCP lookup_company uses canonical names.

From companies to people

Take org_domain from REST company rows, or company_domain from MCP/CSV rows, and pass those values to contact search as domains. Add the person's role filters there:

{
  "domains": ["hubspot.com"],
  "seniority": ["c-level", "vp"],
  "limit": 10
}

Send this body to POST /api/v1/contacts/search, or pass the same flat arguments to MCP search_contacts. Use count_contacts first to size the people search.

Company MCP tools

Pass flat arguments, without a nested filters object. The same company-filter restrictions apply as over REST.

count_companies

Free total_matching count.

{"domains": ["hubspot.com"]}

search_companies

Returns a companies array with canonical field names; default/max 100 rows per call. Page with offset / next_offset.

{
  "domains": ["hubspot.com"],
  "columns": ["company_name", "company_domain", "company_linkedin_url"],
  "limit": 1
}

lookup_company

One company profile; supply exactly one of domain or company_name. Costs 1 credit on a match, 0 on a miss.

{"domain": "hubspot.com"}

export_companies

Starts a CSV export and returns export_id; costs 1 credit per company exported.

{
  "domains": ["hubspot.com"],
  "max_rows": 1,
  "confirmed": true
}

check_company_export

Polls job_status; completed includes export_url.

{"export_id": "<export_id from export_companies>"}

export_companies requires confirmed: true. The REST export example above omits this MCP-only argument. Use count_companies with the same filters first, then export and poll until complete.

Filters and values

GET /api/v1/contacts/columns returns each field's public name, description, type, searchable, exportable, filter_params and enum-lookup information. This catalogue is the current contract. Output fields and searchable fields are different sets; do not assume every returned JSON field is a filter.

GET /api/v1/contacts/filter-values?field=industries returns valid enum values. Use the requested field's documented values rather than inventing labels. MCP equivalents: get_available_columns and get_available_values.

Matching and ranges

• company_size selects size bands. employees_min/max select bands overlapping a bound; use employee_profiles_on_linkedin_min/max for exact numeric cutoffs.
• Person location and company headquarters answer different questions. Combining them requires both to match.
• Titles and keywords can have different matching rules. Read the field description, count the proposed filter and inspect a preview before exporting.
• job_start_date_min/max take literal YYYY-MM-DD dates.
• require_email requires a work email, not a personal address. require_phone requires a mobile; direct dials and company switchboards have separate filters.
• email_status accepts VALID, CATCH_ALL and UNKNOWN. VALID is the verified label; CATCH_ALL cannot confirm the individual mailbox, and UNKNOWN is not verified. Reverify before sending.
• where_sql is AND-combined with the other filters and is limited to 4,000 characters. Reference only fields marked searchable, using their catalogue names and stored values. It is for predicates, not complete SQL statements.

Response fields

The field names below are the public names to request. JSON-valued fields can contain structured lists or objects. A field can be empty when no value is known; the field count is not a promise of that many populated values on every profile. Education/certification, direct-dial and company-URL aliases are listed once here.

Contact

Contact Profile

Contact Location

Contact Job

Company Industry

Company

Company Headcount

Company Location

Company Funding

Company HQ

Company Technographics

REST response-key mapping

Request public names in columns. Read the corresponding REST JSON keys below; do not assume that every public name is also a REST property. CSV/MCP output uses the public labels.

Person enrichment — 3 ways

Match known people to the database. Each JSON endpoint takes items, up to 100 people per request. Matched profiles can include work email, phone fields, email verification metadata and current-role status where available. A match does not guarantee an email, a phone or current employment at the company in your original file.

curl -sS 'https://app.getleads.io/api/v1/enrich/from-linkedin' \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"linkedin_url":"https://www.linkedin.com/in/example/"}],"limit_per_item":1}'

Read each item's success and populated data; preserve its echoed input when joining results. profileUrl, linkedinUrl and email convenience keys can also be present. Check current_role_status before treating an old company association as current. The deprecated /enrich/batch, /enrich/batch-profile and /enrich/batch-person routes map to the corresponding LinkedIn, work-email and name/company workflows; use the named routes for new integrations.

POST/api/v1/enrich/csv

Synchronous enrichment. Send multipart file, mode and optional JSON-encoded mapping. Supported modes are linkedin (profile), work_email (email) and person; phone mode is pending. Explicit mapping supports a single-column input. Existing input columns are retained, with enrichment columns added.

curl -sS 'https://app.getleads.io/api/v1/enrich/csv' \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  -F 'file=@contacts.csv' \
  -F 'mode=linkedin' \
  -F 'mapping={"profileUrl":"LinkedIn URL"}'

The body is CSV rather than JSON. Read the X-Enrich-* headers and actual output rows when checking results. Input headers should have stable row identifiers. A synchronous request can time out on a large file, so use the background flow for large lists.

POST/api/v1/enrich/csv/async

The same multipart upload processed in the background. The initial JSON contains runId, jobStatus, rows and worstCaseCredits; the last number is an admission estimate, not the final number of matched profiles.

curl -sS 'https://app.getleads.io/api/v1/enrich/csv/async' \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  -F 'file=@contacts.csv' \
  -F 'mode=linkedin' \
  -F 'mapping={"profileUrl":"LinkedIn URL"}'

Use MCP check_enrichment_status with the returned run ID, followed by get_enrichment_result to get the CSV. The alternative MCP upload-link workflow uses create_csv_enrichment_upload_link, check_enrichment_upload, check_enrichment_status and get_enrichment_result.

Contacts lookup

POST/api/v1/contacts/lookup/colleagues

Retrieve people using an email_domain or linkedin_company_url, not both. Optional job_titles, limit_per_item and offset narrow or page the result. Defaults to 100; REST permits up to 5,000 per request. A work-email domain and the person's current employer can differ, so inspect the returned employer data when current employment matters.

POST/api/v1/contacts/lookup/decision-makers

Find senior contacts using the supported company/domain inputs. Inspect the returned titles and company data against your brief; broad seniority labels do not establish who buys your product. REST permits up to 5,000 per request; MCP lookup_decision_makers permits up to 100.

GET/api/v1/contacts/lookup/phone

Pending. Reverse lookup from a phone number currently returns HTTP 410. Phone fields on existing records remain available where populated.

POST/api/v1/contacts/from-phone

Pending. Batch reverse lookup currently returns HTTP 410. It is separate from enrichment that returns phone fields for an identified person.

Funding signals

GET /api/v1/funding/signals returns funding-news signals. Use the route's query parameters below for time, region and confidence. These news signals are separate from stored company funding fields.

Acquisition signals

GET /api/v1/acquisitions/signals returns acquisition-news signals, including acquirer, target, source and deal amount where available.

Company followers

Follower scrapes are wallet-funded at $3.50 per 1,000 followers, with a $8.75 minimum. Quote first; POST /api/v1/followers/orders places a paid order. Filters are applied during fulfilment, and the quote describes their effect on count, price and refunds. Order status and delivery are asynchronous.

REST supports quotes, orders and status. MCP lookup_company_linkedin_followers gets the free page count/quote; prepare_company_followers_checkout provides the app checkout link.

Profile monitoring

Monitoring captures engagement on public LinkedIn profiles. It uses prepaid wallet cash at $0.012 per engager. Backfill and ongoing monitoring are different billing choices; request the estimate before starting monitoring. The API also supports one-time post scrapes, profile status changes and reading captured leads. Creating a monitored profile or a post-scrape job can incur wallet charges.

Website visitor identification

Available through the GetLeads app and MCP. Identification covers US visitors, costs $0.125 per delivered lead and uses the prepaid wallet. Use the pixel tools to set up/configure tracking, complete installation and read/export identified leads. The API-key REST reference below does not expose the app's session-only visitor routes.

MCP destinations include webhooks, Smartlead visitor delivery and HeyReach live-lead routing where configured. Setting up a destination does not turn unidentified visitors into identified contacts.

REST endpoint reference

The following request parameters come from the published REST contract. Shared search-filter objects use the catalogue and filter families above. Phone lookup and CSV phone mode remain pending even though older schemas still list them.

POST/api/v1/contacts/search

Search contacts

Request body: application/json.

POST/api/v1/contacts/search/count

Count matching contacts

Request body: application/json.

POST/api/v1/contacts/search/export

Export contacts (async)

Request body: application/json.

GET/api/v1/contacts/search/export/{exportId}

Poll export status

POST/api/v1/companies/search

Search companies

Request body: application/json.

POST/api/v1/companies/search/count

Count matching companies

Request body: application/json.

GET/api/v1/companies/lookup

Look up one company

POST/api/v1/companies/search/export

Export companies to CSV

Request body: application/json.

GET/api/v1/companies/search/export/{export_id}

Poll company export

GET/api/v1/companies/columns

List company columns

GET/api/v1/contacts/filter-values

Get valid values for a filter field

GET/api/v1/contacts/columns

List selectable search columns

GET/api/v1/contacts/health

Dataset health check

GET/api/v1/contacts/lookup/phone

Pending — currently HTTP 410.

POST/api/v1/contacts/from-phone

Pending — currently HTTP 410.

POST/api/v1/contacts/lookup/colleagues

Find colleagues at a company

Request body: application/json.

POST/api/v1/contacts/lookup/decision-makers

Find decision-makers at a company

Request body: application/json.

POST/api/v1/enrich/from-linkedin

Enrich from LinkedIn URLs

Request body: application/json.

POST/api/v1/enrich/from-email

Reverse email lookup

Request body: application/json.

POST/api/v1/enrich/from-person

Enrich from name and company

Request body: application/json.

POST/api/v1/enrich/csv

Enrich CSV (sync)

Request body: multipart/form-data.

Use the shared search filters and search/export options above.

POST/api/v1/enrich/csv/async

Enrich CSV (async)

Request body: multipart/form-data.

POST/api/v1/enrich/batch

Enrich from LinkedIn (deprecated)

Deprecated alias; use the named enrichment endpoint for new integrations.

Request body: application/json.

POST/api/v1/enrich/batch-profile

Reverse email lookup (deprecated)

Deprecated alias; use the named enrichment endpoint for new integrations.

Request body: application/json.

POST/api/v1/enrich/batch-person

Enrich from name + company (deprecated)

Deprecated alias; use the named enrichment endpoint for new integrations.

Request body: application/json.

GET/api/v1/funding/signals

List funding signals

GET/api/v1/acquisitions/signals

List acquisition signals

POST/api/v1/followers/quote

Quote follower export cost

Request body: application/json.

delivery_email is required for delivery. The quote/order minimum is 2,500 leads ($8.75); use the returned quote before ordering.

GET/api/v1/followers/orders

List follower orders

POST/api/v1/followers/orders

Place follower export order

Request body: application/json.

delivery_email is required for delivery. The quote/order minimum is 2,500 leads ($8.75); use the returned quote before ordering.

GET/api/v1/followers/orders/{orderId}

Get follower order status

GET/api/v1/profile-monitoring/profiles

List monitored profiles

POST/api/v1/profile-monitoring/profiles

Add a monitored profile

Request body: application/json.

PATCH/api/v1/profile-monitoring/profiles/{profileId}

Pause or resume a monitored profile

Request body: application/json.

DELETE/api/v1/profile-monitoring/profiles/{profileId}

Remove a monitored profile

POST/api/v1/profile-monitoring/profiles/estimate

Estimate monitoring cost

Request body: application/json.

GET/api/v1/profile-monitoring/leads

List profile monitoring leads

GET/api/v1/profile-monitoring/jobs/{jobId}

Get job status

POST/api/v1/profile-monitoring/jobs/post-scrape

One-time LinkedIn post scrape

Request body: application/json.

GET/api/v1/profile-monitoring/summary

Profile monitoring account summary

GET/api/v1/usage/fair-use

Fair-use limits and credit balance

MCP tools

In your AI tool’s connector or MCP settings, add a remote server named GetLeads with URL https://app.getleads.io/api/mcp. Choose OAuth or sign-in authentication, connect, sign in to GetLeads and approve access. No API key is needed for this sign-in flow. API-key clients can instead send Bearer authentication to the same endpoint using Streamable HTTP and JSON-RPC.

There are 58 tools in the production inventory checked 29 October 2026. The current tools/list response is authoritative. MCP search filters are flat tool arguments rather than the REST filters wrapper. export_contacts and export_companies require confirmed: true. Do not copy that confirmation flag into REST requests.

Tool inventory

Contact search and exports

search_contacts, count_contacts, export_contacts, check_contact_export, get_available_columns, get_available_values.

Company search

search_companies, count_companies, lookup_company, export_companies, check_company_export.

People and enrichment

getleads_get_emails_from_linkedin_batch, getleads_get_linkedin_urls_from_emails_batch, getleads_enrich_person_batch, getleads_lookup_colleagues, lookup_decision_makers, create_csv_enrichment_upload_link, check_enrichment_upload, check_enrichment_status, get_enrichment_result, create_decision_makers_batch_link, check_decision_makers_batch, get_decision_makers_batch_result.

Signals

list_funding_signals, list_acquisition_signals.

Company followers

lookup_company_linkedin_followers, prepare_company_followers_checkout.

Profile monitoring

list_monitored_profiles, add_monitored_profile, scrape_linkedin_post_once, set_monitored_profile_active, remove_monitored_profile, list_profile_monitoring_leads, get_profile_monitoring_handoff_prompt.

Website visitors

list_website_pixels, start_website_visitor_tracking, configure_website_pixel, configure_website_visitors_smartlead, complete_website_pixel_setup, set_website_pixel_status, delete_website_pixel, list_website_visitor_leads, export_website_visitor_leads.

HeyReach

configure_heyreach, list_heyreach_destinations, send_contacts_to_heyreach, check_heyreach_send, create_heyreach_campaign, configure_live_leads_heyreach, enrich_heyreach_leads, get_heyreach_campaign.

Account and wallet

getleads_health, getleads_contacts_health, get_fair_use, get_wallet_balance, estimate_scrape_cost, create_topup_link, configure_auto_topup.

Calling a tool from an API client

curl -sS 'https://app.getleads.io/api/mcp' \
  -H "Authorization: Bearer $GETLEADS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_available_columns","arguments":{}}}'

The response can be JSON or an event stream. For event streams, read the JSON-RPC result with your request ID rather than assuming the first event contains it.

Paging search results over MCP

search_contacts and search_companies return up to 100 rows per call. Follow has_more and next_offset; use the relevant free count tool for audience size and export tools for CSVs. export_companies has its own poll tool, check_company_export.

For agent workflows, see thinking-mode, company-list and get-everyone.