--- title: "Search opportunities" method: POST path: "/opportunities/search" tags: ["Opportunities"] --- # Search opportunities `POST /opportunities/search` ## Request - Base URL: `https://api.copper.com/developer_api/v1` - URL: `https://api.copper.com/developer_api/v1/opportunities/search` - Auth: HTTP bearer Search opportunities. 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 Opportunity IDs to retrieve - `name` union: Filter by opportunity 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: '2024 Q4 Deal' will only match opportunities named exactly '2024 Q4 Deal'. - object: Advanced object format for controlling match type - `value` string, required: The opportunity 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., 'Q4' matches '2024 Q4 Deal'), 'exact' for exact match - `company_name` string: Filter by the name of the primary company associated with the opportunity - `company_ids` integer[]: An array of company IDs to filter by (the companies these opportunities are associated with). Use -2 for no company. - `primary_contact_ids` integer[]: An array of person IDs who are the primary contacts for these opportunities - `close_date` integer: Filter by expected close date (Unix timestamp) - `minimum_close_date` integer: Filter by minimum close date (Unix timestamp) - `maximum_close_date` integer: Filter by maximum close date (Unix timestamp) - `minimum_monetary_value` number: Filter by minimum monetary value - `maximum_monetary_value` number: Filter by maximum monetary value - `minimum_win_probability` integer: Filter by minimum win probability (0-100) - `maximum_win_probability` integer: Filter by maximum win probability (0-100) - `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 opportunities). Use -2 for no assignee. - `pipeline_ids` integer[]: An array of pipeline IDs to filter by - `pipeline_stage_ids` integer[]: An array of pipeline stage IDs to filter by - `statuses` string[]: An array of statuses to filter by - `priorities` string[]: An array of priorities to filter by - `loss_reason_ids` integer[]: An array of loss reason IDs to filter by (for Lost opportunities) - `customer_source_ids` integer[]: An array of customer source IDs to filter by - `followed` 1 | 2: Filter by followed status. Use 1 for followed opportunities, 2 for not followed. - `age` integer: Maximum age in seconds of the opportunity 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_date_stage_changed` integer: Unix timestamp for the minimum date when the pipeline stage was changed - `maximum_date_stage_changed` integer: Unix timestamp for the maximum date when the pipeline stage was changed - `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, or use option: 'ANY' to match any of the specified values. - `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 - `option` 'ANY': For multi-select fields, set to 'ANY' to match any of the specified values - `sort_by` 'assignee' | 'company_name' | 'customer_source_id' | 'date_created' | 'date_modified' | 'inactive_days' | 'interaction_count' | 'last_interaction' | 'monetary_unit' | 'monetary_value' | 'name' | 'primary_contact' | 'priority' | 'stage' | 'status': The field on which to sort the results. Possible values: assignee, company_name, customer_source_id, date_created, date_modified, inactive_days, interaction_count, last_interaction, monetary_unit, monetary_value, name, primary_contact, priority, stage, status - `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. For ChatGPT/Copper GPT, ALWAYS limit to the minimal set of fields needed for the current question. Default minimal set for deal analytics is: 'id', 'name', 'company_id', 'pipeline_id', 'pipeline_stage_id', 'monetary_value', 'close_date', 'assignee_id', 'status'. DO NOT request 'details', 'custom_fields', or 'custom_field_computed_values' unless the user explicitly asks for those values. - union - string: System field name (e.g., 'id', 'name', 'status', 'monetary_value', 'close_date', 'pipeline_id', 'pipeline_stage_id', 'assignee_id', 'company_ids', 'primary_contact_id', 'tags') - 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` Opportunities 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` Opportunity[], required: Records returned for the requested page. The item schema depends on the endpoint using this envelope. - `id` integer, required: Unique identifier for the opportunity - `name` string, required: The name of the opportunity - `assignee_id` integer, nullable: Unique identifier of the user that will be the owner of the opportunity - `close_date` integer, nullable: The expected close date of the opportunity (Unix timestamp) - `company_id` integer, nullable: The unique identifier of the primary company with which the opportunity is associated - `company_name` string, nullable: The name of the primary company with which the opportunity is associated - `customer_source_id` integer, nullable: Unique identifier of the customer source that generated this opportunity - `details` string, nullable: Description of the opportunity - `loss_reason_id` integer, nullable: If the opportunity's status is 'Lost', the unique identifier of the loss reason that caused this opportunity to be lost - `monetary_value` number, nullable: The monetary value of the opportunity - `pipeline_id` integer: The unique identifier of the pipeline in which this opportunity is - `pipeline_is_revenue` boolean: The revenue type of the pipeline associated with the opportunity - `pipeline_stage_id` integer: The unique identifier of the pipeline stage of the opportunity - `pipeline_type` 'opportunity' | 'project' | 'item': The type of the pipeline ('opportunity', 'project', or 'item') associated with the opportunity - `primary_contact_id` integer, nullable: The unique identifier of the person who is the primary contact for this opportunity - `priority` 'None' | 'Low' | 'Medium' | 'High': The priority of the opportunity - `status` 'Open' | 'Won' | 'Lost' | 'Abandoned': The status of the opportunity - `tags` string[]: An array of the tags associated with the opportunity - `win_probability` integer: The expected probability of winning the opportunity. Valid values are [0-100] (inclusive) - `interaction_count` integer: The number of interactions with this opportunity - `date_created` integer: A Unix timestamp representing the time at which this opportunity was created - `date_modified` integer: A Unix timestamp representing the time at which this opportunity was last modified - `custom_fields` object[]: An array of custom field values belonging to the opportunity. 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 ## 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)