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

# Fetch Company

> Retrieve detailed information about companies by their unique identifiers.

The Fetch Company endpoint returns comprehensive data for a given company ID.

By default, the response contains basic company info and firmographic data. The `fields` array accepts the following values:

* **company\_info** — Basic company information and firmographic data (returned by default).
* **tags** — Tags assigned to the company.

For more details see [Models > Company](/docs/enrichment-data/company).

## Limits

Each identifier array (`ids`, `linkedin_slugs`, `linkedin_ids`) accepts up to **1,000 values per request**. Combine arrays freely up to the per-array cap.

## Responses

In addition to the standard error responses, this endpoint may return:

* **`402 Payment Required`** — your team's API credit allowance has been exceeded. Top up or upgrade your plan to continue. See [Credits & Usage](/docs/api-reference/credits-usage).

## Partner teams

Partners can execute a request in the context of a child team by passing the child team's ID in the `x-authenticate-team` header:

```http theme={null}
x-authenticate-team: <child_team_id>
```

* **With the header** — the fetch runs in the context of the child team (e.g. tag membership reflects the child team).
* **Without the header** — the fetch runs in the context of the team that owns the API key (default).

The `child_team_id` is returned when you [create a child team](/docs/endpoints/v3/create-team).

```bash Example request theme={null}
curl -X POST https://bee.theswarm.com/v3/companies/fetch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-authenticate-team: child-team-id-123" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_slugs": ["theswarm"],
    "fields": ["company_info", "tags"]
  }'
```

<Note>
  **Migrating from v2?** v3 uses snake\_case for all field names. The v2 equivalents were `linkedinNames`, `linkedinIds`, `notFound`, and `company_info.Size`. See the [Migrating to v3](/docs/getting-started/migrating-to-v3) guide.
</Note>


## OpenAPI

````yaml openapi.json POST /v3/companies/fetch
openapi: 3.1.0
info:
  title: Swarm API
  version: 1.0.0
  contact:
    name: The Swarm
    url: https://theswarm.com
    email: hello@theswarm.com
servers:
  - url: https://bee.theswarm.com
security:
  - ApiKeyAuth: []
tags:
  - name: profiles
    description: Operations related to profiles
  - name: companies
    description: Operations related to companies
  - name: teams
    description: Operations for managing teams and connectors
  - name: social
    description: Operations related to social media posts and interactions
  - name: mcp
    description: Model Context Protocol endpoint for AI assistant integrations
  - name: credits
    description: Operations related to credit usage
  - name: network-mapper
    description: Operations for mapping connections and relationships across your network
