--- title: "Create or update opportunities in a batch" method: POST path: "/entities/Opportunities/batch-modify" tags: ["Lead & Opportunity"] --- # Create or update opportunities in a batch `POST /entities/Opportunities/batch-modify` ## Request - Base URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id` - URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id/entities/Opportunities/batch-modify` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Query parameters - `validation-level` integer - `rollback-method` 0 | 1 ## Request body - BatchOpportunityInput[] - `created` string, date-time: Creation time. - `active_quote_id` string, uuid: Id of the quote currently synchronized with this opportunity, or empty when no quote is active. A quote can be active on only one opportunity at a time. - `closing_date` string, date: Expected or actual closing date of the opportunity. - `currency_exchange_rates_list_id` string, uuid: 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). Archived opportunities remain readable but are hidden from active lists and cannot be edited until reactivated. - `is_value_auto_calculate` boolean: True when value is auto-calculated from the opportunity product line items. False when the user enters value directly. - `label_flag` string: User-set colored flag used to highlight the opportunity in lists and reports. - `last_ai_buying_center_applied` string, date-time: Time when an AI-suggested buying center was last applied to this opportunity. - `lead_source_id` string, uuid: Id of the lead source the opportunity originated from. - `name` string: Name of the entity and its default text representation. - `oppty_type_id` string, uuid: Id of the opportunity type. - `owner_id` string, uuid: Id of the opportunity owner. - `product_currency_id` string, uuid: Id of the currency used for product line-item prices on this opportunity. - `product_price_list_id` string, uuid: 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": , "name": } objects. Validated on write. Full structure: https://developers.coevera.com/reference/graphql/types/p/#ProductSection This payload conforms to the `ProductSection` JSON Schema (see the linked schema). - `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` string, uuid: Id of the reason of close option selected when the opportunity was archived (lost). - `share_mode` 0 | 1 | 2 | 3: Sharing model applied on top of the owner/unit visibility (e.g. shared with selected sales units or selected users). The matching sharing_units / sharing_clients lists control who is granted access. Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit - `step_id` string, uuid: Id of the pipeline step. - `unit_id` string, uuid: 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. - `value` object: Monetary value of the opportunity in the team space base currency, with the foreign value and currency code preserved alongside. - `base_value` number, double, required: Value in the base currency of the space. If empty, it is calculated from value_foreign at the current exchange rate. - `currency_id` string, uuid, required: Id of the currency of value_foreign. - `value_foreign` number, double, required: Value in the currency set by currency_id. If empty, it is calculated from base_value at the current exchange rate. - `oppty_recurrence` object: Recurrence schedule generating periodic copies of this opportunity, or empty when no recurrence is set up. Related OpptyRecurrence record; see 'updateOpptyRecurrenceInput' for its fields. - `id` string, uuid: Id of the related OpptyRecurrence record. - `revenue_schedule` object: Revenue schedule splitting the opportunity value across periods, or empty when revenue scheduling is not enabled for this opportunity. Related OpptyRevenueSchedule record; see 'updateOpptyRevenueScheduleInput' for its fields. - `id` string, uuid: Id of the related OpptyRevenueSchedule record. - `product_relations` object[]: Product line items on this opportunity. Each entry holds the product, quantity, price and discount that contribute to the opportunity value when is_value_auto_calculate is true. - `id` string, uuid: Id of the related OpptyProductRelation record. - `contact_relations` object[]: Contacts linked to this opportunity, including their roles and org-chart positions. - `id` string, uuid: Id of the related LeadOpptyContactRelation record. - `account_relations` object[]: Accounts linked to this opportunity, including the primary-account flag. - `id` string, uuid: Id of the related LeadOpptyAccountRelation record. - `documents` object[]: Documents linked to this opportunity. - `id` string, uuid: Id of the related CloudObjectRelation record. - `quote_relations` object[]: Quotes prepared for this opportunity. - `id` string, uuid: Id of the related Quote record. - `won_date` string, date-time: Timestamp of when the opportunity was won. Setting it adjusts the underlying win event; empty for opportunities that have not been won. - `lost_date` string, date-time: Timestamp of when the opportunity was archived (lost). Setting it adjusts the underlying loss event; empty for opportunities that have not been archived. - `sharing_units` object[]: Sales units that have been granted shared access to this opportunity. Editable only when share_mode allows unit sharing. - `id` string, uuid: Id of the related LeadOpptySharingSalesUnitRelation record. - `sharing_clients` object[]: Users that have been granted shared access to this opportunity. Editable only when share_mode allows user sharing. - `id` string, uuid: Id of the related LeadOpptySharingClientRelation record. - `tags` object[]: Tag labels applied to this opportunity. - `id` string, uuid: Id of the related TagRelation record. - `static_profiles` object[]: Saved view profiles this opportunity currently matches. - `id` string, uuid: Id of the related ProfileRelation record. - `id` string, uuid: ID of object to update. ## Response `200` Result per item, in request order: the id of the created or updated record, or the error. - object - `success` boolean: True when the request succeeded; false on error. - `data` union[] - union - string, uuid: Id of the created or updated record. - Error: The body of every REST error. `code` and `name` are stable identifiers; `message` is for people. The full list of codes is at https://developers.coevera.com/reference/errors/. - `http_status` integer, required: HTTP status code. - `code` integer: Numeric code of the API error. - `name` string: Name of the API error. - `message` string: Message describing the error. - `success` boolean, required: Always false on error. ## Other responses - `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). - `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). --- [API](https://skmtc.dev/coevera/apis/coevera-crm-api.md) - [All operations](https://skmtc.dev/coevera/apis/coevera-crm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coevera/apis/coevera-crm-api/revisions/40ebbc83f179?raw)