---
title: "Search leads"
method: POST
path: "/leads/search"
tags: ["Leads"]
---

# Search leads

`POST /leads/search`

## Request

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

Search leads. 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 Lead IDs to retrieve
  - `name` string: Filter by lead's full name (first and last name)
  - `first_name` string: Filter by lead's first name
  - `last_name` string: Filter by lead's last name
  - `middle_name` string: Filter by lead's middle name
  - `emails` string, email: Filter by email address
  - `phone_number` string: Filter by phone number
  - `company_name` string: Filter by the name of the company the lead belongs to
  - `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 leads). To get User IDs, see List Users. Use -2 for no assignee.
  - `status_ids` integer[]: An array of status IDs to filter by. To get lead status IDs, see List Lead Statuses.
  - `customer_source_ids` integer[]: An array of customer source IDs to filter by. To get customer source IDs, see List Customer Sources. Use -2 for no customer source.
  - `socials` string[]: An array of social profile URLs to filter by
  - `followed` 1 | 2: Filter by followed status. Use 1 for followed leads, 2 for not followed.
  - `age` integer: Maximum age in seconds of the lead
  - `minimum_monetary_value` number: Filter by minimum monetary value
  - `maximum_monetary_value` number: Filter by maximum monetary value
  - `minimum_interaction_count` integer: Filter by minimum number of interactions the lead has had
  - `maximum_interaction_count` integer: Filter by maximum number of interactions the lead has had
  - `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
  - `include_converted_leads` boolean: When true, includes converted leads in the response
  - `custom_fields` object[]: An array of custom field filters to search by. For multi-select fields, you can optionally include an 'option' property set to 'ANY' to match any of the specified values.
    - `custom_field_definition_id` integer: The custom field definition ID to filter by
    - `value` unknown
    - `option` 'ANY': For multi-select fields, set to 'ANY' to match any of the specified values
  - `sort_by` 'name' | 'company_name' | 'title' | 'value' | 'email' | 'phone' | 'date_modified' | 'date_created' | 'city' | 'state' | 'country' | 'zip' | 'inactive_days' | 'socials': The field on which to sort the results. Note: date_modified and date_created sort from oldest to newest; inactive_days sorts from newest to oldest.
  - `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', 'status', 'email'). 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', 'company_name', 'title', 'email', 'phone_numbers', 'assignee_id', 'status', 'status_id', 'monetary_value', 'customer_source_id', 'tags', 'address', 'socials', 'websites', '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`

Leads 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` Lead[], required: Records returned for the requested page. The item schema depends on the endpoint using this envelope.
    - `id` integer, required: Unique identifier for the lead
    - `name` string, required: The first and last name of the lead
    - `prefix` string, nullable: Name prefix
    - `first_name` string: First name of the lead
    - `last_name` string: Last name of the lead
    - `middle_name` string, nullable: Middle name of the lead
    - `suffix` string, nullable: Name suffix
    - `address` object: An object containing the lead's address
      - `street` string
      - `city` string
      - `state` string
      - `postal_code` string
      - `country` string
    - `assignee_id` integer: Unique identifier of the user that will be the owner of the lead
    - `company_name` string: The name of the company to which the lead belongs
    - `customer_source_id` integer: Unique identifier of the customer source that generated this lead
    - `details` string: Description of the lead
    - `email` object: An object containing the lead's email address and category
      - `email` string, email
      - `category` string
    - `monetary_value` number: The expected monetary value of business with the lead
    - `phone_numbers` object[]: An array of phone numbers belonging to the lead
      - `number` string: A phone number
      - `category` string: The category of the phone number
    - `socials` object[]: An array of social profiles belonging to the lead
      - `url` string: The URL of a social profile
      - `category` string: The category of the social profile
    - `status` 'New' | 'Unqualified' | 'Contacted' | 'Qualified': A string representing the status of the lead
    - `status_id` integer: Unique identifier of the lead status
    - `tags` string[]: An array of the tags associated with the lead
    - `title` string: The professional title of the lead
    - `websites` object[]: An array of websites belonging to the lead
      - `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 lead. 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 lead was created
    - `date_modified` integer: A Unix timestamp representing the time at which this lead was last modified
    - `date_last_contacted` integer: A Unix timestamp representing the time at which this lead was last contacted

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