# Create Opportunity This tutorial should help you create the first Opportunity. Before moving forward, make sure your [**Authentication** ](/api-docs/overview/authentication.md)works and you understand the [**Key Concepts**](/api-docs/core-api-concepts/understanding-the-crm-concept.md) of the Coevera API and make sure you know how to use [**API parameters**](/api-docs/core-api-concepts/api-parameters.md) **The Opportunity** represents existing potential business for a company. Go to the web Application and Opportunities can be located on the Opportunities screen. Opportunity is always part of the Coevera and pipeline step. ![](/files/XlHV07FRX5Fq7dIXvGwC) {% hint style="info" %} **The Pipeline** is the list of steps (eg. First Contact, Proposal, Closed/Won), that represents the life cycle of the opportunity. Set up your first [**Pipeline**](https://help.pipelinersales.com/en/articles/2724115-managing-your-first-pipeline) {% endhint %} ## Tutorial Assignment Create Opportunity in the Pipeline within the First Step of the Pipeline. This Opportunity will be Linked with an Account(Company) and multiple Contact that belongs to this Account. ### 0. Required fields
Required API field NameDescription
nameName of the opportunity
owner_idId of the User in Coevera Application
closing_dateExpected Closing date. When the opportunity should be closed
step_idID of the Pipeline step where the Opportunity should be created
valueThe business value of Opportunity, eg. dollar amount.
base_value - The Real Business Value in dollars
currency_id - The ID of currency saved in Coevera
value_foreign - The value for currency_id (Use only with multicurrency setup)
### 1. Prepare Data #### Owner\_id Load an id of the user with the [default sales unit](/api-docs/core-api-concepts/understanding-the-crm-concept.md#users-and-roles-and-sales-units-accessing-records). This user will become the owner of the newly created Opportunity. {% openapi src="/files/483oBiKgEGR3bPMLT8VK" path="/entities/Clients" method="get" %} [openapi (1).json](https://3470708952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFpjbhrh1xo0SPAbAc7Ny%2Fuploads%2FOlNVdYj1h5GSxQmLHAjz%2Fopenapi%20\(1\).json?alt=media\&token=4be07353-5170-4a95-9100-4f16545d47b0) {% endopenapi %} ``` {{baseUrl}}/entities/Clients?load-only=id,default_unit_id&filter[email]=john.doe@example.com ``` ```json { "id": "00000000-0000-0000-0000-000000011a7d", "default_unit_id": "aba4a358-f3f8-4f55-b3ed-dd5cf589103b" } ``` {% hint style="info" %} We don´t necessarily need to load the default unit id. If only owner\_id is specified in the final request, Coevera will automatically create the opportunity with the default User´s sales unit. (See step 2. of this tutorial) {% endhint %} #### Step\_id Pull Opportunity Pipelines and their steps. Store the ID of the First Step {% openapi src="/files/483oBiKgEGR3bPMLT8VK" path="/entities/Pipelines" method="get" %} [openapi (1).json](https://3470708952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFpjbhrh1xo0SPAbAc7Ny%2Fuploads%2FOlNVdYj1h5GSxQmLHAjz%2Fopenapi%20\(1\).json?alt=media\&token=4be07353-5170-4a95-9100-4f16545d47b0) {% endopenapi %} ``` {{baseUrl}}/entities/Pipelines?expand=steps&filter-op[name]=contains&filter[name]=Test Pipeline ``` ```json { "is_delete_protected": false, "id": "90be8a83-bae8-401d-9e5e-c4564a986270", "is_deleted": false, "modified": "2020-09-25 10:48:29.825069+00:00", "created": "2020-08-12 15:00:21.732550+00:00", "color": 16233984, "name": "Test Pipeline", "revision": 66001, "steps": [ { "is_delete_protected": false, "id": "de115511-5dc1-46c3-86d9-f714457208dd", "is_deleted": false, "modified": "2020-08-12 15:00:21.734413+00:00", "created": "2020-08-12 15:00:21.734454+00:00", "pipeline": "https://us-east.pipelinersales.com/api/v100/rest/spaces/nv3_PipelinerDev/entities/Pipelines/90be8a83-bae8-401d-9e5e-c4564a986270", "name": "First", "percent": 15, "pipeline_id": "90be8a83-bae8-401d-9e5e-c4564a986270", "sort_order": 0, "timeframe": null, "revision": 65654, "documents": [], "step_checklists": [] } } ``` #### Account\_id We are going to search for Accounts by email address. But you can use whatever parameter. ``` {{baseUrl}}/entities/Accounts?include-deleted=false&filter[email1]=info@ziemann-and-sons.de ``` ```json { "is_delete_protected": false, "id": "0bc376a4-c579-413a-9221-e86e4a134766", "is_deleted": false, "modified": "2019-02-01 10:01:23.011709+00:00", "created": "2019-01-30 11:44:23.586083+00:00", "account_type": "https://us-east.pipelinersales.com/api/v100/rest/spaces/nv3_PipelinerDev/entities/AccountTypes/a456236f-6f23-0908-abfd-384aa0f62f9e", "customer_type": "https://us-east.pipelinersales.com/api/v100/rest/spaces/nv3_PipelinerDev/entities/Data/04444b3a-c669-03bc-2c49-bcd7f047d41a", "industry": "https://us-east.pipelinersales.com/api/v100/rest/spaces/nv3_PipelinerDev/entities/Data/acbda72f-2054-0b71-9d42-cb35aaa37600", "owner": "https://us-east.pipelinersales.com/api/v100/rest/spaces/nv3_PipelinerDev/entities/Clients/00000000-0000-0000-0000-000000011a3d", "parent_account": null, "parent_account_relation_type": null, "picture": "https://us-east.pipelinersales.com/api/v100/rest/spaces/nv3_PipelinerDev/entities/CloudObjects/5ddfe953-a569-48e1-86bb-271e6506e7d0", "unit": "https://us-east.pipelinersales.com/api/v100/rest/spaces/nv3_PipelinerDev/entities/SalesUnits/ea33e8fb-9a56-4802-a175-2d1f406af7cf", "account_class": 5, "account_type_id": "a456236f-6f23-0908-abfd-384aa0f62f9e", "address": "7 Lillian Plaza", "city": "Coronda", "comments": "", "country": "Argentina", "customer_type_id": "04444b3a-c669-03bc-2c49-bcd7f047d41a", "email1": "info@ziemann-and-sons.de", "email2": "", "email3": "", "email4": "", "email5": "", "health_category": null, "health_status": null, "home_page": "www.ziemannandsons.com", "industry_id": "acbda72f-2054-0b71-9d42-cb35aaa37600", "name": "Ziemann and Sons", "owner_id": "00000000-0000-0000-0000-000000011a3d", "parent_account_id": null, "parent_account_relation_type_id": null, "phone1": "+1 (888) 500-8000", "..." } ``` #### Contact\_id We are going to search for Contacts that are linked to the Account. We are going to use `Account_id` from the previous Step *and list all* `contact_id` *that exists on the Account* {% openapi src="/files/483oBiKgEGR3bPMLT8VK" path="/entities/ContactAccountRelations" method="get" %} [openapi (1).json](https://3470708952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFpjbhrh1xo0SPAbAc7Ny%2Fuploads%2FOlNVdYj1h5GSxQmLHAjz%2Fopenapi%20\(1\).json?alt=media\&token=4be07353-5170-4a95-9100-4f16545d47b0) {% endopenapi %} ``` {{baseUrl}}/entities/ContactAccountRelations?filter[account_id]=0bc376a4-c579-413a-9221-e86e4a134766 ``` ```json { "is_delete_protected": false, "id": "7bb50668-badb-4c4b-a184-2f2be3df4fd8", "is_deleted": false, "modified": "2019-01-30 11:54:15.289916+00:00", "created": "2019-01-30 11:54:15.289965+00:00", "account": "https://us-east.pipelinersales.com/api/v100/rest/spaces/nv3_PipelinerDev/entities/Accounts/0bc376a4-c579-413a-9221-e86e4a134766", "contact": "https://us-east.pipelinersales.com/api/v100/rest/spaces/nv3_PipelinerDev/entities/Contacts/02bdc9f6-4dfb-479e-84ba-f6c3b96c39ba", "account_id": "0bc376a4-c579-413a-9221-e86e4a134766", "comment": "", "contact_id": "02bdc9f6-4dfb-479e-84ba-f6c3b96c39ba", "is_assistant": false, "is_primary": true, "is_sibling": false, "position": "", "relationship": 0, "revision": 184, "account_roles": [] } ``` #### Value ![](/files/gi6FDG6ALfyenXbpXyX1) 1. **Foreign value (required/optional)** - This is the value that the User (SalesPerson) can put into the system. This value is depending on currency\_id. 1. Example: if your salespeople want to have an Opportunity Value in Euro, for currency\_id use Euro, into the Foreign value put the amount in Euro 2. **currency\_id** **(Required)** - the currency for the opportunity (like dollar, euro, etc.). In Pipeliner there are two types of currencies 1. [Base currency](https://help.pipelinersales.com/en/articles/2710228-base-currency) - System currency (the main currency) 2. [Multiple currencies](https://help.pipelinersales.com/en/articles/2713635-currencies) (custom currencies) - When your business works with multiple currencies 3. **base\_value (required/optional)** - this value is always calculated according to the Base Currency {% hint style="info" %} You can use one of the foreign values, base\_value. It depends on what fits you better. \ When you define base value, then Foreign Currency is calculated automatically based on [Exchange rates](https://help.pipelinersales.com/en/articles/2713643-exchange-rates) When you define Foreign Currency, then the base value is calculated automatically based on Exchange rates {% endhint %} #### Value.currency\_id In this tutorial, we don´t use a multi-currency setup, so we are going to search for the base currency (system currency). To retrieve base currency let´s use the following request. Base currency is flagged as `is_base:true` {% openapi src="/files/483oBiKgEGR3bPMLT8VK" path="/entities/Currencies" method="get" %} [openapi (1).json](https://3470708952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFpjbhrh1xo0SPAbAc7Ny%2Fuploads%2FOlNVdYj1h5GSxQmLHAjz%2Fopenapi%20\(1\).json?alt=media\&token=4be07353-5170-4a95-9100-4f16545d47b0) {% endopenapi %} ``` {{baseUrl}}/entities/Currencies?filter[is_base]=true ``` ```json { "is_delete_protected": true, "id": "c4ca4238-a0b9-0382-0dcc-509a6f75849b", "is_deleted": false, "modified": "2019-01-30 11:20:40.481012+00:00", "created": "2019-01-11 13:47:33.247720+00:00", "code": "USD", "is_base": true, "symbol": "$", "revision": 18, "currency_exchange_rates": [] } ``` ### 2. Create Opportunity Let´s Take data from Step 1. and use them in the following request to create an Opportunity. {% openapi src="/files/483oBiKgEGR3bPMLT8VK" path="/entities/Opportunities" method="post" %} [openapi (1).json](https://3470708952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFpjbhrh1xo0SPAbAc7Ny%2Fuploads%2FOlNVdYj1h5GSxQmLHAjz%2Fopenapi%20\(1\).json?alt=media\&token=4be07353-5170-4a95-9100-4f16545d47b0) {% endopenapi %} ```json { "closing_date": "2019-01-01", "name": "New Opportunity", "owner_id": "00000000-0000-0000-0000-000000011a7d", "step_id": "de115511-5dc1-46c3-86d9-f714457208dd", "value": { "base_value": 100, "currency_id": "c4ca4238-a0b9-0382-0dcc-509a6f75849b" }, "account_relations": [ { "account_id": "0bc376a4-c579-413a-9221-e86e4a134766", "is_primary": true } ], "contact_relations": [ { "contact_id": "02bdc9f6-4dfb-479e-84ba-f6c3b96c39ba", "is_primary":true } ] } ``` ![Opportunity inside the Pipeliner Application](/files/wFQGluIwe0DO500BKtPL) **Possible problems** | Error description | Resolution | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error on field account\_relations. Exactly one 'is\_primary' item must be set. |

Use is\_primary flag for Account/Contact relation object.

-When creating account relations at least one Account needs to be primary
-When creating contact relations at least one Contact needs to be primary

| --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.pipelinersales.com/api-docs/tutorials-and-articles/create-opportunity.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.