---
title: "List or filter opportunities"
method: GET
path: "/opportunity/"
tags: ["opportunities"]
---

# List or filter opportunities

`GET /opportunity/`

* All opportunity list responses contain the following aggregate values about all the matching objects (regardless of pagination / limits):
    * `total_results`: the total number of objects,
    * `count_by_value_period`: a dictionary containing the number of opportunities by value period, e.g. `{ 'one_time': 2, 'annual': 1, 'monthly': 1 }`,
    * `total_value_one_time`: the sum of the values of all one time opportunities,
    * `total_value_monthly`: the sum of the values of all monthly opportunities,
    * `total_value_annual`: the sum of the values of all annual opportunities,
    * `total_value_annualized`: the sum of the values of all opportunities where monthly opportunity values are multiplied by 12,
    * `expected_value_one_time`: the sum of the values of all one time opportunities multiplied by their confidence,
    * `expected_value_monthly`: the sum of the values of all monthly opportunities multiplied by their confidence,
    * `expected_value_annual`: the sum of the values of all annual opportunities multiplied by their confidence,
    * `expected_value_annualized`: the sum of the values of all opportunities multiplied by their confidence where monthly opportunity values are multiplied by 12,
* `query` is an optional search query filter. Only opportunity properties may be used in the filter. For example, `note:important` will only show opportunities which contain the text `important` in their note. Or, `status_change(old_status:active new_status:won date:yesterday)` will only show opportunities that transitioned from status `active` to status `won` on the previous day.
* `_order_by` allows: `date_won`, `date_updated`, `date_created`, `confidence`, `user_name`, `value`, `annualized_value`, `annualized_expected_value` (each of them allows descending order by prepending a minus, e.g. `_order_by=-date_won`).
* `value_period` allows: `one_time`, `monthly`, `annual`.
* Multiple values for `user_id`, `status_id`, `status_label`, `status_type` and `value_period` can be specified using the *in* operator, e.g. `status_type__in=active,won`.
* `_group_by` allows: `user_id`, `date_won__week`, `date_won__month`, `date_won__quarter` `date_won__year` to group results by the given criteria.

    When grouping results, the `data` array contains a list of groups instead of objects. A group consists of the following fields:
    * `key` containing a unique group key,
    * `objects` containing the list of objects for the given group,
    * `total_results` containing the number of total objects for the given group,
    * all aggregate values for the given group,
    * if grouping by year: `year`, containing the year for the given group,
    * if grouping by month: `year` and `month`, containing the year and month (1-12) for the given group,
    * if grouping by quarter: `year` and `quarter`, containing the year and quarter (1-4) for the given group,
    * if grouping by week: `weekyear` and `week`, containing the ISO week year and ISO week number for the given group,
    * if grouping by user: `user_id` and `user_name`, containing the user ID and full name of the user for the given group.

    Note that pagination still applies to objects and not groups. The last or first group may be cut off during pagination, therefore `total_results` may not match the length of `objects`. When paginating, the `key` value may be used to combine groups across multiple pages. Sorting using `_order_by` may be applied and sorts the items within each of the groups. Group order can be reversed by prepending a minus. For example,  `_group_by=-date_won__week` will show the most recent weeks first. When grouping by `user_id`, results are ordered by the user's full name.
* `lead_saved_search_id` is an optional lead Smart View filter.
* (deprecated) `lead_query` is an optional lead search text-based query filter. This parameter is now deprecated in favor of using the `lead_saved_search_id` Smart View ID parameter.

## Query parameters

- `_limit` integer
- `_skip` integer
- `_fields` string
- `lead_id` string, nullable
- `organization_id` string, nullable
- `user_id` string, nullable
- `user_id__in` string, nullable
- `status_id` string, nullable
- `status_id__in` string, nullable
- `status_type` string, nullable
- `status_type__in` string, nullable
- `status_label` string, nullable
- `status_label__in` string, nullable
- `status` string, nullable
- `status__in` string, nullable
- `date_won` string, nullable
- `date_won__gte` string, nullable
- `date_won__gt` string, nullable
- `date_won__lte` string, nullable
- `date_won__lt` string, nullable
- `date_created` string, nullable
- `date_created__gte` string, nullable
- `date_created__gt` string, nullable
- `date_created__lte` string, nullable
- `date_created__lt` string, nullable
- `date_updated` string, nullable
- `date_updated__gte` string, nullable
- `date_updated__gt` string, nullable
- `date_updated__lte` string, nullable
- `date_updated__lt` string, nullable
- `value_period` string, nullable
- `value_period__in` string, nullable
- `query` string, nullable
- `lead_query` string, nullable
- `lead_saved_search_id` string, nullable
- `is_stalled` string, nullable
- `_order_by` string, nullable
- `_group_by` string, nullable

