---
title: "Create a contact"
method: POST
path: "/public-api/v1/contacts"
tags: ["Contacts"]
---

# Create a contact

`POST /public-api/v1/contacts`

## Request

- Base URL: `https://app.hellobonsai.com`
- URL: `https://app.hellobonsai.com/public-api/v1/contacts`
- 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 person to your CRM. `name` and `email` are required.

Pass `company_id` to link them to a company you already have, or leave it
out for a contact who does not belong to one.

## Request body

- object
  - `contact` object, required
    - `name` string, required: Full name. Required.
    - `email` string, required: Email address. Required, and must be unique among your contacts.
    - `job_title` string, nullable: Job title.
    - `phone_number` string, nullable: Phone number, stored as given.
    - `company_id` integer, nullable: Id of the company to link the contact to. Find one with `GET /public-api/v1/companies`.

## Response `201`

The contact was created.

- object
  - `data` Contact, required: A person you work with at a client company, or a standalone contact who belongs to none.
    - `id` integer, required: Unique identifier for the contact.
    - `name` string, nullable, required: The contact's full name.
    - `email` string, nullable, required: The contact's email address.
    - `job_title` string, nullable, required: The contact's job title, or `null` when unset.
    - `phone_number` string, nullable, required: The contact's phone number, or `null` when unset.
    - `archived_at` string, date-time, nullable, required: When the contact was archived, or `null` while they are active. Archived contacts are left out of the list endpoint.
    - `created_at` string, date-time, required: When the contact was added to your account.
    - `company_ids` integer[], required: Ids of every company this contact is linked to. A contact can belong to more than one.
    - `default_company_id` integer, nullable, required: Id of the company this contact is the primary contact for, or `null` when they are not the primary contact anywhere.
    - `url` string, required: Absolute link to the contact 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 `contact` wrapper.
- `401`: The access token is missing, expired or invalid.
- `403`: This token is not allowed to read or write contacts in your CRM.
- `422`: The contact could not be saved — a required field is blank, the email is malformed or already in use, or `company_id` is not a company in your account.
- `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)