---
title: Opportunities
description: Deals in a sales pipeline, with a value, a closing date and a step. Winning is a move to the last step; losing is archiving.
canonical: https://developers.coevera.com/reference/rest/opportunities/
section: rest
verification: schema
generatedFrom: spec 5e43371 (2026-10-16)
publisher: Coevera
---

# Opportunities

Deals in a sales pipeline, with a value, a closing date and a step. Winning is a move to the last step; losing is archiving.

An opportunity sits on a step of a pipeline (`step_id`). A REST update of `step_id`, `owner_id` or `is_archived` records the same history and webhook events as the GraphQL move, change-owner and archive actions, but skips their extras, such as completing activities or the lost form's required fields.

> **What the API requires:** A create needs `account_relations`, with one relation marked `is_primary: true`, although the spec does not mark it as required. Without it the API answers HTTP 422 (docs sandbox, 2026-10-15).

> **What the API requires:** `value` is a currency object. Send `currency_id` and `base_value`: with `base_value` set, `value_foreign` is computed. Without `currency_id` the API answers HTTP 422, *Missing parameter currency_id in field value* (docs sandbox, 2026-10-15).

> **What the API requires:** `status` is 1 Open, 2 Lost or 3 Won, and read-only: an opportunity on its pipeline's last step is won, and one archived on another step is lost.