## Response `200`

Successful response

- object
  - `data` Opportunity[], required
    - `annualized_expected_value` integer, nullable, required
    - `annualized_value` integer, nullable, required
    - `attachments` Attachment[]
      - `content_type` string, nullable, required
      - `filename` string, nullable, required
      - `size` integer, nullable, required
      - `thumbnail_url` string, nullable
      - `url` string, required
    - `comment_summary` CommentSummary
      - `comment_count` integer, required
      - `thread_id` string, required
    - `confidence` integer, required
    - `contact_id` string, nullable, required
    - `contact_name` string, nullable
    - `created_by` string, nullable, required
    - `created_by_name` string, nullable
    - `date_created` string, date-time, required
    - `date_lost` string, date-time, nullable, required
    - `date_updated` string, date-time, required
    - `date_won` string, date, nullable, required
    - `expected_value` integer, nullable, required
    - `id` string, required
    - `integration_links` RenderedIntegrationLink[]
      - `name` string, required
      - `url` string, required
    - `is_stalled` boolean
    - `lead_id` string, required
    - `lead_name` string, nullable
    - `lead_primary_email` ContactEmail
      - `email` string, required
      - `is_unsubscribed` boolean, required
      - `type` string, required
    - `lead_primary_phone` ContactPhone[], nullable
      - `country` string, nullable
      - `outbound_sms_blocked` boolean
      - `phone` string, required
      - `phone_formatted` string
      - `type` string, required
      - `tz_ids` string[]
    - `note` string, nullable, required
    - `note_html` string, nullable, required
    - `organization_id` string, required
    - `pipeline_id` string, nullable
    - `pipeline_name` string, nullable
    - `stall_status` StalledOpportunityActionItems
      - `communication_issue` 'no_issue' | 'cant_get_in_touch' | 'no_communication_attempts', required
      - `next_action` ActionItem, required
        - `action` 'mark_as_lost' | 'change_status' | 'follow_up' | 'adjust_close_date' | 'ask_someone_else_to_reach_out' | 'change_communication_method', required
        - `justification` string, required — A short justification for the recommended action in the sales pipeline. Maximum 2 sentences.
    - `status_display_name` string
    - `status_id` string, required
    - `status_label` string
    - `status_type` 'won' | 'lost' | 'active'
    - `suggested_action` OpportunitySuggestedAction
      - `action` 'change_status' | 'adjust_close_date' | 'follow_up_email' | 'follow_up_call' | 'follow_up_sms', required
      - `details` union, required
        - OpportunityChangeStatusActionDetails
          - `status_id` string, required
        - OpportunityFollowUpEmailActionDetails
          - `contact_id` string, required
          - `message_draft` string, required
          - `subject_draft` string, required
        - OpportunityFollowUpSMSActionDetails
          - `contact_id` string, required
          - `message_draft` string, required
        - OpportunityFollowUpCallActionDetails
          - `call_plan` string, required
          - `contact_id` string, required
        - OpportunityAdjustCloseDateActionDetails
          - `close_date` string, date, required
      - `justification` string, required
    - `updated_by` string, nullable, required
    - `updated_by_name` string, nullable
    - `user_id` string, required
    - `user_name` string, nullable
    - `value` integer, nullable, required
    - `value_currency` string, nullable
    - `value_formatted` string, nullable
    - `value_period` 'one_time' | 'monthly' | 'annual', required
  - `has_more` boolean, required

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/close/apis/close-api.md) · [All operations](https://skmtc.net/close/apis/close-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/close/close-api/revisions/0dcf3303e9d7/schema)