---
title: "List contacts"
method: GET
path: "/public-api/v1/contacts"
tags: ["Contacts"]
---

# List contacts

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

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

Search by name or email to find someone before you add them, and filter
by `company_id` to list everyone you know at one company.

## Filtering

- `filter[name]` — searches contact names, matching anywhere in the name
  and ignoring case.
- `filter[email]` — searches email addresses the same way.
- `filter[company_id]` — one or more company ids. Returns the contacts
  linked to those companies.

## Query parameters

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

## Response `200`

A page of contacts.

- object
  - `data` Contact[], required
    - `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` 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 `filter[company_id]` is not an integer.
- `401`: The access token is missing, expired or invalid.
- `403`: This token is not allowed to read or write contacts 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)