> For a complete page index, fetch https://developer.close.com/llms.txt

# List or filter opportunities

GET https://api.close.com/api/v1/opportunity/

* All opportunity list responses contain the following aggregate values about all the matching objects (regardless of pagination / limits):
  * `total_results`: the total number of objects,
  * `count_by_value_period`: a dictionary containing the number of opportunities by value period, e.g. `{ 'one_time': 2, 'annual': 1, 'monthly': 1 }`,
  * `total_value_one_time`: the sum of the values of all one time opportunities,
  * `total_value_monthly`: the sum of the values of all monthly opportunities,
  * `total_value_annual`: the sum of the values of all annual opportunities,
  * `total_value_annualized`: the sum of the values of all opportunities where monthly opportunity values are multiplied by 12,
  * `expected_value_one_time`: the sum of the values of all one time opportunities multiplied by their confidence,
  * `expected_value_monthly`: the sum of the values of all monthly opportunities multiplied by their confidence,
  * `expected_value_annual`: the sum of the values of all annual opportunities multiplied by their confidence,
  * `expected_value_annualized`: the sum of the values of all opportunities multiplied by their confidence where monthly opportunity values are multiplied by 12,
* `query` is an optional search query filter. Only opportunity properties may be used in the filter. For example, `note:important` will only show opportunities which contain the text `important` in their note. Or, `status_change(old_status:active new_status:won date:yesterday)` will only show opportunities that transitioned from status `active` to status `won` on the previous day.
* `_order_by` allows: `date_won`, `date_updated`, `date_created`, `confidence`, `user_name`, `value`, `annualized_value`, `annualized_expected_value` (each of them allows descending order by prepending a minus, e.g. `_order_by=-date_won`).
* `value_period` allows: `one_time`, `monthly`, `annual`.
* Multiple values for `user_id`, `status_id`, `status_label`, `status_type` and `value_period` can be specified using the *in* operator, e.g. `status_type__in=active,won`.
* `_group_by` allows: `user_id`, `date_won__week`, `date_won__month`, `date_won__quarter` `date_won__year` to group results by the given criteria.

  When grouping results, the `data` array contains a list of groups instead of objects. A group consists of the following fields:

  * `key` containing a unique group key,
  * `objects` containing the list of objects for the given group,
  * `total_results` containing the number of total objects for the given group,
  * all aggregate values for the given group,
  * if grouping by year: `year`, containing the year for the given group,
  * if grouping by month: `year` and `month`, containing the year and month (1-12) for the given group,
  * if grouping by quarter: `year` and `quarter`, containing the year and quarter (1-4) for the given group,
  * if grouping by week: `weekyear` and `week`, containing the ISO week year and ISO week number for the given group,
  * if grouping by user: `user_id` and `user_name`, containing the user ID and full name of the user for the given group.

  Note that pagination still applies to objects and not groups. The last or first group may be cut off during pagination, therefore `total_results` may not match the length of `objects`. When paginating, the `key` value may be used to combine groups across multiple pages. Sorting using `_order_by` may be applied and sorts the items within each of the groups. Group order can be reversed by prepending a minus. For example,  `_group_by=-date_won__week` will show the most recent weeks first. When grouping by `user_id`, results are ordered by the user's full name.
* `lead_saved_search_id` is an optional lead Smart View filter.
* (deprecated) `lead_query` is an optional lead search text-based query filter. This parameter is now deprecated in favor of using the `lead_saved_search_id` Smart View ID parameter.

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

## Authentication

- `Authorization` header (basic auth, required) — Use your API key as the username and leave the password empty.
- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Query parameters

