Create Opportunity

This tutorial should help you create the first Opportunity. Before moving forward, make sure your Authentication works and you understand the Key Concepts of the Pipeliner API and make sure you know how to use 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.

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

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

1. Prepare Data

Owner_id

Load an id of the user with the default sales unit. This user will become the owner of the newly created Opportunity.

{{baseUrl}}/entities/Clients?load-only=id,default_unit_id&filter[email]=john.doe@example.com
{
            "id": "00000000-0000-0000-0000-000000011a7d",
            "default_unit_id": "aba4a358-f3f8-4f55-b3ed-dd5cf589103b"
}

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)

Step_id

Pull Opportunity Pipelines and their steps. Store the ID of the First Step

{{baseUrl}}/entities/Pipelines?expand=steps&filter-op[name]=contains&filter[name]=Test Pipeline
 {
            "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
{
            "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

{{baseUrl}}/entities/ContactAccountRelations?filter[account_id]=0bc376a4-c579-413a-9221-e86e4a134766
{
            "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

  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 - System currency (the main currency)

    2. Multiple 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

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

When you define Foreign Currency, then the base value is calculated automatically based on Exchange rates

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

{{baseUrl}}/entities/Currencies?filter[is_base]=true
{
            "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.

{
    "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
       }
    ]
}

Possible problems

Last updated