---
title: "Search companies"
method: POST
path: "/companies/search"
tags: ["Companies"]
---

# Search companies

`POST /companies/search`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/companies/search`
- Auth: HTTP bearer

Searches your companies using a free-text query. Results are returned sorted by creation date, with the most recently created companies appearing first.

## Request body

- SearchCompaniesBody
  - `query` string: Free-text search query matched against company name. Up to 200 characters.
  - `cursor` string, nullable: An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.
  - `limit` integer: A limit on the number of objects to be returned. Limit can range between 1 and 100.
  - `filters` object
    - `markets` string[]: Return companies assigned to any of these canonical market slugs. Up to 10 values.
    - `customFields` object[]: Match every public custom-field clause; values within one clause are alternatives.
      - `key` string, required
      - `values` union[], required
        - union
          - string
          - number
          - boolean
    - `objectReferences` object[]: Match every public object-reference clause; record IDs within one clause are alternatives.
      - `key` string, required
      - `recordIds` string[], required

## Response `200`

Successful response.

- object
  - `object` 'search_result', required
  - `url` string, required
  - `hasMore` boolean, required
  - `nextCursor` string, nullable, required
  - `data` Company[], required
    - `id` string, required: Unique identifier for the object. Use this value as the `{id}` path parameter for the company endpoints (e.g. `GET /v1/companies/{id}`).
    - `object` 'company', required: String representing the object's type. Objects of the same type share the same value.
    - `name` string, required: Display name of the company.
    - `slug` string, required: URL-friendly slug for the company.
    - `website` string, nullable, required: Public company website URL, or `null` if not set.
    - `logoUrl` string, nullable, required: URL of the company logo, or `null` if no logo is set.
    - `summary` string, nullable, required: One-line summary of the company, or `null` if not set.
    - `markets` string[], required: Canonical market slugs assigned to the company.
    - `xUrl` string, nullable, required: X (Twitter) profile URL, or `null` if not set.
    - `linkedinUrl` string, nullable, required: LinkedIn page URL, or `null` if not set.
    - `facebookUrl` string, nullable, required: Facebook page URL, or `null` if not set.
    - `instagramUrl` string, nullable, required: Instagram profile URL, or `null` if not set.
    - `createdAt` string, required: Time at which the company was created. ISO 8601 datetime.
    - `updatedAt` string, nullable, required: Time at which the company was last updated, or `null` if it has never been updated. ISO 8601 datetime.
    - `revision` integer, required: Public Company lifecycle revision. Historical rows may be 0 until rollout backfill.
    - `links` object, required: Public + admin URLs for this company. `public` may be `null` if the company lacks a slug.
      - `public` string, uri, nullable, required: Canonical public URL for this company on the board, or `null` when no slug is set.
      - `admin` string, uri, required: URL inside the Cavuno app where the authenticated owner can manage this resource.
    - `description` string, nullable, required: Long-form description of the company (HTML), or `null` if not set.
    - `canBackfill` boolean, nullable, required: Whether automated backfill of jobs from this company is supported, or `null` if not yet evaluated.
    - `jobCount` number, required: Total number of jobs at this company across all statuses.
    - `publishedJobCount` number, required: Number of currently-published jobs at this company.

## Other responses

- `default`: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.

## Changes

- **2026-10-19** `c34152c38176`: 1 info
  - added the optional property `error/upgrade` to the response with the `default` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/companies/search/post.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)