- `_limit` (integer, optional, default: 100) — Number of results to return.
- `_skip` (integer, optional, default: 0) — Number of results to skip before returning, for pagination.
- `_fields` (string, optional) — Comma-separated list of fields to include in the response.
- `lead_id` (string, optional, nullable)
- `organization_id` (string, optional, nullable)
- `user_id` (string, optional, nullable)
- `user_id__in` (string, optional, nullable)
- `status_id` (string, optional, nullable)
- `status_id__in` (string, optional, nullable)
- `status_type` (string, optional, nullable)
- `status_type__in` (string, optional, nullable)
- `status_label` (string, optional, nullable)
- `status_label__in` (string, optional, nullable)
- `status` (string, optional, nullable)
- `status__in` (string, optional, nullable)
- `date_won` (string, optional, nullable)
- `date_won__gte` (string, optional, nullable)
- `date_won__gt` (string, optional, nullable)
- `date_won__lte` (string, optional, nullable)
- `date_won__lt` (string, optional, nullable)
- `date_created` (string, optional, nullable)
- `date_created__gte` (string, optional, nullable)
- `date_created__gt` (string, optional, nullable)
- `date_created__lte` (string, optional, nullable)
- `date_created__lt` (string, optional, nullable)
- `date_updated` (string, optional, nullable)
- `date_updated__gte` (string, optional, nullable)
- `date_updated__gt` (string, optional, nullable)
- `date_updated__lte` (string, optional, nullable)
- `date_updated__lt` (string, optional, nullable)
- `value_period` (string, optional, nullable)
- `value_period__in` (string, optional, nullable)
- `query` (string, optional, nullable)
- `lead_query` (string, optional, nullable)
- `lead_saved_search_id` (string, optional, nullable)
- `is_stalled` (string, optional, nullable)
- `_order_by` (string, optional, nullable)
- `_group_by` (string, optional, nullable)

## Response

### 200

Successful response

- `data` (list of Opportunity, required)
- `has_more` (boolean, required)

## Errors

### 400 Bad Request Error

Bad request

- `any`

### 401 Unauthorized Error

Unauthorized

- `any`

### 404 Not Found Error

Not found

- `any`

## Types

### Opportunity

- `annualized_expected_value` (integer, required, nullable)
- `annualized_value` (integer, required, nullable)
- `confidence` (integer, required)
- `contact_id` (string, required, nullable)
- `created_by` (string, required, nullable)
- `date_created` (datetime, required)
- `date_lost` (datetime, required, nullable)
- `date_updated` (datetime, required)
- `date_won` (date, required, nullable)
- `expected_value` (integer, required, nullable)
- `id` (string, required)
- `lead_id` (string, required)
- `note` (string, required, nullable)
- `note_html` (string, required, nullable)
- `organization_id` (string, required)
- `status_id` (string, required)
- `updated_by` (string, required, nullable)
- `user_id` (string, required)
- `value` (integer, required, nullable)
- `value_period` (enum, required)
  - Allowed values: `one_time`, `monthly`, `annual`
- `attachments` (list of Attachment, optional)
- `comment_summary` (CommentSummary, optional, nullable)
- `contact_name` (string, optional, nullable)
- `created_by_name` (string, optional, nullable)
- `integration_links` (list of RenderedIntegrationLink, optional)
- `is_stalled` (boolean, optional)
- `lead_name` (string, optional, nullable)
- `lead_primary_email` (ContactEmail, optional, nullable)
- `lead_primary_phone` (list of ContactPhone, optional, nullable)
- `pipeline_id` (string, optional, nullable)
- `pipeline_name` (string, optional, nullable)
- `stall_status` (StalledOpportunityActionItems, optional, nullable)
- `status_display_name` (string, optional)
- `status_label` (string, optional)
- `status_type` (enum, optional)
  - Allowed values: `won`, `lost`, `active`
- `suggested_action` (OpportunitySuggestedAction, optional, nullable)
- `updated_by_name` (string, optional, nullable)
- `user_name` (string, optional, nullable)
- `value_currency` (string, optional, nullable)
- `value_formatted` (string, optional, nullable)

### Attachment

- `content_type` (string, required, nullable)
- `filename` (string, required, nullable)
- `size` (integer, required, nullable)
- `url` (string, required)
- `thumbnail_url` (string, optional, nullable)

### CommentSummary

- `comment_count` (integer, required)
- `thread_id` (string, required)

### RenderedIntegrationLink

- `name` (string, required)
- `url` (string, required)

### ContactEmail

- `email` (string, required)
- `is_unsubscribed` (boolean, required)
- `type` (string, required)

