LogoLogo
HomeSupport centerAPP
  • Overview
    • Quick Start
    • About the API
    • Authentication
  • API Reference
    • REST API
    • GraphQL API
  • Core API Concepts
    • Understanding the CRM Concept
    • Fields
    • API parameters
    • Dates
    • Pagination
    • Bulk Create, Update, Delete
    • Webhooks(Real-time updates)
  • Tutorials & Articles
    • Create Account
    • Create Contact
    • Create Opportunity
    • Create Product, Product Line Item
    • Create Custom Entity Record
    • Upload Document
    • Merging Accounts/Contacts
Powered by GitBook
On this page
  1. Tutorials & Articles

Create Contact

PreviousCreate AccountNextCreate Opportunity

Last updated 3 years ago

This tutorial should help you create the first Contact. Before moving forward, make sure your works and you understand the of the Pipeliner API ,and make sure you know how to use

The Contact represents existing contact from the company, that your company is dealing with. Go to the web Application and Contacts can be located on the Contacts screen. Contact should not be standalone records, but they should always be linked to the Accounts.

Tutorial Assignment

Create a Contact in Pipeliner with Job Position/Job Title. This contact will be linked with one Account.

0. Required fields

Required API field Name
Description

first_name or last_name

Name of the Contact. Name of the Contact is created as "Fist_name" + "Middle_Name" + "Last_Name"

Required: at least one of the first_name, last_name

owner_id

Id of the User in Pipeliner Application

1. Prepare Data

Owner_id

