Create Contact

This tutorial should help you create the first Contact. 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 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

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

Returns all defined Clients

get

/entities/Clients

Query parameters

include-deletedboolean

if enabled, deleted Clients are returned as well

firstinteger int32

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

lastinteger int32

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.

beforeboolean

Cursor until which to take entities to result set.

afterboolean

Cursor after which to start taking entities to result set.

expandstring

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-bystring

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

filterobject

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-opobject

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-onlystring

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

application/json

application / json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://us-east.pipelinersales.com/api/v100/rest/spaces/<space_id>/entities/Clients'

200

500

200

{
  "success": true,
  "data": [],
  "page_info": {
    "start_cursor": "WyIwMSIsICJiMmYwODI0Ni1iYWE5LTQyY2QtYmM3Yi04YmM4MjY3M2E2NTgiXQ==",
    "end_cursor": "WyIwNSIsICJmMjZhZjZiMC00ZWE4LTQ3MDgtODU2NC0wN2JmYzI4ZGQ5ZTgiXQ==",
    "has_previous_page": true,
    "has_next_page": true
  }
}

list of Clients

{{baseUrl}}/entities/Clients?load-only=id,default_unit_id&filter[email]=[e-mail]

{
            "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]=[e-mail]

{
            "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": "[e-mail]",
            "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": "[phone]",
            "..."
        }

2. Create Contact

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

Creates new contact

post

/entities/Contacts

Query parameters

validation-levelinteger int32

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-time

Last modification time.

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

createdstring date-time

Creation time.

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

addressstring

Multi-line text input field.

Example: string

citystring

Simple text input field.

Example: string

commentsstring

Multi-line text input field.

Example: string

contact_type_idstring uuid

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

countrystring

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

Example: string

email1string

Email address.

Example: string

email2string

Email address.

Example: string

email3string

Email address.

Example: string

email4string

Email address.

Example: string

email5string

Email address.

Example: string

first_namestring

Simple text input field.

Example: string

last_namestring

Simple text input field.

Example: string

middle_namestring

Simple text input field.

Example: string

owner_idstring uuidrequired

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

phone1string

Phone number.

Example: string

phone2string

Phone number.

Example: string

phone3string

Phone number.

Example: string

phone4string

Phone number.

Example: string

phone5string

Phone number.

Example: string

picture_idstring uuid

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

positionstring

Simple text input field.

Example: string

quick_account_namestring

Simple text input field.

Example: string

state_provincestring

Simple text input field.

Example: string

titlestring

Simple text input field.

Example: string

unit_idstring uuid

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

zip_codestring

Simple text input field.

Example: string

revisioninteger int32

Revision when entity was lastly changed.

Example: 1

account_positionstring

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

Example: string

is_unsubscribedboolean

If account has any unsubscribed email.

Example: false

genderenum

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

Example: 0

Options: 0, 1, 2, 3

share_modeenum

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

Example: 0

Options: 0, 1, 2, 3

pictureobject

Relation to CloudObject, see: 'createCloudObjectInput' object for properties.

social_mediaobject

Relation to ContactSocialRelation, see: 'createContactSocialRelationInput' object for properties.

account_relationsobject[]

Relations to Accounts.

sharing_unitsobject[]

Relations to SalesUnits.

sharing_clientsobject[]

Relations to Clients.

documentsobject[]

Relations to CloudObjects.

Responses

application/json

application / json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://us-east.pipelinersales.com/api/v100/rest/spaces/<space_id>/entities/Contacts' \
  --header 'Content-Type: application / json'

201

500

201

{
  "data": {
    "formatted_name": "string",
    "is_favorite": false,
    "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",
    "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",
    "state_province": "string",
    "title": "string",
    "unit_id": "01234567-abcd-dcba-ffff-000000000000",
    "zip_code": "string",
    "revision": 1,
    "social_media": "https://example.com",
    "primary_account": "https://example.com",
    "primary_account_position": "string",
    "account_position": "string",
    "is_unsubscribed": false,
    "gender": 0,
    "share_mode": 0,
    "primary_account_account_roles": [
      "https://example.com"
    ],
    "account_relations": [
      "https://example.com"
    ],
    "sharing_units": [
      "https://example.com"
    ],
    "sharing_clients": [
      "https://example.com"
    ],
    "documents": [
      "https://example.com"
    ]
  },
  "success": true
}

Creation confirmation. Returns created 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.

List view of Contacts

Detail of the Contact with Linked Account

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