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

# List Companies

> For direct client API keys, returns the single associated company. For ATS keys, returns companies created by this API key.

Lists companies accessible to the API key. Behavior differs between regular API keys and ATS integration keys.

## Overview

The list companies endpoint returns companies based on your API key type. Regular API keys see only their associated company, while ATS keys see all companies they've created.

## Regular API Keys

For regular API keys, this endpoint returns the single company associated with the key:

```json theme={null}
{
  "data": {
    "items": [
      {
        "id": "company-uuid",
        "name": "Your Company"
      }
    ],
    "pagination": {
      "total": 1
    }
  }
}
```

## ATS Integration Keys

For ATS keys, this endpoint returns all companies created by that ATS key:

```json theme={null}
{
  "data": {
    "items": [
      {
        "id": "company-a-uuid",
        "name": "Client Company A"
      },
      {
        "id": "company-b-uuid",
        "name": "Client Company B"
      }
    ],
    "pagination": {
      "total": 2
    }
  }
}
```

## Use Cases

* **Company Discovery**: Find company IDs for ATS integrations
* **Multi-Tenant Management**: List all client companies for ATS platforms
* **Company Verification**: Verify company access and existence

## Pagination

The endpoint supports pagination for ATS keys managing many companies:

```javascript theme={null}
GET /company?page=1&limit=50
```

## Related Resources

<CardGroup cols={2}>
  <Card title="ATS Integration Guide" icon="plug" href="/guides/ats-integration">
    Learn about ATS integration keys
  </Card>

  <Card title="Companies Resource Guide" icon="building" href="/guides/resources/companies">
    Understand company management
  </Card>

  <Card title="Get Company" icon="eye" href="/api-reference/companies/get-company">
    Retrieve a specific company by ID
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /company
openapi: 3.0.0
info:
  title: InstaView API
  description: |-
    InstaView API Documentation

    ## Authentication

    All endpoints require API key authentication using Bearer token:
    ```
    Authorization: Bearer sk_your_api_key_here
    ```

    ## API Key Management

    The API Key module provides comprehensive key management for:
    - **Direct Client Keys**: Company-scoped keys for your applications
    - **ATS Partner Keys**: Resource-scoped keys for ATS integrations

    ### Key Features
    - HMAC-SHA256 hashing for API key storage
    - Configurable rate limiting
    - Comprehensive audit logging
    - Company-level isolation
    - Resource scoping for ATS partners
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.instaview.sk
    description: Production API Gateway
security: []
tags: []
paths:
  /company:
    get:
      tags:
        - Companies
      summary: List companies
      description: >-
        For direct client API keys, returns the single associated company. For
        ATS keys, returns companies created by this API key.
      operationId: PublicCompanyController_listCompanies_v1
      parameters:
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            maximum: 10000
            default: 1
            example: 1
            type: integer
        - name: limit
          required: false
          in: query
          description: Number of items per page
          schema:
            minimum: 1
            maximum: 100
            default: 20
            example: 20
            type: integer
        - name: search
          required: false
          in: query
          description: Search by company name
          schema:
            example: Acme
            type: string
        - name: companyId
          required: false
          in: query
          description: >-
            Required for ATS API keys to specify which company to access.
            Ignored for standard company API keys.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicListCompaniesResponseDto'
      security:
        - bearer: []
components:
  schemas:
    PublicListCompaniesResponseDto:
      type: object
      properties:
        data:
          description: Array of companies
          type: array
          items:
            $ref: '#/components/schemas/PublicCompanyDto'
        total:
          type: number
          description: Total number of items
          example: 150
        page:
          type: number
          description: Current page number
          example: 1
        limit:
          type: number
          description: Number of items per page
          example: 20
        totalPages:
          type: number
          description: Total number of pages
          example: 8
      required:
        - data
        - total
        - page
        - limit
        - totalPages
    PublicCompanyDto:
      type: object
      properties:
        id:
          type: string
          description: Company ID
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Company name
          example: Acme Corporation
        description:
          type: string
          description: Company description
          example: Leading technology company
        ownerEmail:
          type: string
          format: email
          maxLength: 254
          description: Email of the company owner
          example: owner@example.com
        metadata:
          type: object
          description: Custom metadata
          example:
            externalCompanyId: COMP-12345
            industry: Technology
        createdAt:
          type: string
          description: Created timestamp
          example: '2024-11-16T10:30:00Z'
        updatedAt:
          type: string
          description: Updated timestamp
          example: '2024-11-16T10:30:00Z'
      required:
        - id
        - name
        - createdAt
        - updatedAt
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key for authentication using Bearer scheme

````