{{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 contact with the default User´s sales unit. (See step 2. of this tutorial)

Account_id

We want to assign this contact with an Account. 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",
            "..."
        }

2. Create Contact

Let´s Take data from Step 1. and use them in the following request to create a Contact.

{
    "first_name": "Pipeliner",
    "last_name":"Developer",
    "position": "This is position in Quick Account Position field",
    "owner_id": "00000000-0000-0000-0000-000000011a7d",
    "account_relations": [
        {
        "account_id": "0bc376a4-c579-413a-9221-e86e4a134766",
        "position": "This is Primary Account Job Title",
        "is_primary": true
        }
    ]
}

Linking Contact to Account

To Link Contact with Account, we are going to create relation by creating new primary relation in account_relations array

Setting up the Position

position - In Pipeliner Application this api_field is called Quick Account Position. This is the Contact field. Use this field when you are not linking Contact with Account immediately.

account_position - This is Primary Account Job Title. This position is linked directly with the Account. It is recommended to use this api_field, as Contacts might have different positions on different Accounts.

Possible Errors

Error description
Resolution

Error on field account_relations. Exactly one 'is_primary' item must be set.

Use is_primary flag for Account 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

Load an id of the user with the . This user will become the owner of the newly created Contact.

Authentication
Key Concepts
API parameters
default sales unit
List view of Contacts
Detail of the Contact with Linked Account
get

Returns all defined Clients

Query parameters
include-deletedbooleanOptional

if enabled, deleted Clients are returned as well

firstinteger · int32Optional

Number of entities to return from beginning of the result set. Max: 100. Default: 30

lastinteger · int32Optional

Return only the "last" number of entities from result set. When used with first parameter, then it returns last M records from the first N records.

beforebooleanOptional

Cursor until which to take entities to result set.

afterbooleanOptional

Cursor after which to start taking entities to result set.

expandstringOptional

Expand related entity. Use api_names of relation fields. You can use multiple values separated via ',' colon. If not used, URI link will be returned instead. You can use dots '.' to expand nested entities as well.

Example: expand=owner,sales_unit,account_relations.account
order-bystringOptional

Order by values. Use api_name of field to sort by ascending. Prefix api_name with '-' to descending sort. You can use multiple values separated via ',' colon.

Example: order-by=created,-modified
filterobjectOptional

Use name of field in braces to filter by this field. To advanced filter, use with combination with filter-op parameter.

Example: filter[name]=Example
filter-opobjectOptional

Filter operator. Specify a way how to filter fields. Supported operators: [eq, ieq, not-eq, not-ieq, contains, starts, ends, icontains, istarts, iends, null, not-null, empty, not-empty, gt, gte, lt, lte, between].

Example: filter-op[name]=eq
load-onlystringOptional

Loads only fields defined within this parameter. You can use multiple values separated via ',' colon. If not used, then all fields are returned. You can use dots '.' to specify load only fields in nested as well.

Example: load-only=id,name,owner.id
Responses
200
list of Clients
application/json
500
unexpected error
application / json
get
GET /api/v100/rest/spaces/<space_id>/entities/Clients HTTP/1.1
Host: us-east.pipelinersales.com
Accept: */*
{
  "success": true,
  "data": [],
  "page_info": {
    "start_cursor": "WyIwMSIsICJiMmYwODI0Ni1iYWE5LTQyY2QtYmM3Yi04YmM4MjY3M2E2NTgiXQ==",
    "end_cursor": "WyIwNSIsICJmMjZhZjZiMC00ZWE4LTQ3MDgtODU2NC0wN2JmYzI4ZGQ5ZTgiXQ==",
    "has_previous_page": true,
    "has_next_page": true
  }
}
  • Tutorial Assignment
  • 0. Required fields
  • 1. Prepare Data
  • GET/entities/Clients
  • 2. Create Contact
  • POST/entities/Contacts
post

Creates new contact

Query parameters
validation-levelinteger · int32Optional

Specify validation level of contact on create. Use them as bit mask: 0 - validate each field on entity, 2 - validate only changed fields, 4 - validate only system fields, 8 - allows to override readonly fields, 16 - allows to set entity on deleted relationship.

Body
modifiedstring · date-timeRead-onlyOptional

Last modification time.

Example: 2019-01-01T00:00:00
createdstring · date-timeOptional

Creation time.

Example: 2019-01-01T00:00:00
addressstringOptional

Multi-line text input field.

Example: string
citystringOptional

Simple text input field.

Example: string
commentsstringOptional

Multi-line text input field.

Example: string
contact_type_idstring · uuidOptional

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000
countrystringOptional

Generic field wrapping sqlalchemy column, configurable by constructor. Good for one-of fields / generated fields.

Example: string
email1stringOptional

Email address.

Example: string
email2stringOptional

Email address.

Example: string
email3stringOptional

Email address.

Example: string
email4stringOptional

Email address.

Example: string
email5stringOptional

Email address.

Example: string
first_namestringOptional

Simple text input field.

Example: string
genderinteger · enumOptional

Integer enum value: 0 - Unknown, 1 - Male, 2 - Female, 3 - NonBinary

Example: 0Possible values:
last_namestringOptional

Simple text input field.

Example: string
middle_namestringOptional

Simple text input field.

Example: string
owner_idstring · uuidRequired

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000
phone1stringOptional

Phone number.

Example: string
phone2stringOptional

Phone number.

Example: string
phone3stringOptional

Phone number.

Example: string
phone4stringOptional

Phone number.

Example: string
phone5stringOptional

Phone number.

Example: string
picture_idstring · uuidOptional

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000
positionstringOptional

Simple text input field.

Example: string
quick_account_namestringOptional

Simple text input field.

Example: string
share_modeinteger · enumOptional

Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit

Example: 0Possible values:
state_provincestringOptional

Simple text input field.

Example: string
titlestringOptional

Simple text input field.

Example: string
unit_idstring · uuidOptional

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000
zip_codestringOptional

Simple text input field.

Example: string
revisioninteger · int32Optional

Revision when entity was lastly changed.

Example: 1
account_positionstringOptional

Job position of Contact in his primary Account or quick account position if Contact has no primary Account.

Example: string
is_unsubscribedbooleanOptional

If account has any unsubscribed email.

Example: false
Responses
201
Creation confirmation. Returns created contact
application/json
500
unexpected error
application / json
post
POST /api/v100/rest/spaces/<space_id>/entities/Contacts HTTP/1.1
Host: us-east.pipelinersales.com
Content-Type: application / json
Accept: */*
Content-Length: 1038

{
  "created": "2019-01-01T00:00:00",
  "picture": {
    "id": "https://example.com"
  },
  "address": "string",
  "city": "string",
  "comments": "string",
  "contact_type_id": "01234567-abcd-dcba-ffff-000000000000",
  "country": "string",
  "email1": "string",
  "email2": "string",
  "email3": "string",
  "email4": "string",
  "email5": "string",
  "first_name": "string",
  "gender": 0,
  "last_name": "string",
  "middle_name": "string",
  "owner_id": "01234567-abcd-dcba-ffff-000000000000",
  "phone1": "string",
  "phone2": "string",
  "phone3": "string",
  "phone4": "string",
  "phone5": "string",
  "picture_id": "01234567-abcd-dcba-ffff-000000000000",
  "position": "string",
  "quick_account_name": "string",
  "share_mode": 0,
  "state_province": "string",
  "title": "string",
  "unit_id": "01234567-abcd-dcba-ffff-000000000000",
  "zip_code": "string",
  "revision": 1,
  "social_media": {
    "id": "https://example.com"
  },
  "account_relations": [
    {
      "id": "https://example.com"
    }
  ],
  "sharing_units": [
    {
      "id": "https://example.com"
    }
  ],
  "sharing_clients": [
    {
      "id": "https://example.com"
    }
  ],
  "documents": [
    {
      "id": "https://example.com"
    }
  ],
  "account_position": "string",
  "is_unsubscribed": false
}
{
  "success": true,
  "data": {
    "is_delete_protected": false,
    "id": "01234567-abcd-dcba-ffff-000000000000",
    "is_deleted": false,
    "modified": "2019-01-01T00:00:00",
    "created": "2019-01-01T00:00:00",
    "contact_type": "https://example.com",
    "owner": "https://example.com",
    "picture": "https://example.com",
    "unit": "https://example.com",
    "address": "string",
    "city": "string",
    "comments": "string",
    "contact_type_id": "01234567-abcd-dcba-ffff-000000000000",
    "country": "string",
    "email1": "string",
    "email2": "string",
    "email3": "string",
    "email4": "string",
    "email5": "string",
    "first_name": "string",
    "gender": 0,
    "last_name": "string",
    "middle_name": "string",
    "owner_id": "01234567-abcd-dcba-ffff-000000000000",
    "phone1": "string",
    "phone2": "string",
    "phone3": "string",
    "phone4": "string",
    "phone5": "string",
    "picture_id": "01234567-abcd-dcba-ffff-000000000000",
    "position": "string",
    "quick_account_name": "string",
    "share_mode": 0,
    "state_province": "string",
    "title": "string",
    "unit_id": "01234567-abcd-dcba-ffff-000000000000",
    "zip_code": "string",
    "revision": 1,
    "formatted_name": "string",
    "social_media": "https://example.com",
    "primary_account": "https://example.com",
    "account_relations": [
      "https://example.com"
    ],
    "sharing_units": [
      "https://example.com"
    ],
    "sharing_clients": [
      "https://example.com"
    ],
    "documents": [
      "https://example.com"
    ],
    "is_favorite": false,
    "primary_account_account_roles": [
      "https://example.com"
    ],
    "primary_account_position": "string",
    "account_position": "string",
    "is_unsubscribed": false
  }
}