Close subpackage_opportunities API

openapi: 3.2.0
info:
  title: Endpoints Subpackage Opportunities API
  version: 1.0.0
servers:
- url: https://api.close.com/api/v1
tags:
- name: subpackage_opportunities
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):\n    * `total_results`: the total number of objects,\n    * `count_by_value_period`: a dictionary containing the number of opportunities by value period, e.g. `{ 'one_time': 2, 'annual': 1, 'monthly': 1 }`,\n    * `total_value_one_time`: the sum of the values of all one time opportunities,\n    * `total_value_monthly`: the sum of the values of all monthly opportunities,\n    * `total_value_annual`: the sum of the values of all annual opportunities,\n    * `total_value_annualized`: the sum of the values of all opportunities where monthly opportunity values are multiplied by 12,\n    * `expected_value_one_time`: the sum of the values of all one time opportunities multiplied by their confidence,\n    * `expected_value_monthly`: the sum of the values of all monthly opportunities multiplied by their confidence,\n    * `expected_value_annual`: the sum of the values of all annual opportunities multiplied by their confidence,\n    * `expected_value_annualized`: the sum of the values of all opportunities multiplied by their confidence where monthly opportunity values are multiplied by 12,\n* `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.\n* `_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`).\n* `value_period` allows: `one_time`, `monthly`, `annual`.\n* 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`.\n* `_group_by` allows: `user_id`, `date_won__week`, `date_won__month`, `date_won__quarter` `date_won__year` to group results by the given criteria.\n\n    When grouping results, the `data` array contains a list of groups instead of objects. A group consists of the following fields:\n    * `key` containing a unique group key,\n    * `objects` containing the list of objects for the given group,\n    * `total_results` containing the number of total objects for the given group,\n    * all aggregate values for the given group,\n    * if grouping by year: `year`, containing the year for the given group,\n    * if grouping by month: `year` and `month`, containing the year and month (1-12) for the given group,\n    * if grouping by quarter: `year` and `quarter`, containing the year and quarter (1-4) for the given group,\n    * if grouping by week: `weekyear` and `week`, containing the ISO week year and ISO week number for the given group,\n    * if grouping by user: `user_id` and `user_name`, containing the user ID and full name of the user for the given group.\n\n    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.\n* `lead_saved_search_id` is an optional lead Smart View filter.\n* (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: Use your API key as the username and leave the password empty.
        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
    post:
      operationId: create
      summary: Create an opportunity
      description: '**lead_id** (optional): Opportunities belong to exactly one Lead. If you do not provide a `lead_id` then a new lead will be created (appearing as "Untitled" in the UI).


        **custom.FIELD_ID** (optional): Set custom fields by setting `custom.FIELD_ID` to the field value, where FIELD_ID is the ID of the custom field, e.g.:


        ```json

        { "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": "value", "custom.cf_8wtBWsdRU2Fur7GDnEeXQ7ra2Vu7R4hG1SNYdiEhh0F": "other value" }

        ```


        If a custom field has `accepts_multiple_values: true`, the entire value will be replaced. For example, given an Opportunity has a Custom Choice Field with value `["A", "B"]`, adding choice `"C"` would mean setting the value to `["A", "B", "C"]`.


        Note that using the `custom` field dict or the `custom.FIELD_NAME` syntax (instead of custom field IDs) is deprecated and will be removed from the API. See [Custom Fields](https://developer.close.com/api/resources/custom-fields) for more details.'
      tags:
      - subpackage_opportunities
      parameters:
      - name: Authorization
        in: header
        description: Use your API key as the username and leave the password empty.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opportunity'
        '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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOpportunity'
  /opportunity/{id}/:
    get:
      operationId: get
      summary: Retrieve an opportunity
      tags:
      - subpackage_opportunities
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: _fields
        in: query
        description: Comma-separated list of fields to include in the response.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Use your API key as the username and leave the password empty.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opportunity'
        '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
    put:
      operationId: update
      summary: Update an opportunity
      description: '*status_id*


        - See description for `status_id` in `POST /opportunity/` above.

        - Setting the `status_id` to a status with a type of `won` will automatically set the `date_won` field if it is not already set or provided in the request. Reverting it from a `won` status to an `active` or `lost` will not automatically change `date_won`.


        *date_won* (optional):


        - If not set on the resource or in the request, the `date_won` will be set automatically to today''s date when setting `status_id` to a status with type `won`. The `x-tz-offset` header, used to pass your timezone''s UTC offset, will be taken into account.


        *custom.FIELD_ID* (optional)


        - See description for `custom.FIELD_ID` in `POST /opportunity/` above.

        - Additionally, you can unset a single field by using `{ "custom.FIELD_ID": null }`, e.g.:

        ```

        { "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": null }

        ```

        If you''re trying to update a custom field and that custom field accepts multiple values, you can also specify `.add` or `.remove` as part of the field key to add/remove a single value to/from a list of values, e.g.:

        ```

        { "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c.add": "Wednesday" }

        ```'
      tags:
      - subpackage_opportunities
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Use your API key as the username and leave the password empty.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opportunity'
        '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
      requestBody:
        content:
          application/json:
            schema:
              description: Any type
    delete:
      operationId: delete
      summary: Delete an opportunity
      tags:
      - subpackage_opportunities
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Use your API key as the username and leave the password empty.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/opportunities_delete_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
components:
  schemas:
    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
    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
    OpportunityStatusType:
      type: string
      enum:
      - won
      - lost
      - active
      title: OpportunityStatusType
    OpportunityFollowUpCallActionDetails:
      type: object
      properties:
        call_plan:
          type: string
        contact_id:
          type: string
      required:
      - call_plan
      - contact_id
      title: OpportunityFollowUpCallActionDetails
    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
    CommentSummary:
      type: object
      properties:
        comment_count:
          type: integer
        thread_id:
          type: string
      required:
      - comment_count
      - thread_id
      title: CommentSummary
    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
    OpportunitySuggestedActionDetails:
      oneOf:
      - $ref: '#/components/schemas/OpportunityChangeStatusActionDetails'
      - $ref: '#/components/schemas/OpportunityFollowUpEmailActionDetails'
      - $ref: '#/components/schemas/OpportunityFollowUpSMSActionDetails'
      - $ref: '#/components/schemas/OpportunityFollowUpCallActionDetails'
      - $ref: '#/components/schemas/OpportunityAdjustCloseDateActionDetails'
      title: OpportunitySuggestedActionDetails
    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
    CreateOpportunity:
      type: object
      properties:
        attachments:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AttachmentIn'
        confidence:
          type:
          - integer
          - 'null'
        contact_id:
          type:
          - string
          - 'null'
        created_by:
          type:
          - string
          - 'null'
        custom_fields:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
        date_created:
          type:
          - string
          - 'null'
          format: date-time
        date_won:
          type:
          - string
          - 'null'
          format: date-time
        lead_id:
          type:
          - string
          - 'null'
        note:
          type:
          - string
          - 'null'
        pipeline_id:
          type:
          - string
          - 'null'
          description: Specify which pipeline this opportunity should belong to. When supplied without `status_id`, the opportunity will be created with the first available status of that pipeline. When supplied with `status_id`, the status must belong to the specified pipeline or a 400 error will be returned. If the pipeline does not exist, a 400 error will be returned. See the [Pipelines API](https://developer.close.com/api/resources/pipelines).
        status_id:
          type:
          - string
          - 'null'
          description: Post a `status_id` to create an opportunity with a specific status. If omitted, the organization's default (first) status will be used (or the first status of the `pipeline_id` if provided). See the [Opportunity Status API](https://developer.close.com/api/resources/opportunity-statuses).
        user_id:
          type:
          - string
          - 'null'
        value:
          type:
          - integer
          - 'null'
        value_period:
          oneOf:
          - $ref: '#/components/schemas/OpportunityValuePeriod'
          - type: 'null'
      title: CreateOpportunity
    opportunities_delete_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: opportunities_delete_Response_200
    AttachmentIn:
      type: object
      properties:
        content_type:
          type: string
          default: ''
        filename:
          type: string
        url:
          type: string
      required:
      - filename
      - url
      title: AttachmentIn
    StalledOpportunityActionTypeV2:
      type: string
      enum:
      - change_status
      - adjust_close_date
      - follow_up_email
      - follow_up_call
      - follow_up_sms
      title: StalledOpportunityActionTypeV2
    ContactEmail:
      type: object
      properties:
        email:
          type: string
        is_unsubscribed:
          type: boolean
        type:
          type: string
      required:
      - email
      - is_unsubscribed
      - type
      title: ContactEmail
    OpportunityAdjustCloseDateActionDetails:
      type: object
      properties:
        close_date:
          type: string
          format: date
      required:
      - close_date
      title: OpportunityAdjustCloseDateActionDetails
    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
    RenderedIntegrationLink:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
      required:
      - name
      - url
      title: RenderedIntegrationLink
    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
    OpportunityValuePeriod:
      type: string
      enum:
      - one_time
      - monthly
      - annual
      title: OpportunityValuePeriod
    StalledOpportunityCommunicationIssue:
      type: string
      enum:
      - no_issue
      - cant_get_in_touch
      - no_communication_attempts
      title: StalledOpportunityCommunicationIssue
    OpportunityChangeStatusActionDetails:
      type: object
      properties:
        status_id:
          type: string
      required:
      - status_id
      title: OpportunityChangeStatusActionDetails
    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
    OpportunityFollowUpSMSActionDetails:
      type: object
      properties:
        contact_id:
          type: string
        message_draft:
          type: string
      required:
      - contact_id
      - message_draft
      title: OpportunityFollowUpSMSActionDetails
    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
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: basic
      description: Use your API key as the username and leave the password empty.
    OAuth2:
      type: http
      scheme: bearer