POST

companies

curl --request POST \
  --url https://api.leadmagic.io/v3/companies/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "company_domain": "leadmagic.io"
}
'

{
  "message": "<string>",
  "credits_consumed": 123,
  "companies": [
    {}
  ],
  "found": true,
  "company": {},
  "companyName": "<string>",
  "companyDomain": "<string>",
  "websiteUrl": "<string>",
  "linkedinUrl": "<string>",
  "count": 123,
  "returned_count": 123,
  "limit_applied": 123,
  "offset": 123,
  "interpreted_search": {},
  "metadata": {}
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/validation_error",
      "title": "Request validation failed. Check your input parameters.",
      "status": 400,
      "code": "validation_error",
      "param": [
        "email"
      ],
      "detail": "Email format is invalid. Expected format: user@domain.com",
      "action": "Provide a valid email address in the 'email' field.",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/missing_authentication",
      "title": "Authentication required. Provide a valid API key in the X-API-Key header (case-insensitive).",
      "status": 401,
      "code": "missing_authentication",
      "docs": "https://leadmagic.io/docs/api-reference/authentication"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/insufficient_credits",
      "title": "Insufficient credits: need 5, have 2.50. Add credits to continue.",
      "status": 402,
      "code": "insufficient_credits",
      "detail": "This request requires 5 credit(s) but your account only has 2.50 credits remaining.",
      "action": "Add credits to your account at https://app.leadmagic.io/billing or contact support@leadmagic.io for enterprise plans.",
      "docs": "https://leadmagic.io/docs/api-reference/credits",
      "context": {
        "credits_required": 5,
        "credits_available": 2.5,
        "credits_needed": 2.5
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/rate_limit_exceeded",
      "title": "Rate limit exceeded: 300 requests per 1 minute. Wait and try again.",
      "status": 429,
      "code": "rate_limit_exceeded",
      "detail": "You have exceeded the maximum allowed request rate. Please wait before making additional requests.",
      "action": "Wait 42 seconds before retrying. Consider implementing exponential backoff.",
      "docs": "https://leadmagic.io/docs/api-reference/rate-limits",
      "context": {
        "limit": 300,
        "window": "1 minute",
        "remaining": 0,
        "reset_at": 1706745642,
        "retry_after_seconds": 42
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

Company Search

POST /v3/companies/search is the single V3 company lookup endpoint for building and paging through account lists from structured criteria. Use Company Search for both one-company lookup and filtered company lists. Send a single identifier such as company_domain, domain, website, company_name, profile_url, or linkedin_url for one company, or use company_filters for account lists.

Existing clients that send one-company search bodies such as company_domain, domain, website, company_name, profile_url, or linkedin_url can keep using the same request shape. When no broad filters or explicit limit are supplied, the API treats the request as a one-row lookup and returns the richer company record plus legacy-friendly aliases such as companyName, companyDomain, and websiteUrl.

You can pass multiple company identities at once using company_domains, company_websites, B2B company profile inputs, and company_names. Those identity filters are treated as alternatives, then the rest of your filters narrow the matched set.

Endpoint Details

Pricing
Rate Limits

Metric	Value
Search	1 credit per returned company
No results	FREE
Page cap	`limit` max is `50`; use `offset` for pagination

Credits finalize by returned company count, not by requested limit.

Metric	Value
Requests/Minute	500
Burst Capacity	Subject to workspace limits

Quick Examples

Use one of the patterns below. They hit the same endpoint but return different response shapes.

One company lookup
Filtered company list

Send a single company identifier at the request root. Do not include company_filters, query, or limit unless you want list mode.

curl -X POST 'https://api.leadmagic.io/v3/companies/search' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_domain": "leadmagic.io"
  }'

const response = await fetch('https://api.leadmagic.io/v3/companies/search', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    company_domain: 'leadmagic.io'
  })
});

const data = await response.json();
console.log(data.companyName, data.company?.company_domain);

import requests

response = requests.post(
    'https://api.leadmagic.io/v3/companies/search',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'company_domain': 'leadmagic.io'}
)

data = response.json()
print(data.get('companyName'), data.get('company', {}).get('company_domain'))

Accepted root fields: company_domain (preferred), domain, website, company_name, profile_url, linkedin_url (and aliases listed below).Response extras: found, company, companyName, companyDomain, websiteUrl, linkedinUrl plus companies[] with one row.

Send structured filters to build or page through an account list.

