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

# Search companies

`POST /companies/search`

## Request

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

Search companies. Response uses a pagination envelope (`page_number`,`total`,`data`) so ChatGPT can read pagination info; the X-PW-TOTAL header still exists. Paginate with page_number/page_size (max 200) until received records equal total. Limited to 100K results.

## Query parameters

- `custom_field_computed_values` boolean

## Request body

- object
  - `ids` integer[]: An array of Company IDs to retrieve
  - `name` union: Filter by company name. Use simple string for exact match (case-insensitive), or use object format with special_value for partial matching capability.
    - string: Simple string for exact match (case-insensitive). Example: 'Acme Corp' will only match companies named exactly 'Acme Corp'.
    - object: Advanced object format for controlling match type
      - `value` string, required: The company name to search for
      - `special_value` object[], required: Array specifying the match type
        - `type` 'partial' | 'exact', required: Match type: 'partial' for substring matching (e.g., 'Happy Cat' matches 'Happy Cat Hotels'), 'exact' for exact match
  - `email_domain` string: Filter by email domain (unique key for companies)
  - `email_domains` string[]: An array of email domains to filter by
  - `phone_number` string: Filter by phone number
  - `city` string: Filter by city in address
  - `state` string: Filter by state in address
  - `postal_code` string: Filter by postal code in address
  - `country` string: Filter by country in address (two-character country code)
  - `primary_contact_ids` integer[]: An array of person IDs who are the primary contacts for these companies.
  - `tags` string[]: An array of tags to filter by
  - `assignee_ids` integer[]: An array of assignee IDs to filter by (the user IDs who own these companies). Use -2 for no assignee.
  - `contact_type_ids` integer[]: An array of contact type IDs to filter by. See List Contact Types.
  - `socials` string[]: An array of social profile URLs to filter by
  - `followed` 1 | 2: Filter by followed status. Use 1 for followed companies, 2 for not followed.
  - `age` integer: Maximum age in seconds of the company record
  - `minimum_interaction_count` integer: Filter by minimum number of interactions
  - `maximum_interaction_count` integer: Filter by maximum number of interactions
  - `minimum_interaction_date` integer: Unix timestamp for the earliest date of the last interaction
  - `maximum_interaction_date` integer: Unix timestamp for the latest date of the last interaction
  - `minimum_created_date` integer: Unix timestamp for the minimum creation date
  - `maximum_created_date` integer: Unix timestamp for the maximum creation date
  - `minimum_modified_date` integer: Unix timestamp for the minimum modification date
  - `maximum_modified_date` integer: Unix timestamp for the maximum modification date
  - `custom_fields` object[]: An array of custom field filters to search by. For date fields, use minimum_value and maximum_value. For multi-select fields, you can use allow_empty to include records where the field is empty.
    - `custom_field_definition_id` integer: The custom field definition ID to filter by
    - `value` unknown
    - `minimum_value` integer: For date/number fields, the minimum value (Unix timestamp for dates)
    - `maximum_value` integer: For date/number fields, the maximum value (Unix timestamp for dates)
    - `allow_empty` boolean: When true, includes records where this custom field is empty/null
  - `sort_by` 'name' | 'phone' | 'contact' | 'contact_first_name' | 'contact_last_name' | 'date_modified' | 'date_created' | 'email_domain' | 'city' | 'state' | 'country' | 'zip' | 'assignee' | 'contact_group' | 'last_interaction' | 'interaction_count' | 'primary_website' | 'socials': The field on which to sort the results
  - `sort_direction` 'asc' | 'desc': The direction in which to sort the results
  - `page_number` integer: The page number (starting with 1) that you would like to view
  - `page_size` integer: The number of entries included in a page of results
  - `fields` union[]: Specify which fields to include in the response to reduce payload size. Include system field names as strings (e.g., 'name', 'email_domain', 'phone_numbers'). To include specific custom fields, add an object with custom_fields array. If omitted, all fields are returned.
    - union
      - string: System field name (e.g., 'id', 'name', 'email_domain', 'phone_numbers', 'address', 'assignee_id', 'contact_type_id', 'primary_contact_id', 'tags', 'socials', 'websites', 'interaction_count', 'date_created', 'date_modified')
      - object
        - `custom_fields` object[], required: Array of custom field definition IDs to include
          - `custom_field_definition_id` integer, required: The ID of the custom field definition to include in the response

## Response `200`

Companies retrieved successfully

- object: Standard paginated response envelope returned for ChatGPT-only requests. Mirrors the previous pagination headers by surfacing totals inside the response body while keeping the original headers available.
  - `page_number` integer, required: Current page number (defaults to 1 when not provided in the request).
  - `total` integer, required: Total number of records that match the request filters (equivalent to the X-PW-TOTAL header).
  - `data` Company[], required: Records returned for the requested page. The item schema depends on the endpoint using this envelope.
    - `id` integer, required: Unique identifier for the company
    - `name` string, required: The name of the company
    - `address` object, nullable: An encapsulation of the company's street, city, state, postal code, and country
      - `street` string
      - `city` string
      - `state` string
      - `postal_code` string
      - `country` string
    - `assignee_id` integer, nullable: Unique identifier of the user that will be the owner of the company
    - `contact_type_id` integer, nullable: The unique identifier of the contact type of the company
    - `details` string, nullable: Description of the company
    - `email_domain` string, nullable: The domain to which email addresses for the company belong. This is a unique key for companies - no two records can have the same domain name.
    - `phone_numbers` object[]: An array of phone numbers belonging to the company
      - `number` string: A phone number
      - `category` string: The category of the phone number
    - `primary_contact_id` integer, nullable: The unique identifier of the person who is the primary contact for this company
    - `socials` object[]: An array of social profiles belonging to the company
      - `url` string: The URL of a social profile
      - `category` string: The category of the social profile
    - `tags` string[]: An array of the tags associated with the company
    - `websites` object[]: An array of websites belonging to the company
      - `url` string: The URL of a website
      - `category` string: The category of the website
    - `custom_fields` object[]: An array of custom field values belonging to the company. When custom_field_computed_values query parameter is true, each field will include a computed_value with human-readable labels for Dropdown and Multi-select fields.
      - `custom_field_definition_id` integer: The id of the custom field definition for which this custom field stores a value
      - `value` unknown
      - `computed_value` unknown
    - `interaction_count` integer: The number of interactions with this company
    - `date_created` integer: A Unix timestamp representing the time at which this company was created
    - `date_modified` integer: A Unix timestamp representing the time at which this company was last modified

## Other responses

- `400`: Bad Request - The request was invalid or cannot be served
- `401`: Unauthorized - Authentication credentials were missing or incorrect
- `429`: Too Many Requests - Rate limit exceeded
- `500`: Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.dev/copper/apis/copper-crm-read-only-api.md) - [All operations](https://skmtc.dev/copper/apis/copper-crm-read-only-api/llms.txt) - [OpenAPI document](https://skmtc.dev/copper/apis/copper-crm-read-only-api/revisions/96adc8557a40?raw)