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

# Autocomplete Companies

> Search and retrieve company suggestions for autocomplete functionality in company filters and selections

Provides autocomplete suggestions for companies based on search text. This endpoint powers company autocomplete dropdowns in the application, helping users quickly find and select companies by name. Results can be sorted by employee count for relevance.

## Authentication

This endpoint requires authentication. The user must be signed in to access autocomplete data.

<Note>
  This endpoint proxies requests to the our search metadata API. Results are
  cached for 7 days to improve performance.
</Note>

## Request

<ParamField query="search" type="string">
  Search query to filter companies by name. Returns companies that match this
  text. Leave empty to retrieve all companies.
</ParamField>

<ParamField query="size" type="integer" default="10">
  Number of results to return per page. Maximum recommended value is 100.
</ParamField>

<ParamField query="page" type="integer" default="0">
  Zero-based page number for pagination.
</ParamField>

<ParamField query="employeeCount" type="string">
  Sort order for results based on company employee count.

  **Allowed values:**

  * `asc` - Sort by employee count ascending (smallest first)
  * `desc` - Sort by employee count descending (largest first)
</ParamField>

## Response

Returns a paginated list of company items matching the search criteria.

<ResponseField name="content" type="CompanyMetadataItem[]">
  Array of company items matching the query.

  <Expandable title="CompanyMetadataItem properties">
    <ResponseField name="id" type="string" required>
      Unique identifier for the company.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Company display name.
    </ResponseField>

    <ResponseField name="logo" type="string">
      URL to the company logo image. Can be null if no logo is available.
    </ResponseField>

    <ResponseField name="url" type="string">
      Company profile URL. Can be null.
    </ResponseField>

    <ResponseField name="domain" type="string">
      Company primary domain (e.g., "google.com"). Can be null.
    </ResponseField>

    <ResponseField name="domainLtd" type="string">
      Company domain with TLD variation. Can be null.
    </ResponseField>

    <ResponseField name="website" type="string">
      Full website URL for the company. Can be null.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalElements" type="integer">
  Total number of matching companies across all pages.
</ResponseField>

<ResponseField name="totalPages" type="integer">
  Total number of pages available.
</ResponseField>

<ResponseField name="size" type="integer">
  Number of items per page.
</ResponseField>

<ResponseField name="number" type="integer">
  Current page number (zero-based).
</ResponseField>

<ResponseField name="first" type="boolean">
  Whether this is the first page.
</ResponseField>

<ResponseField name="last" type="boolean">
  Whether this is the last page.
</ResponseField>

<ResponseField name="empty" type="boolean">
  Whether the result set is empty.
</ResponseField>

<ResponseField name="numberOfElements" type="integer">
  Number of elements in the current page.
</ResponseField>

## Response Examples

<ResponseExample>
  ```json 200 - Company search results theme={null}
  {
    "content": [
      {
        "id": "company_001",
        "name": "Google",
        "logo": "https://logo.clearbit.com/google.com",
        "url": "https://linkedin.com/company/google",
        "domain": "google.com",
        "domainLtd": "google.com",
        "website": "https://www.google.com"
      },
      {
        "id": "company_002",
        "name": "Alphabet Inc.",
        "logo": "https://logo.clearbit.com/abc.xyz",
        "url": "https://linkedin.com/company/alphabet-inc",
        "domain": "abc.xyz",
        "domainLtd": "abc.xyz",
        "website": "https://abc.xyz"
      }
    ],
    "totalElements": 2,
    "totalPages": 1,
    "size": 10,
    "number": 0,
    "first": true,
    "last": true,
    "empty": false,
    "numberOfElements": 2
  }
  ```

  ```json 200 - Sorted by employee count theme={null}
  {
    "content": [
      {
        "id": "company_large",
        "name": "Microsoft Corporation",
        "logo": "https://logo.clearbit.com/microsoft.com",
        "url": null,
        "domain": "microsoft.com",
        "domainLtd": "microsoft.com",
        "website": "https://www.microsoft.com"
      },
      {
        "id": "company_medium",
        "name": "Stripe",
        "logo": "https://logo.clearbit.com/stripe.com",
        "url": null,
        "domain": "stripe.com",
        "domainLtd": "stripe.com",
        "website": "https://stripe.com"
      }
    ],
    "totalElements": 150,
    "totalPages": 15,
    "size": 10,
    "number": 0,
    "first": true,
    "last": false,
    "empty": false,
    "numberOfElements": 10
  }
  ```

  ```json 200 - Empty results theme={null}
  {
    "content": [],
    "totalElements": 0,
    "totalPages": 0,
    "size": 10,
    "number": 0,
    "first": true,
    "last": true,
    "empty": true,
    "numberOfElements": 0
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Unauthorized"
    }
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Search for companies by name

```bash theme={null}
curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/companies?search=google&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Get largest companies first

```bash theme={null}
curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/companies?employeeCount=desc&size=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Paginate through results

```bash theme={null}
curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/companies?search=tech&page=2&size=25" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Get small companies for SMB targeting

```bash theme={null}
curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/companies?employeeCount=asc&size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Notes

* Results are cached for 7 days to improve performance. The cache is shared across all users.
* Use the `search` parameter for type-ahead/autocomplete functionality - it filters results that match the company name.
* The `employeeCount` sort parameter is useful for targeting specific company sizes (enterprise vs SMB).
* Company logos are provided via external URLs and may not always be available.
* The `domain` field is useful for deduplication and matching companies across different data sources.