# List or filter opportunities

GET https://api.close.com/api/v1/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.

Reference: https://developer.close.com/api/resources/opportunities/list

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: Close API
  version: 1.0.0
paths:
  /opportunity/:
    get:
      operationId: list
      summary: List or filter opportunities
      description: >-
        * 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.
      tags:
        - subpackage_opportunities
      parameters:
        - name: _limit
          in: query
          description: Number of results to return.
          required: false
          schema:
            type: integer
            default: 100
        - name: _skip
          in: query
          description: Number of results to skip before returning, for pagination.
          required: false
          schema:
            type: integer
            default: 0
        - name: _fields
          in: query
          description: Comma-separated list of fields to include in the response.
          required: false
          schema:
            type: string
        - name: lead_id
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: organization_id
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: user_id
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: user_id__in
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: status_id
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: status_id__in
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: status_type
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: status_type__in
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: status_label
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: status_label__in
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: status
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: status__in
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_won
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_won__gte
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_won__gt
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_won__lte
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_won__lt
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_created
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_created__gte
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_created__gt
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_created__lte
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_created__lt
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_updated
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_updated__gte
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_updated__gt
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_updated__lte
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: date_updated__lt
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: value_period
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: value_period__in
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: query
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: lead_query
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: lead_saved_search_id
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: is_stalled
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: _order_by
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: _group_by
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: Authorization
          in: header
          description: Basic authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/opportunities_list_Response_200'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Any type
servers:
  - url: https://api.close.com/api/v1
