---
title: "Search people"
method: POST
path: "/people/search"
tags: ["People"]
---

# Search people

`POST /people/search`

## Request

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

Search people. 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 Person IDs to retrieve
  - `name` union: Filter by person's full name (first and last 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: 'John Smith' will only match people named exactly 'John Smith'.
    - object: Advanced object format for controlling match type
      - `value` string, required: The person 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., 'John' matches 'John Smith'), 'exact' for exact match
  - `emails` string[]: An array of email addresses to filter by
  - `phone_numbers` string[]: An array of phone numbers to filter by
  - `title` string: Filter by professional title
  - `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)
  - `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 people). Use -2 for no assignee.
  - `contact_type_ids` integer[]: An array of contact type IDs to filter by. See List Contact Types.
  - `company_ids` integer[]: An array of company IDs to filter by (the companies these people are associated with).
  - `opportunity_ids` integer[]: An array of opportunity IDs to filter by (people associated with these opportunities)
  - `socials` string[]: An array of social profile URLs to filter by
  - `followed` 1 | 2: Filter by followed status. Use 1 for followed people, 2 for not followed.
  - `age` integer: Maximum age in seconds of the person 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' | 'title' | 'email' | 'phone' | 'date_modified' | 'date_created' | 'city' | 'state' | 'country' | 'zip' | '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', 'title', 'emails'). 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', 'first_name', 'last_name', 'title', 'emails', 'phone_numbers', 'company_id', 'company_name', 'assignee_id', 'contact_type_id', 'address', 'tags', 'socials', 'websites', 'date_created', 'date_modified', 'date_last_contacted', 'interaction_count')
      - 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`

People 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` Person[], required: Records returned for the requested page. The item schema depends on the endpoint using this envelope.
    - `id` integer, required: Unique identifier for the person
    - `name` string, required: The first and last name of the person
    - `prefix` string, nullable: Name prefix
    - `first_name` string: First name of the person
    - `middle_name` string, nullable: Middle name of the person
    - `last_name` string: Last name of the person
    - `suffix` string, nullable: Name suffix
    - `address` object, nullable: An object containing the person's address
      - `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 person
    - `company_id` integer, nullable: ID of the associated company
    - `company_name` string, nullable: Name of the associated company
    - `contact_type_id` integer: Unique identifier of the contact type
    - `details` string, nullable: Description of the person
    - `emails` object[]: An array of email addresses belonging to the person
      - `email` string, email
      - `category` string
    - `phone_numbers` object[]: An array of phone numbers belonging to the person
      - `number` string: A phone number
      - `category` string: The category of the phone number
    - `socials` object[]: An array of social profiles belonging to the person
      - `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 person
    - `title` string, nullable: The professional title of the person
    - `websites` object[]: An array of websites belonging to the person
      - `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 person. 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
    - `date_created` integer: A Unix timestamp representing the time at which this person was created
    - `date_modified` integer: A Unix timestamp representing the time at which this person was last modified
    - `date_last_contacted` integer, nullable: A Unix timestamp representing the time at which this person was last contacted
    - `interaction_count` integer: The number of interactions with this person
    - `leads_converted_from` integer[]: An array of lead IDs that were converted to this person
    - `date_lead_created` integer, nullable: A Unix timestamp representing when the lead was created before conversion

## 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)