---
title: "List companies"
method: GET
path: "/public-api/v1/companies"
tags: ["Companies"]
---

# List companies

`GET /public-api/v1/companies`

## Request

- Base URL: `https://app.hellobonsai.com`
- URL: `https://app.hellobonsai.com/public-api/v1/companies`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.hellobonsai.com/oauth/authorize`
    - Token URL: `https://app.hellobonsai.com/oauth/token`
  - HTTP bearer

Lists the companies in your CRM, a page at a time. Archived companies
are left out.

Search by name before creating a company, so you update the existing
record instead of adding a duplicate.

## Filtering

- `filter[name]` — searches company names, matching from the start of
  any word and ignoring case. `acme` finds "Acme Corp"; so does `corp`.

## Query parameters

- `page[number]` integer
- `page[size]` integer
- `filter[name]` string

## Response `200`

A page of companies.

- object
  - `data` Company[], required
    - `id` integer, required: Unique identifier for the company.
    - `name` string, nullable, required: Company name.
    - `default_contact_id` integer, nullable, required: Id of the contact treated as this company's primary point of contact, or `null` when none is set. Deals and invoices created without an explicit contact fall back to it.
    - `description` string, nullable, required: Free text notes about the company, or `null` when unset.
    - `industry` 'arts_and_entertainment' | 'business_and_consumer_services' | 'community_and_society' | 'computers_electronics_and_technology' | 'e_commerce_and_shopping' | 'finance' | 'food_and_drink' | 'gambling' | 'games' | 'health' | 'heavy_industry_and_engineering' | 'hobbies_and_leisure' | 'home_and_garden' | 'jobs_and_career' | 'law_and_government' | 'lifestyle' | 'luxury' | 'news_and_media' | 'pets_and_animals' | 'reference_materials' | 'science_and_education' | 'sports' | 'travel_and_tourism' | 'vehicles' | 'null', nullable, required: The industry the company operates in, or `null` when unset. One of a fixed list.
    - `company_size` 'size_1_10' | 'size_11_50' | 'size_51_200' | 'size_201_1000' | 'size_1000_plus' | 'null', nullable, required: Headcount band for the company, or `null` when unset. One of a fixed list.
    - `source` 'organic_search' | 'paid_search' | 'email_marketing' | 'organic_social' | 'referrals' | 'other_campaigns' | 'direct_traffic' | 'offline_sources' | 'paid_social' | 'ai_referrals' | 'null', nullable, required: How the client was acquired, or `null` when unset. One of a fixed list.
    - `linkedin` string, nullable, required: Link to the company's LinkedIn profile, or `null` when unset.
    - `instagram` string, nullable, required: Link to the company's Instagram profile, or `null` when unset.
    - `twitter` string, nullable, required: Link to the company's X profile, or `null` when unset.
    - `facebook` string, nullable, required: Link to the company's Facebook page, or `null` when unset.
    - `archived_at` string, date-time, nullable, required: When the company was archived, or `null` while it is active. Archived companies are left out of the list endpoint.
    - `created_at` string, date-time, required: When the company was added to your account.
    - `domains` string[], required: Domains associated with the company, lowercased and stripped of any protocol or `www.` prefix. A domain can belong to only one company in your account.
    - `avatar_url` string, nullable, required: Link to the company's logo, or `null` when it has none. Read-only — the create and update endpoints don't accept it. Bonsai shows generated initials in the app when there is no logo; those are never returned here.
    - `url` string, required: Absolute link to the company in the Bonsai app. Share it to send someone straight to the record.
  - `meta` PaginatedMeta, required: Metadata returned alongside every list response.
    - `request_id` string, required: Identifier for this request. Quote it when contacting support about a specific call.
    - `pagination` Pagination, required: Where the returned page sits in the full result set.
      - `page` integer, required: The page that was returned.
      - `page_size` integer, required: How many records this page can hold.
      - `has_more` boolean, required: Whether at least one more page follows this one. Keep incrementing `page[number]` while this is `true`.

## Other responses

- `400`: A filter key is unknown, or a pagination parameter is not an integer.
- `401`: The access token is missing, expired or invalid.
- `403`: This token is not allowed to read or write companies in your CRM.
- `429`: Rate limit exceeded. Wait at least `Retry-After` seconds before trying again.

---

[API](https://skmtc.dev/hellobonsai/apis/bonsai-api.md) - [All operations](https://skmtc.dev/hellobonsai/apis/bonsai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hellobonsai/apis/bonsai-api/revisions/abf12ed6a8d3?raw)