*REST API › Objects › CRM*

# Opportunity

> CRM opportunity: which pipeline and stage it is in, for how much, with whom and with what probability.

A CRM sales opportunity: which pipeline and stage it is in, for how much, with whom and with what probability. It needs the CRM add-on: without it the answer is 402 `addon_required`. Writes use optimistic locking: send the `version` you read. The detail read, [`GET /api/v1/crm/opportunities/{opportunityId}`](https://docs.filmo.io/rest-api/endpoint-reference/crm/get-an-opportunity), adds the description, the collaborators, the linked quotes, the version and, with `includeHistory=true`, the stage history.

Schemas: `OpportunityDto`, `OpportunityDetailDto`

## Attributes

| Name | Type | Description |
| --- | --- | --- |
| `opportunityId` | string |  |
| `identifier` | string |  |
| `name` | string |  |
| `status` | string |  `open`, `won`, `lost` |
| `amount` | string |  |
| `currency` | string |  |
| `pipelineId` | string |  |
| `pipelineName` | string |  |
| `stageId` | string |  |
| `stageName` | string |  |
| `stageType` | string |  `open`, `won`, `lost` |
| `effectiveProbability` | number |  |
| `weightedAmount` | string |  |
| `daysInStage` | integer |  |
| `expectedCloseDate` | string<date-time> |  |
| `contactName` | string |  |
| `companyName` | string |  |
| `ownerName` | string |  |
| `source` | string |  `inbound_email`, `website_form`, `referral`, `cold_outreach`, `event`, `social`, `existing_customer`, `partner`, `other` |
| `createdAt` | string<date-time> |  |
| `updatedAt` | string<date-time> |  |
| `description` | string |  |
| `version` | integer |  |
| `collaboratorStaffIds` | string[] |  |
| `quoteIds` | string[] |  |
| `stageHistory` | object[] |  |
| `stageHistory.fromStageId` | string |  |
| `stageHistory.toStageId` | string |  |
| `stageHistory.toStatus` | string |  |
| `stageHistory.daysInPrevStage` | integer |  |
| `stageHistory.movedAt` | string<date-time> |  |
| `stageHistory.note` | string |  |

## Values

| Field | Values |
| --- | --- |
| `status` | `open`, `won`, `lost` |
| `stageType` | `open`, `won`, `lost` |
| `source` | `inbound_email`, `website_form`, `referral`, `cold_outreach`, `event`, `social`, `existing_customer`, `partner`, `other` |

## Example

*Opportunity · Generated from the schema*

```json
{
  "opportunityId": "string",
  "identifier": "string",
  "name": "Example",
  "status": "open",
  "amount": "1234.50",
  "currency": "EUR",
  "pipelineId": "string",
  "pipelineName": "Example",
  "stageId": "string",
  "stageName": "Example",
  "stageType": "open",
  "effectiveProbability": 1,
  "weightedAmount": "1234.50",
  "daysInStage": 1,
  "expectedCloseDate": "2026-09-01T08:00:00Z",
  "contactName": "Example",
  "companyName": "Example",
  "ownerName": "Example",
  "source": "inbound_email",
  "createdAt": "2026-09-01T08:00:00Z",
  "updatedAt": "2026-09-01T08:00:00Z",
  "description": "string",
  "version": 1,
  "collaboratorStaffIds": [
    "string"
  ],
  "quoteIds": [
    "string"
  ],
  "stageHistory": [
    {
      "fromStageId": "string",
      "toStageId": "string",
      "toStatus": "string",
      "daysInPrevStage": 1,
      "movedAt": "2026-09-01T08:00:00Z",
      "note": "string"
    }
  ]
}
```

## Returned by

- [`GET /api/v1/crm/opportunities`](https://docs.filmo.io/rest-api/endpoint-reference/crm/list-opportunities) — List opportunities
- [`GET /api/v1/crm/opportunities/{opportunityId}`](https://docs.filmo.io/rest-api/endpoint-reference/crm/get-an-opportunity) — Get an opportunity

## Modified by

- [`POST /api/v1/crm/opportunities`](https://docs.filmo.io/rest-api/endpoint-reference/crm/create-an-opportunity) — Create an opportunity
- [`PATCH /api/v1/crm/opportunities/{opportunityId}`](https://docs.filmo.io/rest-api/endpoint-reference/crm/update-an-opportunity) — Update an opportunity
- [`PATCH /api/v1/crm/opportunities/{opportunityId}/stage`](https://docs.filmo.io/rest-api/endpoint-reference/crm/move-an-opportunity-to-another-stage) — Move an opportunity to another stage
- [`POST /api/v1/crm/opportunities/{opportunityId}/close`](https://docs.filmo.io/rest-api/endpoint-reference/crm/close-an-opportunity) — Close an opportunity
- [`POST /api/v1/crm/opportunities/{opportunityId}/links`](https://docs.filmo.io/rest-api/endpoint-reference/crm/link-a-document-to-an-opportunity) — Link a document to an opportunity

---

Canonical URL: https://docs.filmo.io/rest-api/objects/opportunity  
Last updated: 2026-10-25