> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openfunnel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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-auth/agent-auth/agent-sign-up) 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.



## OpenAPI

````yaml agent-primitives/openapi.json POST /api/v1/account/lookup-companies
openapi: 3.1.0
info:
  title: OpenFunnel Agent Primitives
  version: 1.0.0
servers:
  - url: https://api.openfunnel.dev
security: []
paths:
  /api/v1/account/lookup-companies:
    post:
      tags:
        - Company Lookup
      summary: Lookup Companies
      description: >-
        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-auth/agent-auth/agent-sign-up) 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.
      operationId: lookup_companies_api_v1_account_lookup_companies_post
      parameters:
        - name: X-API-Key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyLookupRequest'
      responses:
        '200':
          description: One result per input company, in request order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyLookupResponse'
              example:
                results:
                  - input:
                      name: null
                      domain: stripe.com
                      linkedin_url: null
                    status: resolved
                    matches:
                      - company_id: ww_39dde6f3035d07e7e55e882f05ec6d7e
                        name: Stripe
                        domain: stripe.com
                        linkedin_url: https://www.linkedin.com/company/stripe
                        linkedin_slug: stripe
                        employee_count_min: 5000
                        employee_count_max: 10000
                        stage: private_equity
                        industries: Financial Services, FinTech
                        location_city: San Francisco
                        location_country: United States
                        location_country_code: us
                        matched_on: domain
                        score: null
                  - input:
                      name: Plaid
                      domain: null
                      linkedin_url: null
                    status: resolved
                    matches:
                      - company_id: ww_55c8eee3a23eab95f8cc650641deea75
                        name: Plaid
                        domain: plaid.com
                        linkedin_url: https://www.linkedin.com/company/plaid
                        linkedin_slug: plaid
                        employee_count_min: 1200
                        employee_count_max: 1200
                        stage: series_unknown
                        industries: Finance, Banking, FinTech
                        location_city: San Francisco
                        location_country: United States
                        location_country_code: us
                        matched_on: name
                        score: 0.97
                  - input:
                      name: null
                      domain: this-domain-does-not-exist-xyz.com
                      linkedin_url: null
                    status: not_found
                    matches: []
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: bash
          label: Lookup companies
          source: >-
            curl -sS -X POST
            "https://api.openfunnel.dev/api/v1/account/lookup-companies" \
              -H "X-API-Key: YOUR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"companies": [{"domain": "stripe.com"}, {"linkedin_url": "https://www.linkedin.com/company/adyen"}, {"name": "Plaid"}]}'
components:
  schemas:
    CompanyLookupRequest:
      type: object
      title: CompanyLookupRequest
      description: 'Batch company lookup: resolve up to 100 companies by identifier.'
      required:
        - companies
      properties:
        companies:
          type: array
          items:
            $ref: '#/components/schemas/CompanyLookupItem'
          minItems: 1
          maxItems: 100
          title: Companies
          description: 1-100 companies to resolve.
    CompanyLookupResponse:
      type: object
      title: CompanyLookupResponse
      description: >-
        Response for the batch company lookup endpoint (one result per input, in
        request order).
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CompanyLookupItemResult'
          title: Results
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    CompanyLookupItem:
      type: object
      title: CompanyLookupItem
      description: >-
        One company to resolve, identified by any subset of
        name/domain/linkedin_url. At least one is required.
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Name
          description: Company name. Fuzzy - resolves to ranked candidates.
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: >-
            Company website/domain (e.g. stripe.com). Matched on the primary
            domain.
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Url
          description: >-
            Company LinkedIn URL. Matched on the company slug parsed from the
            URL.
    CompanyLookupItemResult:
      type: object
      title: CompanyLookupItemResult
      description: Resolution result for one input company.
      required:
        - input
        - status
      properties:
        input:
          $ref: '#/components/schemas/CompanyLookupInput'
          description: The identifiers supplied for this item.
        status:
          type: string
          title: Status
          description: '`resolved` if any match, else `not_found`.'
        matches:
          type: array
          items:
            $ref: '#/components/schemas/CompanyLookupMatch'
          title: Matches
          description: Matched companies, deduped by company_id.
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string
    CompanyLookupInput:
      type: object
      title: CompanyLookupInput
      description: Echo of the identifiers supplied for a lookup item.
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Url
    CompanyLookupMatch:
      type: object
      title: CompanyLookupMatch
      description: A company matched against one lookup item.
      required:
        - matched_on
      properties:
        company_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Company Id
          description: Canonical company id, reusable as a seed in Search Lookalikes.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Url
        linkedin_slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Slug
        employee_count_min:
          anyOf:
            - type: integer
            - type: 'null'
          title: Employee Count Min
        employee_count_max:
          anyOf:
            - type: integer
            - type: 'null'
          title: Employee Count Max
        stage:
          anyOf:
            - type: string
            - type: 'null'
          title: Stage
        industries:
          anyOf:
            - type: string
            - type: 'null'
          title: Industries
        location_city:
          anyOf:
            - type: string
            - type: 'null'
          title: Location City
        location_country:
          anyOf:
            - type: string
            - type: 'null'
          title: Location Country
        location_country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Location Country Code
        matched_on:
          type: string
          title: Matched On
          description: 'Which identifier matched: `domain`, `linkedin`, or `name`.'
        score:
          anyOf:
            - type: number
            - type: 'null'
          title: Score
          description: >-
            Relevance score (0-1) for `name` matches; null for exact
            domain/linkedin matches.

````