---
title: "Create a company"
method: POST
path: "/public-api/v1/companies"
tags: ["Companies"]
---

# Create a company

`POST /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

Adds a company to your CRM. Only `name` is required.

Search the list endpoint by name first — nothing here deduplicates for
you, so creating a company you already have leaves you with two.

Every company created through the API is a client. Vendors cannot be
created here.

## Request body

- object
  - `company` object, required
    - `name` string, required: Company name. Required.
    - `default_contact_id` integer, nullable: Id of the contact to make this company's primary point of contact. Must be a contact in your account — find one with `GET /public-api/v1/contacts`.
    - `description` string, nullable: Free text notes about the company.
    - `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: The industry the company operates in. Must be one of the listed values.
    - `company_size` 'size_1_10' | 'size_11_50' | 'size_51_200' | 'size_201_1000' | 'size_1000_plus' | 'null', nullable: Headcount band for the company. Must be one of the listed values.
    - `source` 'organic_search' | 'paid_search' | 'email_marketing' | 'organic_social' | 'referrals' | 'other_campaigns' | 'direct_traffic' | 'offline_sources' | 'paid_social' | 'ai_referrals' | 'null', nullable: How the client was acquired. Must be one of the listed values.
    - `linkedin` string, nullable: Link to the company's LinkedIn profile.
    - `instagram` string, nullable: Link to the company's Instagram profile.
    - `twitter` string, nullable: Link to the company's X profile.
    - `facebook` string, nullable: Link to the company's Facebook page.
    - `domains` string[], nullable: Domains to associate with the company. Each value is lowercased and stripped of any protocol or `www.` prefix before it is stored. A domain can belong to only one company in your account; claiming one that is already taken fails with `422`.

## Response `201`

The company was created.

- object
  - `data` Company, required: A client company in your CRM. Deals, projects and invoices all belong to one.
    - `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` Meta, required: Metadata returned alongside every single-resource response.
    - `request_id` string, required: Identifier for this request. Quote it when contacting support about a specific call.

## Other responses

- `400`: The request body is missing its `company` wrapper.
- `401`: The access token is missing, expired or invalid.
- `403`: This token is not allowed to read or write companies in your CRM.
- `422`: The company could not be saved — most often a blank name, a value outside one of the fixed lists, or a domain already claimed by another company.
- `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)