curl -X POST 'https://api.leadmagic.io/v3/companies/search' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "limit": 10,
    "offset": 0,
    "company_filters": {
      "company_domains": ["leadmagic.io"],
      "country_codes": ["US"],
      "min_total_contacts": 1
    }
  }'

const response = await fetch('https://api.leadmagic.io/v3/companies/search', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    limit: 10,
    offset: 0,
    company_filters: {
      company_domains: ['leadmagic.io'],
      country_codes: ['US'],
      min_total_contacts: 1
    }
  })
});

const data = await response.json();
console.log(`${data.count} companies`);

import requests

response = requests.post(
    'https://api.leadmagic.io/v3/companies/search',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'limit': 10,
        'offset': 0,
        'company_filters': {
            'company_domains': ['leadmagic.io'],
            'country_codes': ['US']
        }
    }
)

data = response.json()
print(f"{data['count']} companies")

Response focus: companies[], count, limit_applied, offset, interpreted_search. Legacy single-company aliases are omitted in list mode.

Adding limit, company_filters, or query switches the request to list mode. For a single-company lookup, send only identity fields such as company_domain or linkedin_url.

Request Body

string

One-company lookup: company domain (preferred). Aliases: domain, website, company_website.

string

One-company lookup: company name. Aliases: name.

string

One-company lookup: B2B company profile URL. Aliases: linkedin_url, company_linkedin_url, company_url, url.

object

List search: primary filter object. You may also send the same fields inside filters or at the request root; company_filters is preferred for new integrations.

string

Optional natural-language/company keyword query. Use structured fields when you know the exact filters.

integer

default:"10"

Number of companies to return. Maximum is 50 for this public API route.

integer

default:"0"

Offset for pagination. Increase by limit to fetch the next page.

Company Identity Filters

Field	Type	Matching behavior
`company_domains`	`string[]`	Exact normalized domain match, e.g. `leadmagic.io`
`company_websites`	`string[]`	Normalized to domain-equivalent exact matches
`linkedin_urls`	`string[]`	Exact normalized B2B company profile matches
`company_names`	`string[]`	Exact case-insensitive company name match
`company_domain`	`string`	Single-value alias for `company_domains`
`company_website` / `website`	`string`	Single-value aliases for `company_websites`
`linkedin_url` / `company_linkedin_url`	`string`	Single-value aliases for B2B company profile inputs
`company_name` / `name`	`string`	Single-value aliases for company name search

Firmographic Filters

Field	Type	Description
`country_codes` / `country_code`	`string[]` / `string`	HQ country codes such as `US`, `GB`, `CA`
`industries` / `industry`	`string[]` / `string`	B2B industry labels
`employee_ranges` / `employee_range`	`string[]` / `string`	Ranges such as `51 to 200`, `201 to 500`, `10001+`
`min_employees`	`integer`	Minimum employee count/range overlap
`max_employees`	`integer`	Maximum employee count/range overlap
`revenue_ranges` / `revenue_range`	`string[]` / `string`	Revenue labels such as `$10M to <$50M`
`min_revenue`	`integer`	Minimum revenue
`max_revenue`	`integer`	Maximum revenue
`founded_after`	`integer`	Minimum founded year
`founded_before`	`integer`	Maximum founded year
`company_entity_types`	`string[]`	Legal/company entity type labels
`domain_tlds`	`string[]`	Domain TLDs such as `io`, `com`, `ai`

Location Filters

Field	Type
`hq_countries`	`string[]`
`hq_regions`	`string[]`
`hq_cities`	`string[]`
`hq_states`	`string[]`
`hq_continents`	`string[]`
`hq_streets`	`string[]`
`hq_postcodes`	`string[]`

Funding Filters

Field	Type	Description
`has_funding`	`boolean`	Require or exclude companies with known funding
`min_total_funding` / `max_total_funding`	`integer`	Funding amount bounds
`last_funding_types`	`string[]`	Funding round/type labels
`last_funding_after` / `last_funding_before`	`string`	Date bounds for last funding
`min_funding_investor_count` / `max_funding_investor_count`	`integer`	Investor-count bounds
`lead_investors`	`string[]`	Fuzzy lead investor text search

Contact Coverage Filters

Field	Type
`min_total_contacts` / `max_total_contacts`	`integer`
`min_contacts_with_email` / `max_contacts_with_email`	`integer`
`min_contacts_with_phone` / `max_contacts_with_phone`	`integer`
`min_valid_email_count` / `max_valid_email_count`	`integer`

Technology Filters