components:
  schemas:
    Attachment:
      type: object
      properties:
        content_type:
          type:
            - string
            - 'null'
        filename:
          type:
            - string
            - 'null'
        size:
          type:
            - integer
            - 'null'
        thumbnail_url:
          type:
            - string
            - 'null'
        url:
          type: string
      required:
        - content_type
        - filename
        - size
        - url
      title: Attachment
    CommentSummary:
      type: object
      properties:
        comment_count:
          type: integer
        thread_id:
          type: string
      required:
        - comment_count
        - thread_id
      title: CommentSummary
    RenderedIntegrationLink:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
      required:
        - name
        - url
      title: RenderedIntegrationLink
    ContactEmail:
      type: object
      properties:
        email:
          type: string
        is_unsubscribed:
          type: boolean
        type:
          type: string
      required:
        - email
        - is_unsubscribed
        - type
      title: ContactEmail
    ContactPhone:
      type: object
      properties:
        country:
          type:
            - string
            - 'null'
        outbound_sms_blocked:
          type: boolean
        phone:
          type: string
        phone_formatted:
          type: string
        type:
          type: string
        tz_ids:
          type: array
          items:
            type: string
      required:
        - phone
        - type
      title: ContactPhone
    StalledOpportunityCommunicationIssue:
      type: string
      enum:
        - no_issue
        - cant_get_in_touch
        - no_communication_attempts
      title: StalledOpportunityCommunicationIssue
    StalledOpportunityActionTypeV1:
      type: string
      enum:
        - mark_as_lost
        - change_status
        - follow_up
        - adjust_close_date
        - ask_someone_else_to_reach_out
        - change_communication_method
      title: StalledOpportunityActionTypeV1
    ActionItem:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/StalledOpportunityActionTypeV1'
          description: >-
            The recommended next step to progress or resolve the stalled
            opportunity
        justification:
          type: string
          description: >-
            A short justification for the recommended action in the sales
            pipeline. Maximum 2 sentences.
      required:
        - action
        - justification
      title: ActionItem
    StalledOpportunityActionItems:
      type: object
      properties:
        communication_issue:
          $ref: '#/components/schemas/StalledOpportunityCommunicationIssue'
          description: >-
            The communication issue that is causing the stalled opportunity. If
            there is no issue, set to NoIssue.
        next_action:
          $ref: '#/components/schemas/ActionItem'
          description: >-
            An action item recommended to progress or resolve the stalled
            opportunity.
      required:
        - communication_issue
        - next_action
      title: StalledOpportunityActionItems
    OpportunityStatusType:
      type: string
      enum:
        - won
        - lost
        - active
      title: OpportunityStatusType
    StalledOpportunityActionTypeV2:
      type: string
      enum:
        - change_status
        - adjust_close_date
        - follow_up_email
        - follow_up_call
        - follow_up_sms
      title: StalledOpportunityActionTypeV2
    OpportunityChangeStatusActionDetails:
      type: object
      properties:
        status_id:
          type: string
      required:
        - status_id
      title: OpportunityChangeStatusActionDetails
    OpportunityFollowUpEmailActionDetails:
      type: object
      properties:
        contact_id:
          type: string
        message_draft:
          type: string
        subject_draft:
          type: string
      required:
        - contact_id
        - message_draft
        - subject_draft
      title: OpportunityFollowUpEmailActionDetails
    OpportunityFollowUpSMSActionDetails:
      type: object
      properties:
        contact_id:
          type: string
        message_draft:
          type: string
      required:
        - contact_id
        - message_draft
      title: OpportunityFollowUpSMSActionDetails
    OpportunityFollowUpCallActionDetails:
      type: object
      properties:
        call_plan:
          type: string
        contact_id:
          type: string
      required:
        - call_plan
        - contact_id
      title: OpportunityFollowUpCallActionDetails
    OpportunityAdjustCloseDateActionDetails:
      type: object
      properties:
        close_date:
          type: string
          format: date
      required:
        - close_date
      title: OpportunityAdjustCloseDateActionDetails
    OpportunitySuggestedActionDetails:
      oneOf:
        - $ref: '#/components/schemas/OpportunityChangeStatusActionDetails'
        - $ref: '#/components/schemas/OpportunityFollowUpEmailActionDetails'
        - $ref: '#/components/schemas/OpportunityFollowUpSMSActionDetails'
        - $ref: '#/components/schemas/OpportunityFollowUpCallActionDetails'
        - $ref: '#/components/schemas/OpportunityAdjustCloseDateActionDetails'
      title: OpportunitySuggestedActionDetails
    OpportunitySuggestedAction:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/StalledOpportunityActionTypeV2'
        details:
          oneOf:
            - $ref: '#/components/schemas/OpportunitySuggestedActionDetails'
            - type: 'null'
        justification:
          type: string
      required:
        - action
        - details
        - justification
      title: OpportunitySuggestedAction
    OpportunityValuePeriod:
      type: string
      enum:
        - one_time
        - monthly
        - annual
      title: OpportunityValuePeriod
    Opportunity:
      type: object
      properties:
        annualized_expected_value:
          type:
            - integer
            - 'null'
        annualized_value:
          type:
            - integer
            - 'null'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        comment_summary:
          oneOf:
            - $ref: '#/components/schemas/CommentSummary'
            - type: 'null'
        confidence:
          type: integer
        contact_id:
          type:
            - string
            - 'null'
        contact_name:
          type:
            - string
            - 'null'
        created_by:
          type:
            - string
            - 'null'
        created_by_name:
          type:
            - string
            - 'null'
        date_created:
          type: string
          format: date-time
        date_lost:
          type:
            - string
            - 'null'
          format: date-time
        date_updated:
          type: string
          format: date-time
        date_won:
          type:
            - string
            - 'null'
          format: date
        expected_value:
          type:
            - integer
            - 'null'
        id:
          type: string
        integration_links:
          type: array
          items:
            $ref: '#/components/schemas/RenderedIntegrationLink'
        is_stalled:
          type: boolean
        lead_id:
          type: string
        lead_name:
          type:
            - string
            - 'null'
        lead_primary_email:
          oneOf:
            - $ref: '#/components/schemas/ContactEmail'
            - type: 'null'
        lead_primary_phone:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ContactPhone'
        note:
          type:
            - string
            - 'null'
        organization_id:
          type: string
        pipeline_id:
          type:
            - string
            - 'null'
        pipeline_name:
          type:
            - string
            - 'null'
        stall_status:
          oneOf:
            - $ref: '#/components/schemas/StalledOpportunityActionItems'
            - type: 'null'
        status_display_name:
          type: string
        status_id:
          type: string
        status_label:
          type: string
        status_type:
          $ref: '#/components/schemas/OpportunityStatusType'
        suggested_action:
          oneOf:
            - $ref: '#/components/schemas/OpportunitySuggestedAction'
            - type: 'null'
        updated_by:
          type:
            - string
            - 'null'
        updated_by_name:
          type:
            - string
            - 'null'
        user_id:
          type: string
        user_name:
          type:
            - string
            - 'null'
        value:
          type:
            - integer
            - 'null'
        value_currency:
          type:
            - string
            - 'null'
        value_formatted:
          type:
            - string
            - 'null'
        value_period:
          $ref: '#/components/schemas/OpportunityValuePeriod'
      required:
        - annualized_expected_value
        - annualized_value
        - confidence
        - contact_id
        - created_by
        - date_created
        - date_lost
        - date_updated
        - date_won
        - expected_value
        - id
        - lead_id
        - note
        - organization_id
        - status_id
        - updated_by
        - user_id
        - value
        - value_period
      title: Opportunity
    opportunities_list_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Opportunity'
        has_more:
          type: boolean
      required:
        - data
        - has_more
      title: opportunities_list_Response_200
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: basic
    OAuth2:
      type: http
      scheme: bearer

```