> ## Documentation Index > Fetch the complete documentation index at: https://leadmagic.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Company Search > Canonical V3 company lookup with all company filters. # 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. > [!NOTE] > > 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`. > [!TIP] > > 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 > [tab] Pricing > > | Metric | Value | > | - | - | > | **Search** | **1 credit** per returned company | > | **No results** | **FREE** | > | **Page cap** | `limit` max is `50`; use `offset` for pagination | > > > [!TIP] > > > > Credits finalize by returned company count, not by requested limit. > [tab] Rate Limits > > | 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. > [tab] One company lookup > > Send a single company identifier at the request root. Do **not** include `company_filters`, `query`, or `limit` unless you want list mode. > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > 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" > }' > ``` > > ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}} > 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); > ``` > > ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} > 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. > [tab] Filtered company list > > Send structured filters to build or page through an account list. > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > 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 > } > }' > ``` > > ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}} > 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`); > ``` > > ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} > 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. > [!WARNING] > > 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 **company\_domain** `string` One-company lookup: company domain (preferred). Aliases: `domain`, `website`, `company_website`. **company\_name** `string` One-company lookup: company name. Aliases: `name`. **profile\_url** `string` One-company lookup: B2B company profile URL. Aliases: `linkedin_url`, `company_linkedin_url`, `company_url`, `url`. **company\_filters** `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. **query** `string` Optional natural-language/company keyword query. Use structured fields when you know the exact filters. **limit** `integer` (default: 10) Number of companies to return. Maximum is `50` for this public API route. **offset** `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 **companies** `object[]` Company records matching your criteria. **company** `object` Present for one-company lookup requests. Contains the first returned company record. **found** `boolean` Present for one-company lookup requests. `true` when a company row was returned. **companyName** `string` Present for one-company lookup requests. Alias for `company.company_name`. **companyDomain** `string` Present for one-company lookup requests. Alias for `company.company_domain`. **websiteUrl** `string` Present for one-company lookup requests. Alias for `company.company_website`. **linkedinUrl** `string` Present for one-company lookup requests. Alias for `company.linkedin_url`. **count** `integer` Number of companies returned. **returned\_count** `integer` Alias for `count`. **limit\_applied** `integer` Applied page size. **offset** `integer` Applied offset. **credits\_consumed** `number` Finalized credits charged (1 per returned company; `0` when no companies match). **interpreted\_search** `object` Normalized filters used by the backend. ### Example Responses ```json One company lookup theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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 } ``` ```json Filtered company list theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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. ## Related endpoints > [card] [Company Lookalike](https://leadmagic.io/docs/v1/reference/company-lookalike.md) > > Find similar accounts from a seed company and return the same full company row shape. > [card] [Technographics](https://leadmagic.io/docs/v1/reference/technographics.md) > > Get detailed technology stack information for one company. > [card] [People Search](https://leadmagic.io/docs/v1/reference/people-search.md) > > Search contacts across one company or a filtered company set. ## OpenAPI ````yaml post /v3/companies/search openapi: 3.1.0 info: title: LeadMagic API version: 1.4.34 description: > # LeadMagic API Documentation The LeadMagic API provides comprehensive B2B data enrichment services including email validation, email finding, profile search, company intelligence, and more. ## Quick Start 1. Get your API key from the [LeadMagic Dashboard](https://app.leadmagic.io) 2. Add the `X-API-Key` header to all requests 3. Start enriching your data! ## Base URL All API requests should be made to: `https://api.leadmagic.io` ## Rate Limits Each endpoint has specific rate limits (requests per minute). Exceeding limits returns a `429 Too Many Requests` response. ## Credits API calls consume credits based on the endpoint used. Check your balance with the `/v1/credits` endpoint. ## Support Contact us at support@leadmagic.io for assistance. contact: name: LeadMagic Support email: support@leadmagic.io url: https://leadmagic.io termsOfService: https://leadmagic.io/legal/terms servers: - url: https://api.leadmagic.io description: Production API Server security: - ApiKeyAuth: [] tags: - name: Credits description: Manage and check your credit balance - name: Analytics description: >- Monitor your API usage with comprehensive analytics endpoints (FREE - no credits consumed) - name: People Enrichment description: Find and validate contact information for individuals - name: Company Data description: Discover company information and intelligence - name: Jobs Data description: Search job listings and detect career changes - name: Ads Data description: Search advertising data across platforms paths: /v3/companies/search: post: tags: - Company Data summary: Company Search description: > Canonical V3 company endpoint. Supports two request shapes on the same path: 1. **One-company lookup** — send a single identity field at the root (`company_domain`, `domain`, `website`, `company_name`, `profile_url`, or `linkedin_url`) without `company_filters`, `query`, or an explicit `limit`. Returns one row plus legacy aliases (`found`, `company`, `companyName`, `companyDomain`, `websiteUrl`, `linkedinUrl`). 2. **Filtered company list** — send `company_filters` (and optional `limit`, `offset`) to page through matching accounts. operationId: company-search-v3 requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: company_domain: type: string description: >- 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: type: string description: Alias for company_domain. website: type: string description: Company website URL or domain. company_name: type: string description: Company name lookup input. profile_url: type: string description: Company profile URL. linkedin_url: type: string description: Company profile URL. company_filters: type: object additionalProperties: true description: Full company filter object. query: type: string limit: type: integer minimum: 1 maximum: 50 default: 10 offset: type: integer default: 0 minimum: 0 examples: oneCompanyLookup: summary: One company lookup description: >- Send only identity fields. Omit limit unless you want list mode. value: company_domain: leadmagic.io filteredCompanyList: summary: Filtered company list description: Use company_filters to build or page through account lists. value: limit: 10 offset: 0 company_filters: company_domains: - leadmagic.io country_codes: - US crm_tech: - Salesforce example: company_domain: leadmagic.io responses: '200': description: Company search results content: application/json: schema: type: object additionalProperties: true properties: message: type: string credits_consumed: type: number companies: type: array items: type: object additionalProperties: true found: type: boolean description: Present for one-company lookup requests. company: type: object nullable: true additionalProperties: true description: >- Present for one-company lookup requests. Contains the first returned company row. companyName: type: string nullable: true description: >- Present for one-company lookup requests. Alias for company.company_name. companyDomain: type: string nullable: true description: >- Present for one-company lookup requests. Alias for company.company_domain. websiteUrl: type: string nullable: true description: >- Present for one-company lookup requests. Alias for company.company_website. linkedinUrl: type: string nullable: true description: >- Present for one-company lookup requests. Alias for company.linkedin_url. count: type: integer returned_count: type: integer limit_applied: type: integer offset: type: integer interpreted_search: type: object additionalProperties: true metadata: type: object additionalProperties: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '429': $ref: '#/components/responses/RateLimitExceeded' components: responses: BadRequest: description: | Bad Request - The request was malformed or contains invalid parameters. **Common causes:** - Missing required fields - Invalid field format (e.g., malformed email) - Invalid JSON syntax - Invalid parameter values content: application/problem+json: schema: $ref: '#/components/schemas/ValidationError' Unauthorized: description: | Unauthorized - Authentication failed. **Common causes:** - Missing X-API-Key header - Invalid or expired API key - Malformed API key content: application/problem+json: schema: oneOf: - $ref: '#/components/schemas/MissingAuthenticationError' - $ref: '#/components/schemas/InvalidApiKeyError' PaymentRequired: description: > Payment Required - Insufficient credits for this request. **Action required:** Add credits to your account at https://app.leadmagic.io/billing content: application/problem+json: schema: $ref: '#/components/schemas/InsufficientCreditsError' RateLimitExceeded: description: | Too Many Requests - Rate limit exceeded. **Action required:** Check the `Retry-After` header for when to retry. **Headers returned:** - `Retry-After`: Seconds until you can retry - `RateLimit-Limit`: Your limit per minute - `RateLimit-Remaining`: Remaining requests this minute - `RateLimit-Reset`: Seconds until limit resets headers: Retry-After: schema: type: integer description: Seconds to wait before retrying RateLimit-Limit: schema: type: integer description: Maximum requests per minute RateLimit-Remaining: schema: type: integer description: Remaining requests this minute RateLimit-Reset: schema: type: integer description: Seconds until limit resets content: application/problem+json: schema: $ref: '#/components/schemas/RateLimitExceededError' schemas: ValidationError: allOf: - $ref: '#/components/schemas/ErrorResponse' example: 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' MissingAuthenticationError: allOf: - $ref: '#/components/schemas/ErrorResponse' example: 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' InvalidApiKeyError: allOf: - $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - type: https://api.leadmagic.io/errors/invalid_api_key title: Invalid API key. The key does not exist or is incorrect. status: 401 code: invalid_api_key docs: https://leadmagic.io/docs/api-reference/authentication meta: request_id: ea6e3248-f4d2-437d-bca3-20881b529129 timestamp: '2024-02-01T12:00:00.000Z' InsufficientCreditsError: allOf: - $ref: '#/components/schemas/ErrorResponse' example: 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' RateLimitExceededError: allOf: - $ref: '#/components/schemas/ErrorResponse' example: 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' ErrorResponse: type: object description: RFC 9457 Problem Details error response required: - success - errors properties: success: type: boolean example: false description: Always false for error responses errors: type: array description: Array of error details (typically one, but can be multiple) items: $ref: '#/components/schemas/ErrorDetail' meta: $ref: '#/components/schemas/ResponseMeta' ErrorDetail: type: object description: RFC 9457 compliant error detail required: - type - title - status properties: type: type: string format: uri description: RFC 9457 - URI reference identifying the error type example: https://api.leadmagic.io/errors/validation_error title: type: string description: RFC 9457 - Short human-readable summary example: Request validation failed. Check your input parameters. status: type: integer description: RFC 9457 - HTTP status code example: 400 detail: type: string description: RFC 9457 - Human-readable explanation specific to this occurrence example: The email field is required but was not provided. instance: type: string format: uri description: RFC 9457 - URI reference for this specific occurrence example: /v1/people/email-validation#req_abc123 code: type: string description: Machine-readable error code for programmatic handling example: validation_error param: type: array description: Parameters that caused the error items: type: string example: - email action: type: string description: Suggested action to resolve the error example: Provide a valid email address in the 'email' field. docs: type: string format: uri description: Link to relevant documentation example: https://leadmagic.io/docs/api-reference/errors context: type: object description: Additional context specific to this error type additionalProperties: true ResponseMeta: type: object description: Metadata included in all responses properties: request_id: type: string format: uuid description: Unique identifier for this request (use for debugging/support) example: ea6e3248-f4d2-437d-bca3-20881b529129 timestamp: type: string format: date-time description: ISO 8601 timestamp when the response was generated example: '2024-02-01T12:00:00.000Z' environment: type: string description: API environment (production, staging) example: production securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- Your LeadMagic API key. Header name is case-insensitive (X-API-Key, X-API-KEY, x-api-key all work). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.