COcopper
Leads

Search leads

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.

post/leads/search

Request

  • Base URL
    https://api.copper.com/developer_api/v1
  • Auth
    HTTP bearer

Query parameters

custom_field_computed_valuesboolean

When true, returns computed custom field values (human-readable labels) in addition to option IDs for Dropdown and Multi-select fields. The response will include a 'computed_value' field alongside the 'value' field in custom_fields array.

Request body

idsinteger[]

An array of Lead IDs to retrieve

namestring

Filter by lead's full name (first and last name)

first_namestring

Filter by lead's first name

last_namestring

Filter by lead's last name

middle_namestring

Filter by lead's middle name

emailsstring email

Filter by email address

phone_numberstring

Filter by phone number

company_namestring

Filter by the name of the company the lead belongs to

titlestring

Filter by professional title

citystring

Filter by city in address

statestring

Filter by state in address

postal_codestring

Filter by postal code in address

countrystring

Filter by country in address (two-character country code)

tagsstring[]

An array of tags to filter by

assignee_idsinteger[]

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_idsinteger[]

An array of status IDs to filter by. To get lead status IDs, see List Lead Statuses.

customer_source_idsinteger[]

An array of customer source IDs to filter by. To get customer source IDs, see List Customer Sources. Use -2 for no customer source.

socialsstring[]

An array of social profile URLs to filter by

followed1 | 2

Filter by followed status. Use 1 for followed leads, 2 for not followed.

ageinteger

Maximum age in seconds of the lead

minimum_monetary_valuenumber

Filter by minimum monetary value

maximum_monetary_valuenumber

Filter by maximum monetary value

minimum_interaction_countinteger

Filter by minimum number of interactions the lead has had

maximum_interaction_countinteger

Filter by maximum number of interactions the lead has had

minimum_interaction_dateinteger

Unix timestamp for the earliest date of the last interaction

maximum_interaction_dateinteger

Unix timestamp for the latest date of the last interaction

minimum_created_dateinteger

Unix timestamp for the minimum creation date

maximum_created_dateinteger

Unix timestamp for the maximum creation date

minimum_modified_dateinteger

Unix timestamp for the minimum modification date

maximum_modified_dateinteger

Unix timestamp for the maximum modification date

include_converted_leadsboolean

When true, includes converted leads in the response

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_numberinteger

The page number (starting with 1) that you would like to view

page_sizeinteger

The number of entries included in a page of results

Example request

{
  "fields": [
    "id",
    "name",
    "company_name",
    "status",
    "assignee_id"
  ]
}

Response

Leads retrieved successfully

page_numberinteger required

Current page number (defaults to 1 when not provided in the request).

totalinteger required

Total number of records that match the request filters (equivalent to the X-PW-TOTAL header).

Example response

{
  "page_number": 1,
  "total": 775,
  "data": []
}

Changes

No recorded changes to this operation across all 1 revision of this API.