openapi: 3.1.0 info: title: API Endpoints subpackage_activities 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: StalledOpportunityActionTypeV2: type: string enum: - change_status - adjust_close_date - follow_up_email - follow_up_call - follow_up_sms title: StalledOpportunityActionTypeV2 AttachmentIn: type: object properties: content_type: type: string default: '' filename: type: string url: type: string required: - filename - url title: AttachmentIn OpportunitySuggestedActionDetails: oneOf: - $ref: '#/components/schemas/OpportunityChangeStatusActionDetails' - $ref: '#/components/schemas/OpportunityFollowUpEmailActionDetails' - $ref: '#/components/schemas/OpportunityFollowUpSMSActionDetails' - $ref: '#/components/schemas/OpportunityFollowUpCallActionDetails' - $ref: '#/components/schemas/OpportunityAdjustCloseDateActionDetails' title: OpportunitySuggestedActionDetails 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 OpportunityValuePeriod: type: string enum: - one_time - monthly - annual title: OpportunityValuePeriod 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 OpportunityAdjustCloseDateActionDetails: type: object properties: close_date: type: string format: date required: - close_date title: OpportunityAdjustCloseDateActionDetails opportunities_delete_Response_200: type: object properties: {} description: Empty response body title: opportunities_delete_Response_200 StalledOpportunityCommunicationIssue: type: string enum: - no_issue - cant_get_in_touch - no_communication_attempts title: StalledOpportunityCommunicationIssue 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 OpportunityFollowUpSMSActionDetails: type: object properties: contact_id: type: string message_draft: type: string required: - contact_id - message_draft title: OpportunityFollowUpSMSActionDetails 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 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 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 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 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 OpportunityChangeStatusActionDetails: type: object properties: status_id: type: string required: - status_id title: OpportunityChangeStatusActionDetails 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 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 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 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 securitySchemes: ApiKeyAuth: type: http scheme: basic description: Use your API key as the username and leave the password empty. OAuth2: type: http scheme: bearer