paths:
  /v3/companies/fetch:
    post:
      tags:
        - companies
      summary: Fetch companies with corresponding data
      description: Fetch companies with corresponding data (e.g. tags)
      operationId: fetchCompaniesV3
      parameters:
        - $ref: '#/components/parameters/AuthenticateTeamHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  maxItems: 1000
                  description: The Swarm company IDs
                linkedin_names:
                  type: array
                  items:
                    type: string
                  maxItems: 1000
                  description: LinkedIn company URL slugs
                linkedin_ids:
                  type: array
                  items:
                    type: integer
                  maxItems: 1000
                  description: LinkedIn numeric company IDs
                fields:
                  type: array
                  items:
                    type: string
                    enum:
                      - company_info
                      - tags
                  default:
                    - company_info
              anyOf:
                - required:
                    - ids
                - required:
                    - linkedin_names
                - required:
                    - linkedin_ids
      responses:
        '200':
          description: A list of companies with corresponding data
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    description: List of companies with corresponding data
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanyV3'
                  not_found:
                    description: >-
                      List of company identifiers (ids / linkedin_names /
                      linkedin_ids) that were not found
                    type: array
                    items:
                      type: string
                required:
                  - results
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    AuthenticateTeamHeader:
      name: x-authenticate-team
      in: header
      required: false
      description: >-
        Partner accounts only. When present, the request is executed in the
        context of the specified child team (use the `team_id` returned by
        [Create Team](/docs/endpoints/v3/create-team)). When omitted, the
        request runs as the team that owns the API key.
      schema:
        type: string
  schemas:
    CompanyV3:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the company
        company_info:
          $ref: '#/components/schemas/CompanyInfoV3'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagV3'
          description: The tags of the company
        found_by:
          $ref: '#/components/schemas/CompanyFoundByV3'
      required:
        - id
    CompanyInfoV3:
      type: object
      properties:
        id:
          type: string
        linkedin_slugs:
          type: array
          items:
            type: string
        name:
          type: string
        alternative_names:
          type: array
          items:
            type: string
        description:
          type: string
        summary:
          type: string
        contact_info:
          type: object
          properties:
            email:
              type: string
            phone:
              type: string
            url:
              type: string
        canonical_name:
          type: string
        founded:
          type: string
          format: date-time
        workforce:
          type: object
          properties:
            headcount:
              type: integer
            historical_headcount:
              type: array
              items:
                type: object
                properties:
                  timestamp:
                    type: integer
                  count:
                    type: integer
            size_class:
              type: string
        tech_stack:
          type: object
          properties:
            products:
              type: array
              items:
                type: string
        business_data:
          type: object
          properties:
            identifiers:
              type: object
              properties:
                stock_ticker:
                  type: string
                duns_code:
                  type: string
                cage_code:
                  type: string
                naics_code:
                  type: string
            customer_types:
              type: array
              items:
                type: string
            stock_exchange:
              type: string
            is_acquired:
              type: boolean
            is_exited:
              type: boolean
            is_government:
              type: boolean
            is_non_profit:
              type: boolean
            is_shut_down:
              type: boolean
            is_startup:
              type: boolean
            is_stealth:
              type: boolean
            ownership_status:
              type: string
            ownership_status_detailed:
              type: string
            patent_count:
              type: integer
            financing_profile:
              type: object
              properties:
                status:
                  type: string
                ipo_date:
                  type: string
                  format: date-time
                outstanding_shares:
                  type: number
                market_cap:
                  type: number
        social_media:
          type: array
          items:
            $ref: '#/components/schemas/CompanySocialMedia'
          description: The networks of the company
        locations:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              country:
                type: string
              is_primary:
                type: boolean
        logo_url:
          type: string
        investor:
          type: object
          properties:
            type:
              type: array
              items:
                type: string
            specialities:
              type: array
              items:
                type: string
            investments:
              type: array
              items:
                type: string
            geography_focus:
              type: array
              items:
                type: string
        funding:
          type: object
          properties:
            last_round:
              type: object
              properties:
                last_round_type:
                  type: string
                last_round_amount_usd:
                  type: number
                last_round_date:
                  type: string
                  format: date-time
                last_round_investors:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      kind:
                        type: string
                        enum:
                          - Unknown
                          - Profile
                          - Company
                        description: Investor kind
                      name:
                        type: string
                      crunchbase_slug:
                        type: string
            rounds:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  amount_usd:
                    type: number
                  date:
                    type: string
                    format: date-time
                  investors:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        kind:
                          type: string
                          enum:
                            - Unknown
                            - Profile
                            - Company
                          description: Investor kind
                        name:
                          type: string
                        crunchbase_slug:
                          type: string
            total_funding_amount_usd:
              type: number
        updated_at:
          type: string
          format: date-time
        industries:
          type: array
          items:
            type: string
        websites:
          type: array
          items:
            type: string
      required:
        - name
    TagV3:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the tag
        name:
          type: string
          description: The name of the tag
      required:
        - id
        - name
    CompanyFoundByV3:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
            format: uuid
        linkedin_names:
          type: array
          items:
            type: string
        linkedin_ids:
          type: array
          items:
            type: integer
      description: Which of the requested identifiers matched this result
    ErrorResponse:
      type: object
      properties:
        code:
          description: Error status code
          type: integer
        errors:
          type: array
          items:
            type:
              - string
              - object
      required:
        - code
    CompanySocialMedia:
      type: object
      properties:
        network:
          type: string
          description: Social media network name
        id:
          type: string
          description: Identifier on the social network
        slug:
          type: string
          description: Slug / handle on the social network
        url:
          type: string
          description: Full profile URL
  responses:
    '400':
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '401':
      description: Unauthorized
    '402':
      description: Payment required - the team's API credit allowance has been exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '403':
      description: Forbidden
    5XX:
      description: Unexpected error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````