Search Companies

Searches LinkedIn company pages live and returns one page of companies. A name condition is required; add one location condition to narrow it down.

filters is one condition, or { "op": "and", "conditions": [...] } with one name condition and one location condition. A condition is { "field", "type", "value" }:

• basic_info.name with (.) (contains, in the source's relevance order, an exact name first) or = (only companies with exactly this name).
• locations.country with = (one country name in English, e.g. Belgium; an ISO code such as BE works too) or in (a list with one country).
• locations.headquarters with =: a city or region in English, e.g. Ghent.

Search returns company cards: name, LinkedIn URL, description, logo, headquarters, industry and followers. Headcount, website, funding and hiring are not in the search results; call Enrich Companies with the linkedin_url for those. Page through with next_cursor.

Send Authorization: Bearer gtk_…. Create the key under API Access → API Keys. A missing, invalid or revoked key is 401, including while this API is closed. A valid key while the API is closed for your organization answers 404, the same body as an unknown path. Every response includes FounderMCP-Api-Version and FounderMCP-Request-Id.

Authentication

Send your API key as a Bearer token: Authorization: Bearer gtk_…. Create the key under API Access → API Keys. A missing, invalid or revoked key is 401, including while an API is closed. A valid key while the Signals API or the Company API is closed for your organization answers 404, the same body as an unknown path. Every response includes FounderMCP-Api-Version and FounderMCP-Request-Id.

Body parameters

• filters object · required — One condition, or an and group of a name condition and a location condition.
• fields string[] — Groups to return on each card. Defaults to all four. One of: basic_info, locations, taxonomy, followers.
• limit integer — Companies to return, 1 to 25. Defaults to 10.
• cursor string — The next_cursor of the previous response.

Response

• companies object[] — The companies on this page, in the source's order.
• companies[].linkedin_url string — The company page: the stable identifier, and the input for Enrich Companies.
• companies[].basic_info object — name, linkedin_url, description, logo_url.
• companies[].locations object — headquarters, as LinkedIn shows it.
• companies[].taxonomy object — industry.
• companies[].followers object — count.
• next_cursor string | null — The next page, or null on the last page.
• total_count integer | null — The total the source reports for this search, when it reports one.
• credits_used integer — Credits this call used: one per returned company.

Credits

1 credit per returned company Errors and empty lookups are free. A call that spent credits puts that number in credits_used, in X-Credits-Used and in X-Credits-Charged. When the wallet can be read, the response also sends X-Credits-Remaining.

Errors

• 400 invalid_request — The body is not valid JSON, a field is unknown or has the wrong type, or a value is not allowed.
• 401 authentication_error — The Authorization header is missing, or the key is unknown or revoked.
• 403 permission_error — API access is not part of your plan, or your account is suspended.
• 429 rate_limit_error — More than 60 requests per minute, or more than 3 at the same time, on one key. Wait for the Retry-After header.
• 429 daily_limit_reached — The request could take your organization over its daily credit limit. The limit resets at midnight (Europe/Brussels).
• 502 upstream_error — The data source did not answer. Retry later.
• 503 service_unavailable — The API is temporarily unavailable. Retry later.
• 500 internal_error — Something went wrong on our side.

Example

cURL

curl -X POST "https://foundermcp.dev/api/v1/company/search" \
  -H "Authorization: Bearer $FOUNDERMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "op": "and",
      "conditions": [
        {
          "field": "basic_info.name",
          "type": "(.)",
          "value": "Acme"
        },
        {
          "field": "locations.country",
          "type": "=",
          "value": "Belgium"
        }
      ]
    },
    "limit": 10
  }'

JavaScript

const response = await fetch('https://foundermcp.dev/api/v1/company/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUNDERMCP_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "filters": {
      "op": "and",
      "conditions": [
        {
          "field": "basic_info.name",
          "type": "(.)",
          "value": "Acme"
        },
        {
          "field": "locations.country",
          "type": "=",
          "value": "Belgium"
        }
      ]
    },
    "limit": 10
  })
});
const body = await response.json();

Python

import json
import os
import urllib.request

payload = {
  "filters": {
    "op": "and",
    "conditions": [
      {
        "field": "basic_info.name",
        "type": "(.)",
        "value": "Acme"
      },
      {
        "field": "locations.country",
        "type": "=",
        "value": "Belgium"
      }
    ]
  },
  "limit": 10
}

request = urllib.request.Request(
    "https://foundermcp.dev/api/v1/company/search",
    headers={
    "Authorization": f"Bearer {os.environ['FOUNDERMCP_API_KEY']}",
    "Content-Type": "application/json"
    },
    data=json.dumps(payload).encode(),
    method="POST",
)
with urllib.request.urlopen(request) as response:
    body = json.load(response)

Example response

{
  "companies": [
    {
      "linkedin_url": "https://www.linkedin.com/company/acme-analytics",
      "basic_info": {
        "name": "Acme Analytics",
        "linkedin_url": "https://www.linkedin.com/company/acme-analytics",
        "description": "Analytics for finance teams.",
        "logo_url": null
      },
      "locations": {
        "headquarters": "Ghent, Flemish Region"
      },
      "taxonomy": {
        "industry": "Software Development"
      },
      "followers": {
        "count": 1204
      }
    }
  ],
  "next_cursor": "eyJwIjoyfQ",
  "total_count": 14,
  "credits_used": 1
}