Field	Type	Description
`has_tech_stack`	`boolean`	Require a detected tech stack
`tech_stack` / `technologies`	`string[]`	Generic technology search across indexed tech/specialty columns
`crm_tech`	`string[]`	CRM technologies
`marketing_automation_tech`	`string[]`	Marketing automation
`sales_automation_tech`	`string[]`	Sales automation
`analytics_tech`	`string[]`	Analytics tools
`cloud_provider_tech`	`string[]`	Cloud platforms such as AWS, GCP, Azure
`development_tech`	`string[]`	Development frameworks/tools
`ecommerce_tech`	`string[]`	Ecommerce platforms
`erp_tech`	`string[]`	ERP platforms
`email_hosting_tech`	`string[]`	Email hosting
`email_security_tech`	`string[]`	Email security
`abm_tech`	`string[]`	ABM tools
`cms_tech`	`string[]`	CMS tools
`conversation_intelligence_tech`	`string[]`	Conversation intelligence tools
`app_security_tech`	`string[]`	Application security tools
`cloud_security_tech`	`string[]`	Cloud security tools
`company_martech`	`string[]`	Marketing technology

Text And Classification Filters

Field	Type
`keyword`	`string`
`specialties`	`string[]`
`company_headlines`	`string[]`
`company_about`	`string[]`
`company_phones`	`string[]`
`sic_codes`	`string[]`
`naics_codes`	`string[]`
`sic_descriptions`	`string[]`
`naics_descriptions`	`string[]`

Website Filters

Field	Type
`website_active`	`boolean`
`website_for_sale`	`boolean`
`min_total_app_reviews` / `max_total_app_reviews`	`integer`

Sort

Field	Type	Values
`sort_by`	`string`	`company_domain`, `total_funding`, `founded_year`, `total_contacts`
`sort_order`	`string`	`asc`, `desc`

Response

object[]

Company records matching your criteria.

object

Present for one-company lookup requests. Contains the first returned company record.

boolean

Present for one-company lookup requests. true when a company row was returned.

string

Present for one-company lookup requests. Alias for company.company_name.

string

Present for one-company lookup requests. Alias for company.company_domain.

string

Present for one-company lookup requests. Alias for company.company_website.

string

Present for one-company lookup requests. Alias for company.linkedin_url.

integer

Number of companies returned.

integer

Alias for count.

integer

Applied page size.

integer

Applied offset.

number

Finalized credits charged (1 per returned company; 0 when no companies match).

object

Normalized filters used by the backend.

Example Responses

{
  "message": "Companies found",
  "credits_consumed": 1,
  "found": true,
  "companyName": "LeadMagic",
  "companyDomain": "leadmagic.io",
  "websiteUrl": "https://leadmagic.io",
  "company": {
    "company_domain": "leadmagic.io",
    "company_name": "LeadMagic"
  },
  "companies": [
    {
      "company_domain": "leadmagic.io",
      "company_name": "LeadMagic"
    }
  ],
  "count": 1,
  "returned_count": 1,
  "limit_applied": 1,
  "offset": 0
}

{
  "message": "Companies found",
  "credits_consumed": 1,
  "companies": [
    {
      "company_domain": "leadmagic.io",
      "company_name": "LeadMagic",
      "hq_country_code": "US"
    }
  ],
  "count": 1,
  "returned_count": 1,
  "limit_applied": 10,
  "offset": 0,
  "interpreted_search": {
    "company_filters": {
      "company_domains": ["leadmagic.io"],
      "country_codes": ["US"]
    }
  }
}

Returned company rows can include: company_domain, company_name, company_website, company_industry_linkedin, employee_range, employee_min, employee_max, revenue_range, revenue_min, revenue_max, hq_country, hq_country_code, hq_city, hq_state, hq_street, hq_postcode, hq_region, hq_continent, founded_year, category, specialties, total_funding, funding_investor_count, last_funding_type, last_funding_date, last_funding_amount, lead_investors, linkedin_url, company_headline, company_about, company_logo_url, company_phone, company_entity_type, has_tech_stack, total_contacts, contacts_with_email, contacts_with_phone, valid_email_count, website_active, website_for_sale, sic_code, naics_code, sic_description, naics_description, domain_tld, total_app_reviews, and all technology columns listed above.

Company Lookalike

Find similar accounts from a seed company and return the same full company row shape.

Technographics

Get detailed technology stack information for one company.

People Search

Search contacts across one company or a filtered company set.

Authorizations

X-API-Key

string

header

required

Your LeadMagic API key. Header name is case-insensitive (X-API-Key, X-API-KEY, x-api-key all work).