Family: Leads and opportunities. GraphQL: [opportunity](https://developers.coevera.com/reference/graphql/opportunity.md). Base URL: `https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}`.

| Method | Path | Operation |
| --- | --- | --- |
| GET | `/entities/Opportunities` | List opportunities |
| POST | `/entities/Opportunities` | Create an opportunity |
| GET | `/entities/Opportunities/{id}` | Get an opportunity |
| PATCH | `/entities/Opportunities/{id}` | Update an opportunity |
| DELETE | `/entities/Opportunities/{id}` | Delete an opportunity |
| POST | `/entities/Opportunities/batch-modify` | Create or update opportunities in a batch |
| POST | `/entities/Opportunities/batch-delete` | Delete opportunities in a batch |
| POST | `/entities/Opportunities/batch-restore` | Restore deleted opportunities |

## List opportunities

`GET /entities/Opportunities`

Returns the opportunities the API application can read, one page at a time.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `include-deleted` | query | boolean | Include soft-deleted records. Lists only; get-by-id refuses it. |
| `first` | query | integer | Page size. Default 30, maximum 100; a larger value is refused with HTTP 400, code 117. (default 30, 1 to 100) |
| `last` | query | integer | Return the last N records of the result; together with `first`, the last N of the first M. Maximum 100. (1 to 100) |
| `before` | query | string | Cursor from `page_info.start_cursor`, to page backwards. URL-encode it. |
| `after` | query | string | Cursor from `page_info.end_cursor` of the previous page. URL-encode it: cursors are base64, and a raw + becomes a space. |
| `expand` | query | string | Related records to return inline instead of their URIs, comma-separated; dots reach nested relations, as in `account_relations.account`. |
| `order-by` | query | string | Fields to sort by, comma-separated. A leading - sorts descending, as in `-modified`; dotted paths sort by related fields. |
| `filter` | query | object | `filter[field]=value`. Separate several values with a raw comma (OR), as in `filter[name]=north,south`. Encode a comma that belongs to a value as %2C. URLSearchParams and Python requests encode every comma, so build the filter part of the query string yourself. Dotted paths filter on related records, as in `filter[owner.email]`. Encode a + in a value as %2B: query values are form-decoded, so a raw + becomes a space. |
| `filter-op` | query | object | `filter-op[field]=operator`, one per field: eq (the default), ieq, not-eq, not-ieq, contains, icontains, starts, istarts, ends, iends, gt, gte, lt, lte, between, null, not-null, empty and not-empty. null, not-null, empty and not-empty take no filter value; gt, gte, lt and lte take exactly one. |
| `load-only` | query | string | Fields to return, comma-separated (raw or encoded commas both work here); dots select nested fields, as in `owner.id`. All fields are returned without it. Lists only: get-by-id refuses it with HTTP 400, code 118. |

Responses: 200 (Page of Opportunity records.: `success`, `total`, `page_info`, `data`), 400, 401, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Opportunities?first=10&filter%5Bname%5D=north&filter-op%5Bname%5D=icontains' \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
```

## Create an opportunity

`POST /entities/Opportunities`

Creates one opportunity and answers 201 with the record. `name`, `owner_id`, `step_id`, `closing_date`, `value` (with `currency_id`) and `account_relations` are required.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `validation-level` | query | integer | Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117. |

Request body: The new record's fields. Relations are set by id. Schema `createOpportunityInput`. Required: `closing_date`, `name`, `owner_id`, `step_id`, `value`, `account_relations`.

Responses: 201 (The created Opportunity record.: `success`, `data`), 400, 401, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Opportunities' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Northwind Analytics - CRM rollout",
  "owner_id": "37000000-0000-4000-a000-000000000001",
  "step_id": "d4000000-0000-4000-a000-000000000001",
  "closing_date": "2026-12-15",
  "value": {
    "base_value": 24000,
    "currency_id": "be000000-0000-4000-a000-000000000001"
  },
  "account_relations": [
    {
      "account_id": "1d000000-0000-4000-a000-000000000001",
      "is_primary": true
    }
  ]
}'
```

## Get an opportunity

`GET /entities/Opportunities/{id}`

Returns one opportunity by id.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | path | string (uuid) | Required. Id of the Opportunity record to retrieve. |
| `expand` | query | string | Related records to return inline instead of their URIs, comma-separated; dots reach nested relations. The only parameter this call accepts. |

Responses: 200 (The Opportunity record.: `success`, `data`), 400, 401, 404, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Opportunities/ca000000-0000-4000-a000-000000000001?expand=owner' \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
```

## Update an opportunity

`PATCH /entities/Opportunities/{id}`

Changes the fields you send and leaves the rest as they are. Changing `step_id`, `owner_id` or `is_archived` here skips the extras of the GraphQL move, change-owner and archive actions.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | path | string (uuid) | Required. Id of the Opportunity record to update. |
| `validation-level` | query | integer | Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117. |

Request body: The fields to change. Schema `updateOpportunityInput`.

Responses: 200 (The changed Opportunity record.: `success`, `data`), 400, 401, 404, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Opportunities/ca000000-0000-4000-a000-000000000001' \
  --request PATCH \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Northwind opportunity (renamed)"
}'
```

## Delete an opportunity

`DELETE /entities/Opportunities/{id}`

Soft-deletes one opportunity and answers with its id.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | path | string (uuid) | Required. Id of the Opportunity record to delete. |

Responses: 200 (Deletion confirmation.: `success`, `data`), 400, 401, 404, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Opportunities/ca000000-0000-4000-a000-000000000001' \
  --request DELETE \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
```

## Create or update opportunities in a batch

`POST /entities/Opportunities/batch-modify`

An item with an `id` updates that opportunity; an item without one creates an opportunity. By default one invalid item fails the whole call with HTTP 422.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `validation-level` | query | integer | Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117. |
| `rollback-method` | query | integer | 0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item. (default 0) |

Request body: A JSON array of records: an item with an `id` updates, an item without one creates. Schema `batchOpportunityInput`. Required: `closing_date`, `name`, `owner_id`, `step_id`, `value`, `account_relations`.

Responses: 200 (Result per item, in request order: the id of the created or updated record, or the error.: `success`, `data`), 400, 401, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Opportunities/batch-modify' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "closing_date": "2026-10-13",
    "name": "Northwind opportunity",
    "owner_id": "37000000-0000-4000-a000-000000000001",
    "step_id": "d4000000-0000-4000-a000-000000000001",
    "value": {
      "base_value": 1000
    },
    "account_relations": []
  },
  {
    "id": "ca000000-0000-4000-a000-000000000001",
    "name": "Northwind opportunity (renamed)"
  }
]'
```

## Delete opportunities in a batch

`POST /entities/Opportunities/batch-delete`

Soft-deletes the opportunities whose ids are in the body, a JSON array.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `rollback-method` | query | integer | 0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item. (default 0) |

Request body: A JSON array of ids.

Responses: 200 (Result per id, in request order: the id of the deleted record, or the error.: `success`, `data`), 400, 401, 404, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Opportunities/batch-delete' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '[
  "ca000000-0000-4000-a000-000000000001",
  "ca000000-0000-4000-a000-000000000002"
]'
```

## Restore deleted opportunities

`POST /entities/Opportunities/batch-restore`

Restores the soft-deleted opportunities whose ids are in the body, a JSON array.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `rollback-method` | query | integer | 0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item. (default 0) |

Request body: A JSON array of ids.

Responses: 200 (Result per id, in request order: the id of the restored record, or the error.: `success`, `data`), 400, 401, 404, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Opportunities/batch-restore' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '[
  "ca000000-0000-4000-a000-000000000001",
  "ca000000-0000-4000-a000-000000000002"
]'
```

## Opportunity fields

| Field | Type | Notes |
| --- | --- | --- |
| `id` | uuid | Read-only. Unique identifier of entity. |
| `closing_date` | date | Required on create. Expected or actual closing date of the opportunity. |
| `name` | string | Required on create. Name of the entity and its default text representation. |
| `owner_id` | uuid → Clients | Required on create. Id of the opportunity owner. |
| `step_id` | uuid → Steps | Required on create. Id of the pipeline step. |
| `value` | object | Required on create. Monetary value of the opportunity; on create, send `currency_id` and `base_value`, and `value_foreign` is computed. |
| `account_relations` | array of uri → LeadOpptyAccountRelations | Required on create. Accounts linked to this opportunity; required on create, with one relation marked `is_primary: true`, the primary account. |
| `created` | date-time | Creation time. |
| `active_quote_id` | uuid → Quotes | Id of the quote currently synchronized with this opportunity, or empty when no quote is active. |
| `currency_exchange_rates_list_id` | uuid → CurrencyExchangeRatesLists | Id of the currency exchange rate list applied to this opportunity. |
| `description` | string | Free-form description of the opportunity. |
| `is_archived` | boolean | True when the opportunity has been archived (lost). |
| `is_value_auto_calculate` | boolean | True when value is auto-calculated from the opportunity product line items. |
| `label_flag` | string | User-set colored flag used to highlight the opportunity in lists and reports. Values: 1, 2, 4. |
| `last_ai_buying_center_applied` | date-time | Time when an AI-suggested buying center was last applied to this opportunity. |
| `lead_source_id` | uuid → Data | Id of the lead source the opportunity originated from. |
| `oppty_type_id` | uuid → OpportunityTypes | Id of the opportunity type. |
| `product_currency_id` | uuid → Currencies | Id of the currency used for product line-item prices on this opportunity. |
| `product_price_list_id` | uuid → ProductPriceLists | Id of the price list that supplies prices for product line items added to this opportunity, or empty to use catalog defaults. |
| `product_sections` | object | Product sections grouping the record's line items, as a JSON array of {"id": <UUID>, "name": <string>} objects. |
| `quick_account_email` | string | Free-text company email captured at opportunity creation when no Account record has been linked yet. |
| `quick_account_name` | string | Free-text company name captured at opportunity creation when no Account record has been linked yet. |
| `quick_account_phone` | string | Free-text company phone captured at opportunity creation when no Account record has been linked yet. |
| `quick_contact_name` | string | Free-text contact name captured at opportunity creation when no Contact record has been linked yet. |
| `quick_email` | string | Free-text contact email captured at opportunity creation when no Contact record has been linked yet. |
| `quick_phone` | string | Free-text contact phone captured at opportunity creation when no Contact record has been linked yet. |
| `ranking` | integer | Qualitative ranking score (1-10) the user assigns to indicate the strength of the opportunity. |
| `reason_of_close_description` | string | Free-form note explaining why the opportunity was archived (lost). |
| `reason_of_close_id` | uuid → Data | Id of the reason of close option selected when the opportunity was archived (lost). |
| `share_mode` | integer | Sharing model applied on top of the owner/unit visibility (e.g. Values: 0 Standard, 1 Private, 2 AllView, 3 AllEdit. |
| `unit_id` | uuid → SalesUnits | Id of the sales unit. |
| `was_qualified` | boolean | True when the opportunity has gone through the qualification step at least once. |
| `revision` | integer | Revision when entity was lastly changed. |
| `oppty_recurrence` | uri → OpptyRecurrences | Recurrence schedule generating periodic copies of this opportunity, or empty when no recurrence is set up. |
| `revenue_schedule` | uri → OpptyRevenueSchedules | Revenue schedule splitting the opportunity value across periods, or empty when revenue scheduling is not enabled for this opportunity. |
| `product_relations` | array of uri → OpptyProductRelations | Product line items on this opportunity. |
| `contact_relations` | array of uri → LeadOpptyContactRelations | Contacts linked to this opportunity, including their roles and org-chart positions. |
| `documents` | array of uri → CloudObjectRelations | Documents linked to this opportunity. |
| `quote_relations` | array of uri → Quotes | Quotes prepared for this opportunity. |
| `won_date` | date-time | Timestamp of when the opportunity was won. |
| `lost_date` | date-time | Timestamp of when the opportunity was archived (lost). |
| `sharing_units` | array of uri → LeadOpptySharingSalesUnitRelations | Sales units that have been granted shared access to this opportunity. |
| `sharing_clients` | array of uri → LeadOpptySharingClientRelations | Users that have been granted shared access to this opportunity. |
| `tags` | array of uri → TagRelations | Tag labels applied to this opportunity. |
| `static_profiles` | array of uri → ProfileRelations | Saved view profiles this opportunity currently matches. |
| `is_delete_protected` | boolean | Read-only. True when the record is protected against deletion because it must always exist in the space. |
| `is_deleted` | boolean | Read-only. Specifies if the entity is considered deleted. |
| `modified` | date-time | Read-only. Last modification time. |
| `active_quote` | uri → Quotes | Read-only. Quote currently used to drive the opportunity (e.g. |
| `currency_exchange_rates_list` | uri → CurrencyExchangeRatesLists | Read-only. Currency exchange rate list used to convert monetary fields linked to this opportunity. |
| `lead_source` | uri → Data | Read-only. How the opportunity originated (e.g. |
| `oppty_type` | uri → OpportunityTypes | Read-only. Opportunity type that classifies this opportunity. |
| `owner` | uri → Clients | Read-only. Sales user who owns this opportunity. |
| `product_currency` | uri → Currencies | Read-only. Currency used for product line-item prices on this opportunity. |
| `product_price_list` | uri → ProductPriceLists | Read-only. Product price list used to populate prices for product line items added to this opportunity. |
| `reason_of_close` | uri → Data | Read-only. Configurable reason recorded when the opportunity is archived (lost). |
| `step` | uri → Steps | Read-only. Pipeline step the opportunity is currently sitting in. |
| `unit` | uri → SalesUnits | Read-only. Sales unit this opportunity is assigned to. |
| `table_name` | string | Read-only. Discriminator identifying the concrete record type — always "opportunity" for Opportunity records. |
| `primary_contact` | uri → Contacts | Read-only. Primary contact of this opportunity. |
| `primary_account` | uri → Accounts | Read-only. Primary account of this opportunity. |
| `status` | integer | Read-only. Status of the opportunity: 1 Open, 2 Lost, 3 Won. Values: 1 Open, 2 Lost, 3 Won. |
| `qualify_date` | date-time | Read-only. Timestamp of when the opportunity was qualified, taken from the matching KPI event. |
| `days_in_step` | integer | Read-only. Number of days the opportunity has been sitting in its current pipeline step. |
| `is_favorite` | boolean | Read-only. True when the current authenticated user has marked this opportunity as favorite. |
| `formatted_name` | string | Read-only. Display version of the opportunity name, used in lists and references. |
| `modified_by_user` | date-time | Read-only. Timestamp of the most recent modification made by an end user (excluding system changes). |

Custom fields appear in your space's live spec: `GET /api/v100/rest/spaces/{space_id}/openapi.json` with your credentials.

## Errors

Every error body has `success: false`, `http_status`, `code`, `name` and `message`. Branch on `code`: the status alone does not tell a missing permission from a bad parameter.

| HTTP | When |
| --- | --- |
| 400 | Bad request: a bad or unknown parameter (codes 117, 118), a missing permission (code 50), conflicting data (code 2002) or any other API error. The REST API answers 400 where others answer 403 or 409; check `code`. |
| 401 | Not authenticated: missing or wrong credentials, a credential of another space, or an expired token (code 401, ERROR_UNAUTHORIZED). |
| 404 | No such record or entity (code 143 ERROR_NO_ENTITY, or 2006 ERROR_UNKNOWN_TYPE). |
| 422 | Validation failed (code 40000, with the failing fields) or a required parameter is missing (code 119). By default one failed item fails a whole batch and nothing is written. |
| 429 | Too many requests (code 182). Wait for the seconds in Retry-After, then retry. |
| 500 | Unexpected server error (code 1000, ERROR_UNKNOWN). |

All error codes: https://developers.coevera.com/reference/errors.md; how to handle them: https://developers.coevera.com/concepts/errors.md

## Webhook events for opportunities

`Opportunity.Create`, `Opportunity.Delete`, `Opportunity.DocumentLinked`, `Opportunity.Lost`, `Opportunity.Move`, `Opportunity.OwnerChanged`, `Opportunity.Qualify`, `Opportunity.Update`, `Opportunity.Won`. Payloads: https://developers.coevera.com/webhooks/events.md

Subscribe with [Create a webhook](https://developers.coevera.com/reference/rest/webhooks.md).