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