Body

application/json

company_domain

string

Direct one-company lookup input. Returns one rich company row plus legacy-friendly aliases when no broad filters or explicit limit are supplied.

Example:

"leadmagic.io"

domain

string

Alias for company_domain.

website

string

Company website URL or domain.

company_name

string

Company name lookup input.

profile_url

string

Company profile URL.

linkedin_url

string

Company profile URL.

company_filters

object

Full company filter object.

query

string

limit

integer

default:10

Required range: 1 <= x <= 50

offset

integer

default:0

Required range: x >= 0

Response

Company search results

message

string

credits_consumed

number

companies

object[]

found

boolean

Present for one-company lookup requests.

company

object | null

Present for one-company lookup requests. Contains the first returned company row.

companyName

string | null

Present for one-company lookup requests. Alias for company.company_name.

companyDomain

string | null

Present for one-company lookup requests. Alias for company.company_domain.

websiteUrl

string | null

Present for one-company lookup requests. Alias for company.company_website.

linkedinUrl

string | null

Present for one-company lookup requests. Alias for company.linkedin_url.

count

integer

returned_count

integer

limit_applied

integer

offset

integer

interpreted_search

object

metadata

object

curl --request POST \
  --url https://api.leadmagic.io/v3/companies/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "company_domain": "leadmagic.io"
}
'

{
  "message": "<string>",
  "credits_consumed": 123,
  "companies": [
    {}
  ],
  "found": true,
  "company": {},
  "companyName": "<string>",
  "companyDomain": "<string>",
  "websiteUrl": "<string>",
  "linkedinUrl": "<string>",
  "count": 123,
  "returned_count": 123,
  "limit_applied": 123,
  "offset": 123,
  "interpreted_search": {},
  "metadata": {}
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/validation_error",
      "title": "Request validation failed. Check your input parameters.",
      "status": 400,
      "code": "validation_error",
      "param": [
        "email"
      ],
      "detail": "Email format is invalid. Expected format: user@domain.com",
      "action": "Provide a valid email address in the 'email' field.",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/missing_authentication",
      "title": "Authentication required. Provide a valid API key in the X-API-Key header (case-insensitive).",
      "status": 401,
      "code": "missing_authentication",
      "docs": "https://leadmagic.io/docs/api-reference/authentication"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/insufficient_credits",
      "title": "Insufficient credits: need 5, have 2.50. Add credits to continue.",
      "status": 402,
      "code": "insufficient_credits",
      "detail": "This request requires 5 credit(s) but your account only has 2.50 credits remaining.",
      "action": "Add credits to your account at https://app.leadmagic.io/billing or contact support@leadmagic.io for enterprise plans.",
      "docs": "https://leadmagic.io/docs/api-reference/credits",
      "context": {
        "credits_required": 5,
        "credits_available": 2.5,
        "credits_needed": 2.5
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/rate_limit_exceeded",
      "title": "Rate limit exceeded: 300 requests per 1 minute. Wait and try again.",
      "status": 429,
      "code": "rate_limit_exceeded",
      "detail": "You have exceeded the maximum allowed request rate. Please wait before making additional requests.",
      "action": "Wait 42 seconds before retrying. Consider implementing exponential backoff.",
      "docs": "https://leadmagic.io/docs/api-reference/rate-limits",
      "context": {
        "limit": 300,
        "window": "1 minute",
        "remaining": 0,
        "reset_at": 1706745642,
        "retry_after_seconds": 42
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

Get Started

API Endpoints

MCP Server

CLI

Company Search

Company Search

Endpoint Details

Quick Examples

Request Body

Company Identity Filters

Firmographic Filters

Location Filters

Funding Filters

Contact Coverage Filters

Technology Filters

Text And Classification Filters

Website Filters

Sort

Response

Example Responses

Company Lookalike

Technographics

People Search

Authorizations

Body

Response

​Company Search

​Endpoint Details

​Quick Examples

​Request Body

​Company Identity Filters

​Firmographic Filters

​Location Filters

​Funding Filters

​Contact Coverage Filters

​Technology Filters

​Text And Classification Filters

​Website Filters

​Sort

​Response

​Example Responses

​Related endpoints

Company Lookalike

Technographics

People Search

Authorizations

Body

Response

Company Search

Endpoint Details

Quick Examples

Request Body

Company Identity Filters

Firmographic Filters

Location Filters

Funding Filters

Contact Coverage Filters

Technology Filters

Text And Classification Filters

Website Filters

Sort

Response

Example Responses

Related endpoints