### ContactPhone

- `phone` (string, required)
- `type` (string, required)
- `country` (string, optional, nullable)
- `outbound_sms_blocked` (boolean, optional)
- `phone_formatted` (string, optional)
- `tz_ids` (list of string, optional)

### StalledOpportunityActionItems

- `communication_issue` (enum, required) — The communication issue that is causing the stalled opportunity. If there is no issue, set to NoIssue.
  - Allowed values: `no_issue`, `cant_get_in_touch`, `no_communication_attempts`
- `next_action` (ActionItem, required, deprecated) — An action item recommended to progress or resolve the stalled opportunity.

### OpportunitySuggestedAction

- `action` (enum, required)
  - Allowed values: `change_status`, `adjust_close_date`, `follow_up_email`, `follow_up_call`, `follow_up_sms`
- `details` (OpportunitySuggestedActionDetails, required, nullable)
- `justification` (string, required)

### ActionItem

- `action` (enum, required) — The recommended next step to progress or resolve the stalled opportunity
  - Allowed values: `mark_as_lost`, `change_status`, `follow_up`, `adjust_close_date`, `ask_someone_else_to_reach_out`, `change_communication_method`
- `justification` (string, required) — A short justification for the recommended action in the sales pipeline. Maximum 2 sentences.

### OpportunitySuggestedActionDetails

### OpportunityChangeStatusActionDetails

- `status_id` (string, required)

### OpportunityFollowUpEmailActionDetails

- `contact_id` (string, required)
- `message_draft` (string, required)
- `subject_draft` (string, required)

### OpportunityFollowUpSMSActionDetails

- `contact_id` (string, required)
- `message_draft` (string, required)

### OpportunityFollowUpCallActionDetails

- `call_plan` (string, required)
- `contact_id` (string, required)

### OpportunityAdjustCloseDateActionDetails

- `close_date` (date, required)

## Examples

**Response**

