---
title: "Lookup Companies"
method: POST
path: "/api/v1/account/lookup-companies"
tags: ["Company Lookup"]
---

# Lookup Companies

`POST /api/v1/account/lookup-companies`

Resolve companies to their canonical OpenFunnel record(s) by any subset of **name / domain / linkedin_url**. Batch up to **100** per call. **No credits are charged.**

<Info>**No API key yet?** [Sign up via Agent Auth](/agent-primitives/authentication) to get your `X-API-Key` - the only required header for this endpoint.</Info>

Each item may carry any combination of identifiers:
- **domain** → exact match on any of the company's domains. Returns all matching records.
- **linkedin_url** → exact match on the company's LinkedIn slug (parsed from the URL).
- **name** → fuzzy match; returns up to 10 ranked candidates with a relevance `score`.

If an item includes a `domain` or `linkedin_url`, it is resolved by that exact identifier and the `name` is ignored - the fuzzy name path runs only when `name` is the sole identifier. Matches are deduped by `company_id` (precedence: linkedin > domain > name). A returned `company_id` can be passed straight back into Search Lookalikes as a seed. Unknown inputs return `status: "not_found"` with an empty `matches` array.

## Headers

- `X-API-Key` string, required

## Request body

- CompanyLookupRequest — Batch company lookup: resolve up to 100 companies by identifier.
  - `companies` CompanyLookupItem[], required — 1-100 companies to resolve.
    - `name` string, nullable — Company name. Fuzzy - resolves to ranked candidates.
    - `domain` string, nullable — Company website/domain (e.g. stripe.com). Matched on the primary domain.
    - `linkedin_url` string, nullable — Company LinkedIn URL. Matched on the company slug parsed from the URL.

## Response `200`

One result per input company, in request order.

- CompanyLookupResponse — Response for the batch company lookup endpoint (one result per input, in request order).
  - `results` CompanyLookupItemResult[], required
    - `input` CompanyLookupInput, required — Echo of the identifiers supplied for a lookup item.
      - `name` string, nullable
      - `domain` string, nullable
      - `linkedin_url` string, nullable
    - `status` string, required — `resolved` if any match, else `not_found`.
    - `matches` CompanyLookupMatch[] — Matched companies, deduped by company_id.
      - `company_id` string, nullable — Canonical company id, reusable as a seed in Search Lookalikes.
      - `name` string, nullable
      - `domain` string, nullable
      - `linkedin_url` string, nullable
      - `linkedin_slug` string, nullable
      - `employee_count_min` integer, nullable
      - `employee_count_max` integer, nullable
      - `stage` string, nullable
      - `industries` string, nullable
      - `location_city` string, nullable
      - `location_country` string, nullable
      - `location_country_code` string, nullable
      - `matched_on` string, required — Which identifier matched: `domain`, `linkedin`, or `name`.
      - `score` number, nullable — Relevance score (0-1) for `name` matches; null for exact domain/linkedin matches.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/openfunnel/apis/openfunnel-agent-primitives.md) · [All operations](https://skmtc.net/openfunnel/apis/openfunnel-agent-primitives/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openfunnel/openfunnel-agent-primitives/revisions/68cc95acb1f2/schema)