# List Opportunities

`GET /crm/opportunities`

Group: CRM › Opportunities · Operation ID: `listOpportunities`

Returns a list of opportunities, most recently created first. To filter by opportunityName, opportunityNumber or crmId, or by more than one value of a field, use POST crm/opportunities/search.

Only ids, dates and an exact currency filter this endpoint. To filter by opportunityName, opportunityNumber or crmId, or to pass more than one value of a field, use POST crm/opportunities/search. The item schema is the same here, on GET crm/opportunities/:id and on POST crm/opportunities/search.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=listOpportunities)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"v1"` | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |
| `entityId` | query | string | no | Limits results to opportunities owned by this legal entity. Omit for every entity. |
| `customerId` | query | string | no | Limits results to opportunities for this customer or prospect, matched against either. Omit for every customer. |
| `currency` | query | string | no | Limits results to opportunities in this currency. Format ISO 4217, for example 'USD'. Omit for every currency. |
| `createdFrom` | query | string | no | Limits results to opportunities created at or after this time, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Inclusive. |
| `createdTo` | query | string | no | Limits results to opportunities created at or before this time, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Inclusive. |
| `modifiedFrom` | query | string | no | Limits results to opportunities changed at or after this time, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Inclusive. |
| `modifiedTo` | query | string | no | Limits results to opportunities changed at or before this time, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Inclusive. |
| `cursor` | query | string | no | The cursor from the previous response's pagination.nextCursor. Omit on the first request. |
| `pageSize` | query | number | no | The number of opportunities per page. Defaults to 50, and a value above 200 is treated as 200, not rejected. |

## Response

`200` Success

Under `data` (listOpportunitiesOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The opportunities on this page, most recently created first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the opportunity. |
| `items[].opportunityNumber` | string | no | The system-generated opportunity number, for example 'OP-1042'. Absent while none has been assigned. |
| `items[].entityId` | string | yes | The legal entity that owns the opportunity. |
| `items[].currency` | string | yes | The currency the opportunity is denominated in, and the currency of amount. Format ISO 4217, for example 'USD'. |
| `items[].customerId` | string | no | The identifier of the customer or prospect this opportunity is for. customerPath says which node it points at. Absent when it points at neither. See id on GET accounting/customers/:id for a customer, or GET crm/prospects/:id for a prospect. |
| `items[].customerPath` | string | no | The node customerId points at. 'urn:evst:everest:fin/accounting:field/node:Customer.id' when customerId is a customer, 'urn:evst:everest:crm:field/node:Prospect.id' when it is a prospect. Absent when neither resolves. |
| `items[].endCustomerId` | string | no | The identifier of the end customer behind a partner customer. Absent unless one is on record. See id on GET accounting/customers/:id. |
| `items[].priceBookId` | string | yes | The identifier of the price book quotes on this opportunity are priced from. See id on GET accounting/price-books/:id. |
| `items[].stageId` | string | yes | The identifier of the stage the opportunity currently sits in. There is no endpoint for it. |
| `items[].opportunityName` | string | no | The free-text display name of the opportunity. Absent when none is set. |
| `items[].closeDate` | string (date) | no | The expected close date of the deal. Format YYYY-MM-DD. Absent when none is set. |
| `items[].amount` | string (decimal) | no | The expected deal amount, as a decimal in the opportunity's currency. Absent when none is set. |
| `items[].crmId` | string | no | The identifier of this opportunity in the external system it was imported from, for example a Salesforce record id. It is free text and not unique. Absent when none is set. |
| `items[].dataSource` | string | no | The system the record originated from, for example 'Everest' or 'Salesforce'. Absent when none is set. |
| `items[].lastModifiedDate` | string (date-time) | no | The date and time the opportunity record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].quotes` | array of object | yes | Every quote linked to this opportunity. An empty array when it has none. |
| `items[].quotes[].quoteId` | string | yes | The identifier of the linked quote. See id on GET crm/quotes/:id. |
| `items[].quotes[].isPrimary` | boolean | yes | Whether this is a primary quote for the opportunity. It is not guaranteed to be true for exactly one quote. |
| `pagination` | object | yes | The pagination details for this page. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it back as cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | Whether another page follows. A full page may still be the last, so branch on this. |

## Statuses

- `400` — Invalid request or business failure
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error