# Create Opportunity This tutorial should help you create the first Opportunity. Before moving forward, make sure your [**Authentication** ](https://developers.pipelinersales.com/api-docs/overview/authentication)works and you understand the [**Key Concepts**](https://developers.pipelinersales.com/api-docs/core-api-concepts/understanding-the-crm-concept) of the Pipeliner API and make sure you know how to use [**API parameters**](https://developers.pipelinersales.com/api-docs/core-api-concepts/api-parameters) **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 Pipeline and pipeline step. ![](https://3470708952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFpjbhrh1xo0SPAbAc7Ny%2Fuploads%2FQ6qmUmY2Lu0z4NrbwCpS%2FSnipping%20Tool%202021-12-20%2015.22.11.png?alt=media\&token=dd2906ec-69dd-4f1d-8889-ea7becd70f25) {% 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 Pipeliner 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 Pipeliner
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](https://developers.pipelinersales.com/api-docs/core-api-concepts/understanding-the-crm-concept#users-and-roles-and-sales-units-accessing-records). This user will become the owner of the newly created Opportunity. {% openapi src="" 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, Pipeliner 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="" 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="" 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 ![](https://3470708952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFpjbhrh1xo0SPAbAc7Ny%2Fuploads%2FsIVtisDSAbHVTIJlsAZT%2FBruen%20Canada%20_%20Pipeliner%20CRM%20-%20Google%20Chrome%202021-.png?alt=media\&token=4243a1b8-b85b-46c3-8d08-fd3850288b7c) 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="" 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="" 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](https://3470708952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFpjbhrh1xo0SPAbAc7Ny%2Fuploads%2FOQl4Bnb8bqfRatPGvoql%2Fimage.png?alt=media\&token=d7e1889f-9bfc-4074-b436-257147a5c833) **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

|