Enrich Companies

Send exactly one of linkedin_urls, domains or names, with up to 25 entries. Each entry gets its own result, in the order you sent them, with a list of matches.

A LinkedIn URL or a domain gives at most one company. A name can give up to 5, because companies share names; confidence_score is 1.0 on an exact name and null otherwise. Set exact_match to keep only exact names (or, for domains, only a company on exactly that domain).

fields picks the groups: basic_info (the default), headcount, locations, taxonomy, followers, funding and hiring. A value we cannot fill is null, and its path is listed in unavailable, so you can tell "unknown" from "zero".

Every company found costs one credit, whatever groups you ask for; the open roles in hiring are included. Not found, invalid or failed entries cost nothing.

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

• linkedin_urls string[] — LinkedIn company pages, e.g. https://www.linkedin.com/company/acme-analytics.
• domains string[] — Company websites or domains, e.g. acme-analytics.example.
• names string[] — Company names.
• fields string[] — Groups to return. Defaults to ["basic_info"]. One of: basic_info, headcount, locations, taxonomy, followers, funding, hiring.
• exact_match boolean — Names: keep only exact names. Domains: keep only a company on exactly that domain. Defaults to false.

Response

• results object[] — One entry per input, in the same order.
• results[].input string — The input as you sent it.
• results[].status string — matched, not_found, invalid (not a LinkedIn company URL, domain or name) or error (lookup failed; retry later). One of: matched, not_found, invalid, error.
• results[].match_type string — linkedin_url, domain or name. One of: linkedin_url, domain, name.
• results[].matches object[] — confidence_score and company; empty unless the status is matched.
• company.linkedin_url string | null — The company page.
• company.basic_info object — name, linkedin_url, website, primary_domain, description, tagline, logo_url, employee_count_range, company_type, year_founded.
• company.headcount object — total (employees on LinkedIn) and range. Growth, role mix and region mix are null and listed in unavailable.
• company.locations object — headquarters, city, state, country, country_code, street_address, postal_code and all_office_addresses.
• company.taxonomy object — industry and specialities.
• company.followers object — count. Follower growth is null and listed in unavailable.
• company.funding object — last_round_type, last_round_amount_usd, last_fundraise_date, investors and rounds (newest first), from the funding rounds we track.
• company.hiring object — openings_count (open roles on LinkedIn) and recent_openings: the newest roles, with title, url, location and posted_on.
• company.unavailable string[] — Paths in the requested groups that this API cannot fill for this company.
• credits_used integer — Credits this call used.

Credits

1 credit per company found 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/enrich" \
  -H "Authorization: Bearer $FOUNDERMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": [
      "https://www.linkedin.com/company/acme-analytics"
    ],
    "fields": [
      "basic_info",
      "headcount"
    ]
  }'

JavaScript

const response = await fetch('https://foundermcp.dev/api/v1/company/enrich', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUNDERMCP_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "linkedin_urls": [
      "https://www.linkedin.com/company/acme-analytics"
    ],
    "fields": [
      "basic_info",
      "headcount"
    ]
  })
});
const body = await response.json();

Python

import json
import os
import urllib.request

payload = {
  "linkedin_urls": [
    "https://www.linkedin.com/company/acme-analytics"
  ],
  "fields": [
    "basic_info",
    "headcount"
  ]
}

request = urllib.request.Request(
    "https://foundermcp.dev/api/v1/company/enrich",
    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

{
  "results": [
    {
      "input": "https://www.linkedin.com/company/acme-analytics",
      "status": "matched",
      "match_type": "linkedin_url",
      "matches": [
        {
          "confidence_score": 1,
          "company": {
            "linkedin_url": "https://www.linkedin.com/company/acme-analytics",
            "basic_info": {
              "name": "Acme Analytics",
              "linkedin_url": "https://www.linkedin.com/company/acme-analytics",
              "website": "https://acme-analytics.example",
              "primary_domain": "acme-analytics.example",
              "description": "Analytics for finance teams.",
              "tagline": null,
              "logo_url": null,
              "employee_count_range": "51-200",
              "company_type": "Privately Held",
              "year_founded": 2019
            },
            "headcount": {
              "total": 87,
              "range": "51-200",
              "growth_percent": {
                "1m": null,
                "3m": null,
                "6m": null,
                "12m": null
              },
              "growth_absolute": {
                "1m": null,
                "3m": null,
                "6m": null,
                "12m": null
              },
              "by_role": null,
              "by_region": null,
              "largest_headcount_country": null
            },
            "unavailable": [
              "headcount.growth_percent",
              "headcount.growth_absolute",
              "headcount.by_role",
              "headcount.by_region",
              "headcount.largest_headcount_country"
            ]
          }
        }
      ]
    }
  ],
  "credits_used": 1
}