# 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.

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

```bash
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

```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

```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

```json
{
  "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
}
```