```json
{
  "data": [
    {
      "annualized_expected_value": 225000,
      "annualized_value": 300000,
      "confidence": 75,
      "contact_id": null,
      "created_by": null,
      "date_created": "2013-02-01T00:54:51.321000+00:00",
      "date_lost": null,
      "date_updated": "2013-02-01T00:54:51.321000+00:00",
      "date_won": null,
      "expected_value": 225000,
      "id": "oppo_KXyJj2PT74U1wOPvhBDO37jCC89mmrnoW0DylcDDWrL",
      "lead_id": "lead_s6vHFTK1TSRoH6otXOexWDO9jM4xyb1kELHDoU7Fdsp",
      "note": "Gob's ready to buy a $3,000 suit.",
      "note_html": "<body><p>Gob's ready to buy a $3,000 suit.</p></body>",
      "organization_id": "orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH",
      "status_id": "stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk",
      "updated_by": null,
      "user_id": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
      "value": 300000,
      "value_period": "one_time",
      "lead_name": "Bluth Company (Sample Lead)",
      "pipeline_id": "pipe_04fC628PVB0HjK2Qq5EqEf",
      "pipeline_name": "Sales",
      "status_label": "Active",
      "status_type": "active",
      "user_name": "John Doe",
      "value_currency": "USD",
      "value_formatted": "$3,000"
    },
    {
      "annualized_expected_value": 37500,
      "annualized_value": 50000,
      "confidence": 75,
      "contact_id": null,
      "created_by": null,
      "date_created": "2013-02-01T00:54:51.337000+00:00",
      "date_lost": null,
      "date_updated": "2013-02-01T00:54:51.337000+00:00",
      "date_won": null,
      "expected_value": 37500,
      "id": "oppo_8eB77gAdf8FMy6GsNHEy84f7uoeEWv55slvUjKQZpJt",
      "lead_id": "lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O",
      "note": "Bruce needs new software for the Bat Cave.",
      "note_html": "<body><p>Bruce needs new software for the Bat Cave.</p></body>",
      "organization_id": "orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH",
      "status_id": "stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk",
      "updated_by": null,
      "user_id": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
      "value": 50000,
      "value_period": "annual",
      "lead_name": "Wayne Enterprises (Sample Lead)",
      "pipeline_id": "pipe_04fC628PVB0HjK2Qq5EqEf",
      "pipeline_name": "Sales",
      "status_label": "Active",
      "status_type": "active",
      "user_name": "John Doe",
      "value_currency": "USD",
      "value_formatted": "$500"
    },
    {
      "annualized_expected_value": 30000,
      "annualized_value": 60000,
      "confidence": 50,
      "contact_id": null,
      "created_by": null,
      "date_created": "2013-02-01T00:54:51.337000+00:00",
      "date_lost": null,
      "date_updated": "2013-02-01T00:54:51.337000+00:00",
      "date_won": null,
      "expected_value": 2500,
      "id": "oppo_klajsdflf8FMy6GsNHEy84f7uoeEWv55slvUjKQZpJt",
      "lead_id": "lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O",
      "note": "Bat Cave monthly maintenance cost",
      "note_html": "<body><p>Bat Cave monthly maintenance cost</p></body>",
      "organization_id": "orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH",
      "status_id": "stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk",
      "updated_by": null,
      "user_id": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
      "value": 5000,
      "value_period": "monthly",
      "lead_name": "Wayne Enterprises (Sample Lead)",
      "pipeline_id": "pipe_04fC628PVB0HjK2Qq5EqEf",
      "pipeline_name": "Sales",
      "status_label": "Active",
      "status_type": "active",
      "user_name": "John Doe",
      "value_currency": "USD",
      "value_formatted": "$50 monthly",
      "custom.cf_j0P7kHmgFTZZnYBFtyPSZ3uQw4dpW8xKcW7Krps8atj": "https://www.example.com/contract.pdf"
    }
  ],
  "has_more": false,
  "count_by_value_period": {
    "annual": 1,
    "monthly": 1,
    "one_time": 1
  },
  "expected_value_annual": 37500,
  "expected_value_annual_formatted": "$375",
  "expected_value_annualized": 292500,
  "expected_value_annualized_formatted": "$2,925",
  "expected_value_monthly": 2500,
  "expected_value_monthly_formatted": "$25",
  "expected_value_one_time": 225000,
  "expected_value_one_time_formatted": "$2,250",
  "total_results": 3,
  "total_value_annual": 50000,
  "total_value_annual_formatted": "$500",
  "total_value_annualized": 410000,
  "total_value_annualized_formatted": "$4,100",
  "total_value_monthly": 5000,
  "total_value_monthly_formatted": "$50",
  "total_value_one_time": 300000,
  "total_value_one_time_formatted": "$3,000"
}
```

**SDK Code**

```python opportunities_list_example
import requests

url = "https://api.close.com/api/v1/opportunity/"

response = requests.get(url, auth=("<CLOSE_API_KEY>", ""))

print(response.json())
```

```javascript opportunities_list_example
const url = 'https://api.close.com/api/v1/opportunity/';
const credentials = btoa("<CLOSE_API_KEY>:");

const options = {method: 'GET', headers: {Authorization: `Basic ${credentials}`}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go opportunities_list_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.close.com/api/v1/opportunity/"

	req, _ := http.NewRequest("GET", url, nil)

	req.SetBasicAuth("<CLOSE_API_KEY>", "")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby opportunities_list_example
require 'uri'
require 'net/http'

url = URI("https://api.close.com/api/v1/opportunity/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request.basic_auth("<CLOSE_API_KEY>", "")

response = http.request(request)
puts response.read_body
```

```java opportunities_list_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.close.com/api/v1/opportunity/")
  .basicAuth("<CLOSE_API_KEY>", "")
  .asString();
```

```php opportunities_list_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.close.com/api/v1/opportunity/', [
  'headers' => [
  ],
    'auth' => ['<CLOSE_API_KEY>', ''],
]);

echo $response->getBody();
```

```csharp opportunities_list_example
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://api.close.com/api/v1/opportunity/");
client.Authenticator = new HttpBasicAuthenticator("<CLOSE_API_KEY>", "");
var request = new RestRequest(Method.GET);

IRestResponse response = client.Execute(request);
```