Close Pipelines & Statuses API
Manage opportunity pipelines and the configurable lead and opportunity statuses driving funnel progression.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Endpoints
version: 1.0.0
paths:
/lead/:
get:
operationId: list
summary: List Leads
tags:
- subpackage_leads
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: 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/leads_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 a new lead
description: >-
Contacts, addresses, and custom fields can all be nested in the lead. Activities, tasks, and opportunities must
be posted separately.
**status / status_id** (optional): Post either `status` or `status_id` (but not both). If neither is provided,
the organization's default (first) status will be used. Using `status_id` is recommended so that users can
rename statuses in the UI without breaking your implementation.
**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 a
Lead 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_leads
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/Lead'
'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
/lead/merge/:
post:
operationId: merge
summary: Merge two leads
description: For details and definitions of 'source' and 'destination', see the Merge Leads feature in the UI.
tags:
- subpackage_leads
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/leads_merge_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
requestBody:
content:
application/json:
schema:
description: Any type
/lead/{id}/:
get:
operationId: get
summary: Get a single Lead
tags:
- subpackage_leads
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/Lead'
'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 existing lead
description: >-
Supports non-destructive patches. Nested `contacts` cannot be updated through this endpoint -- use the Contacts
API instead.
**status**: See `status` and `status_id` guidance on the create endpoint.
**custom.FIELD_ID** (optional): See `custom.FIELD_ID` guidance on the create endpoint. You can also unset a
single field, e.g.:
```json
{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": null }
```
If the custom field accepts multiple values, you can specify `.add` or `.remove` as part of the field key to
add/remove a single value to/from a list of values, e.g.:
```json
{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c.add": "Wednesday" }
```
adds "Wednesday" to the list of values which already exist on the given lead.
tags:
- subpackage_leads
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/Lead'
'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 a lead
tags:
- subpackage_leads
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/leads_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
/contact/:
get:
operationId: list
summary: List contacts
tags:
- subpackage_contacts
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
- 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/contacts_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 a new contact
description: >-
Contacts belong to exactly one Lead (specified by `lead_id`). If you do not provide a `lead_id` then a new lead
will be created, named after the contact.
tags:
- subpackage_contacts
parameters:
- 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/Contact'
'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
/contact/{id}/:
get:
operationId: get
summary: Fetch a single contact
tags:
- subpackage_contacts
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/Contact'
'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 existing contact
description: >-
Update a contact's information. If you're trying to update a custom field and that custom field accepts multiple
values, you can specify `.add` or `.remove` as part of the field key to add/remove a single value to/from a list
of values, e.g.:
```json
{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c.add": "Wednesday" }
```
adds "Wednesday" to the list of values which already exist on the given contact.
tags:
- subpackage_contacts
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/Contact'
'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 a contact
tags:
- subpackage_contacts
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/contacts_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
/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: 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:
descri
# --- truncated at 32 KB (676 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/close/refs/heads/main/openapi/close-openapi.yml