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