Create Custom Entity Record

This tutorial should help you create the first Custom Entity record. 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 Custom Entity allows user to work with a completely new type of entity in Pipeliner. You can create Custom Entity records and link them with other entities using Lookup fields.

Tutorial Assignment

Create Custom Entity record with the particular Entity Type
Link Custom Entity record to Opportunity using Lookup field
Filter existing Custom entity record by custom field

0. Required fields

Required API field Name

Description

name

Name of the custom entity record

owner_id

Id of the User in Pipeliner Application

type_id

Id of the related Custom Entity Expected Closing date.

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 Custom Entity Record.

Returns all defined Clients

GEThttps://us-east.pipelinersales.com/api/v100/rest/spaces/<space_id>/entities/Clients

Query parameters

Response

list of Clients

Body

successboolean

True when response succeeded, false on error.

Example: true

dataarray of Client (object)

page_infoobject

Page info result set. Please note it is returned only when legacy limit & offset parameters are not used.

Request

Response

{{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)

Type_id

Pull Custom Entity Types. Store the ID of the Custom Entity Type

Returns CustomEntity Types

GEThttps://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}Type

Path parameters

custom_entity_api_name*string

Custom entity api name

Response

CustomEntityType data

Body

successboolean

True when response succeeded, false on error.

Example: true

dataCustomEntity (object)

Request

const response = await fetch('https://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}Type', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "success": true,
  "data": {
    "is_delete_protected": false,
    "id": "01234567-abcd-dcba-ffff-000000000000",
    "modified": "2019-01-01T00:00:00",
    "created": "2019-01-01T00:00:00",
    "owner": "https://example.com",
    "type": "https://example.com",
    "unit": "https://example.com",
    "name": "string",
    "owner_id": "01234567-abcd-dcba-ffff-000000000000",
    "share_mode": 0,
    "table_name": "string",
    "type_id": "01234567-abcd-dcba-ffff-000000000000",
    "unit_id": "01234567-abcd-dcba-ffff-000000000000",
    "is_deleted": false,
    "sharing_units": [
      "https://example.com"
    ],
    "sharing_clients": [
      "https://example.com"
    ],
    "documents": [
      "https://example.com"
    ],
    "is_favorite": false,
    "revision": 1
  }
}

{{baseUrl}}/entities/MyCustomEntityType

 
{
	"is_delete_protected": true,
	"has_draft": false,
	"id": "00000000-0000-0000-0000-000000000002",
	"is_deleted": false,
	"modified": "2023-09-20 07:08:32.528011+00:00",
	"created": "2023-09-11 08:38:36.498033+00:00",
	"form_edit": {
	},
	"form_edit_api": {
	},
	"is_readonly": false,
	"name": "Custom entity 1",
	"is_published": true,
	"revision": 4288,
	"entity_api_name": "MyCustomEntity"
},
{
	"is_delete_protected": false,
	"has_draft": false,
	"id": "018ad56d-879c-b0dd-3c3a-75c59ab97a23",
	"is_deleted": false,
	"modified": "2023-09-27 06:57:23.126262+00:00",
	"created": "2023-09-27 06:57:19.772625+00:00",
	"form_edit": "",
	"form_edit_api": {
	},
	"is_readonly": false,
	"name": "Custom entity 2",
	"is_published": true,
	"revision": 4461,
	"entity_api_name": "MyCustomEntity"
}

2. Create Custom Entity record

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

CustomEntities.create

Creates new CustomEntity

POSThttps://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}

Path parameters

custom_entity_api_name*string

Custom entity api name

Query parameters

Body

data of new CustomEntity

modifiedstring (date-time)

Last modification time.

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

createdstring (date-time)

Creation time.

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

namestring

Name of the entity and its default text representation.

Example: "string"

owner_id*string (uuid)

Relation to single entity instance.

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

share_modeenum

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

Example: 0

0123

type_id*string (uuid)

Relation to single entity instance.

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

unit_idstring (uuid)

Relation to single entity instance.

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

sharing_unitsarray of object

Relations to SalesUnits.

sharing_clientsarray of object

Relations to Clients.

documentsarray of object

Relations to CloudObjects.

revisioninteger (int32)

Revision when entity was lastly changed.

Example: 1

Response

Creation confirmation. Returns created CustomEntity

Body

successboolean

True when response succeeded, false on error.

Example: true

dataCustomEntity (object)

Request

const response = await fetch('https://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}', {
    method: 'POST',
    headers: {
      "Content-Type": "application / json"
    },
    body: JSON.stringify({
      "owner_id": "01234567-abcd-dcba-ffff-000000000000",
      "type_id": "01234567-abcd-dcba-ffff-000000000000"
    }),
});
const data = await response.json();

Response

{
  "success": true,
  "data": {
    "is_delete_protected": false,
    "id": "01234567-abcd-dcba-ffff-000000000000",
    "modified": "2019-01-01T00:00:00",
    "created": "2019-01-01T00:00:00",
    "owner": "https://example.com",
    "type": "https://example.com",
    "unit": "https://example.com",
    "name": "string",
    "owner_id": "01234567-abcd-dcba-ffff-000000000000",
    "share_mode": 0,
    "table_name": "string",
    "type_id": "01234567-abcd-dcba-ffff-000000000000",
    "unit_id": "01234567-abcd-dcba-ffff-000000000000",
    "is_deleted": false,
    "sharing_units": [
      "https://example.com"
    ],
    "sharing_clients": [
      "https://example.com"
    ],
    "documents": [
      "https://example.com"
    ],
    "is_favorite": false,
    "revision": 1
  }
}

{
	"name": "Custom Entity Record 3",
	"owner_id": "00000000-0000-0000-0000-000000011a7d",
	"type_id": "018ad56d-879c-b0dd-3c3a-75c59ab97a23"
}

Success response

{
	"success": true,
	"data": {
		"is_delete_protected": false,
		"id": "018ad5a4-2ea8-75f0-e8cc-c6e54688b165",
		"modified": "2023-09-27 07:57:01.480723+00:00",
		"created": "2023-09-27 07:57:01.480781+00:00",
		"owner": "http://example.com",
		"type": "http://example.com",
		"unit": "http://example.com",
		"name": "Custom Entity Record 3",
		"owner_id": "00000000-0000-0000-0000-000000011a7d",
		"share_mode": 0,
		"table_name": "ce_custom_entity1n",
		"type_id": "018ad56d-879c-b0dd-3c3a-75c59ab97a23",
		"unit_id": "7d9467e0-d885-4729-877e-5c9e1e057b4a",
		"is_deleted": false,
		"sharing_units": [],
		"sharing_clients": [],
		"documents": [],
		"is_favorite": false,
		"revision": 4464,
		"cf_high_priority": true,
		"cf_lookup_ce_mycustomentity_leadoppty": []
	}
}

3. Link Custom Entity record to existing record using Lookup field

Take data from Step 2. and use them in the following request, to link existing record to Opportunity using a Lookup field.

Get Opportunity_id

We are going to search for Opportunity by name. But you can use whatever parameter.

Opportunities.list

Returns all defined Opportunities

GEThttps://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/Opportunities

Query parameters

Response

list of Opportunities

Body

successboolean

True when response succeeded, false on error.

Example: true

dataarray of Opportunity (object)

page_infoobject

Page info result set. Please note it is returned only when legacy limit & offset parameters are not used.

Request

const response = await fetch('https://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/Opportunities', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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",
      "active_quote": "https://example.com",
      "oppty_type": "https://example.com",
      "owner": "https://example.com",
      "product_currency": "https://example.com",
      "product_price_list": "https://example.com",
      "reason_of_close": "https://example.com",
      "step": "https://example.com",
      "unit": "https://example.com",
      "active_quote_id": "01234567-abcd-dcba-ffff-000000000000",
      "closing_date": "2019-01-01",
      "description": "string",
      "is_archived": false,
      "is_value_auto_calculate": false,
      "label_flag": 1,
      "name": "string",
      "oppty_type_id": "01234567-abcd-dcba-ffff-000000000000",
      "owner_id": "01234567-abcd-dcba-ffff-000000000000",
      "product_currency_id": "01234567-abcd-dcba-ffff-000000000000",
      "product_price_list_id": "01234567-abcd-dcba-ffff-000000000000",
      "quick_account_email": "string",
      "quick_account_name": "string",
      "quick_account_phone": "string",
      "quick_contact_name": "string",
      "quick_email": "string",
      "quick_phone": "string",
      "ranking": 1,
      "reason_of_close_description": "string",
      "reason_of_close_id": "01234567-abcd-dcba-ffff-000000000000",
      "share_mode": 0,
      "step_id": "01234567-abcd-dcba-ffff-000000000000",
      "table_name": "string",
      "unit_id": "01234567-abcd-dcba-ffff-000000000000",
      "was_qualified": false,
      "revision": 1,
      "value": {
        "base_value": "4.32",
        "currency_id": "01234567-abcd-dcba-ffff-000000000000",
        "value_foreign": "4.32"
      },
      "oppty_recurrence": "https://example.com",
      "revenue_schedule": "https://example.com",
      "product_relations": [
        "https://example.com"
      ],
      "primary_contact": "https://example.com",
      "primary_account": "https://example.com",
      "contact_relations": [
        "https://example.com"
      ],
      "account_relations": [
        "https://example.com"
      ],
      "documents": [
        "https://example.com"
      ],
      "quote_relations": [
        "https://example.com"
      ],
      "status": 1,
      "qualify_date": "2019-01-01T00:00:00",
      "won_date": "2019-01-01T00:00:00",
      "lost_date": "2019-01-01T00:00:00",
      "days_in_step": 1,
      "is_favorite": false,
      "sharing_units": [
        "https://example.com"
      ],
      "sharing_clients": [
        "https://example.com"
      ],
      "tags": [
        "https://example.com"
      ],
      "formatted_name": "string",
      "modified_by_user": "2019-01-01T00:00:00"
    }
  ],
  "page_info": {
    "start_cursor": "WyIwMSIsICJiMmYwODI0Ni1iYWE5LTQyY2QtYmM3Yi04YmM4MjY3M2E2NTgiXQ==",
    "end_cursor": "WyIwNSIsICJmMjZhZjZiMC00ZWE4LTQ3MDgtODU2NC0wN2JmYzI4ZGQ5ZTgiXQ==",
    "has_previous_page": true,
    "has_next_page": true
  }
}

{{baseUrl}}/entities/Opportunities?filter-op[name]=contains&filter[name]=Accounting

{
        "is_delete_protected": false,
        "id": "0188d953-0aa6-1094-f764-1ce141993b26",
        "is_deleted": false,
        "modified": "2023-06-20 15:01:18.162394+00:00",
        "created": "2023-06-20 15:01:18.118462+00:00",
        "active_quote": null,
        "oppty_type": "http://example.com",
        "owner": "http://example.com",
        "product_currency": "http://example.com",
        "product_price_list": null,
        "reason_of_close": null,
        "step": "http://example.com",
        "unit": "http://example.com",
        "active_quote_id": null,
        "closing_date": "2023-06-21",
        "description": "",
        "is_archived": false,
        "is_value_auto_calculate": false,
        "label_flag": 0,
        "name": "Double Entry Accounting Services",
        "oppty_type_id": "0c03f112-4544-06a8-b162-1f14524c149c",
        "owner_id": "00000000-0000-0000-0000-000000011a7d",
        "product_currency_id": "c4ca4238-a0b9-0382-0dcc-509a6f75849b",
        "ranking": 50,
        "reason_of_close_description": "",
        "reason_of_close_id": null,
        "share_mode": 0,
        "step_id": "5854307d-d86e-4b97-be3f-a2c19f85ff07",
        "table_name": "oppty",
        "unit_id": "7d9467e0-d885-4729-877e-5c9e1e057b4a",
        "was_qualified": false,
        "revision": 3584,
        "value": {
        "base_value": 10000,
        "currency_id": "36665823-00d8-401f-b7d2-8e0736c3beb2",
        "value_foreign": 12500
        },
        "oppty_recurrence": null,
        "revenue_schedule": null,
        "product_relations": [],
        "primary_contact": null,
        "primary_account": "http://example.com",
        "contact_relations": [],
        "account_relations": [
                "http://example.com"
        ],
        "documents": [],
        "quote_relations": [],
        "status": 1,
        "qualify_date": null,
        "won_date": null,
        "lost_date": null,
        "days_in_step": 68,
        "is_favorite": false,
        "sharing_units": [],
        "sharing_clients": [],
        "tags": [],
        "formatted_name": "Double Entry Accounting Services",
        "modified_by_user": null
}

Create a linking between Custom Entity record and Opportunity

CustomEntities.update

Modifies CustomEntity or {custom_entity_api_name} with given id(s)

PATCHhttps://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}/{id}

Path parameters

custom_entity_api_name*string

Custom entity api name

id*string (uuid)

ID of CustomEntity to update

Query parameters

Body

id(s) of modified item(s) and fields to modify

namestring

Name of the entity and its default text representation.

Example: "string"

owner_idstring (uuid)

Relation to single entity instance.

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

share_modeenum

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

Example: 0

0123

type_idstring (uuid)

Relation to single entity instance.

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

unit_idstring (uuid)

Relation to single entity instance.

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

sharing_unitsarray of object

Relations to SalesUnits.

sharing_clientsarray of object

Relations to Clients.

documentsarray of object

Relations to CloudObjects.

revisioninteger (int32)

Revision when entity was lastly changed.

Example: 1

Response

Modification confirmation. Returns resulting CustomEntity

Body

successboolean

True when response succeeded, false on error.

Example: true

dataCustomEntity (object)

Request

const response = await fetch('https://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "success": true,
  "data": {
    "is_delete_protected": false,
    "id": "01234567-abcd-dcba-ffff-000000000000",
    "modified": "2019-01-01T00:00:00",
    "created": "2019-01-01T00:00:00",
    "owner": "https://example.com",
    "type": "https://example.com",
    "unit": "https://example.com",
    "name": "string",
    "owner_id": "01234567-abcd-dcba-ffff-000000000000",
    "share_mode": 0,
    "table_name": "string",
    "type_id": "01234567-abcd-dcba-ffff-000000000000",
    "unit_id": "01234567-abcd-dcba-ffff-000000000000",
    "is_deleted": false,
    "sharing_units": [
      "https://example.com"
    ],
    "sharing_clients": [
      "https://example.com"
    ],
    "documents": [
      "https://example.com"
    ],
    "is_favorite": false,
    "revision": 1
  }
}

{
	"cf_lookup_ce_mycustomentity_leadoppty": "0188d953-0aa6-1094-f764-1ce141993b26"
}

Success response

{
		"is_delete_protected": false,
		"id": "018ad5a4-2ea8-75f0-e8cc-c6e54688b165",
		"modified": "2023-09-27 07:57:01.480723+00:00",
		"created": "2023-09-27 07:57:01.480781+00:00",
		"owner": "http://example.com",
		"type": "http://example.com",
		"unit": "http://example.com",
		"name": "Custom Entity Record 3",
		"owner_id": "00000000-0000-0000-0000-000000011a7d",
		"share_mode": 0,
		"table_name": "ce_custom_entity1n",
		"type_id": "018ad56d-879c-b0dd-3c3a-75c59ab97a23",
		"unit_id": "7d9467e0-d885-4729-877e-5c9e1e057b4a",
		"is_deleted": false,
		"sharing_units": [],
		"sharing_clients": [],
		"documents": [],
		"is_favorite": false,
		"revision": 4464,
		"cf_priority": 2,
		"cf_lookup_ce_mycustomentity_leadoppty": [
				"id": "0188d953-0aa6-1094-f764-1ce141993b26",
				"name": "Double Entry Accounting Services",
				"picture_url": null,
				"entity_name": "Opportunity",
				"entity_api_name": null,
				"entity_type_id": null,
				"is_deleted": false,
				"is_available": true
		]
}

4. Filter existing Custom Entity record by custom field

Filter Custom Entity records using the specific conditions.

CustomEntities.list

Returns all defined {custom_entity_api_name}

GEThttps://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}

Path parameters

custom_entity_api_name*string

Custom entity api name

Query parameters

Response

list of {custom_entity_api_name}

Body

successboolean

True when response succeeded, false on error.

Example: true

dataarray of CustomEntity (object)

page_infoobject

Page info result set. Please note it is returned only when legacy limit & offset parameters are not used.

Request

const response = await fetch('https://us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "success": true,
  "data": [
    {
      "is_delete_protected": false,
      "id": "01234567-abcd-dcba-ffff-000000000000",
      "modified": "2019-01-01T00:00:00",
      "created": "2019-01-01T00:00:00",
      "owner": "https://example.com",
      "type": "https://example.com",
      "unit": "https://example.com",
      "name": "string",
      "owner_id": "01234567-abcd-dcba-ffff-000000000000",
      "share_mode": 0,
      "table_name": "string",
      "type_id": "01234567-abcd-dcba-ffff-000000000000",
      "unit_id": "01234567-abcd-dcba-ffff-000000000000",
      "is_deleted": false,
      "sharing_units": [
        "https://example.com"
      ],
      "sharing_clients": [
        "https://example.com"
      ],
      "documents": [
        "https://example.com"
      ],
      "is_favorite": false,
      "revision": 1
    }
  ],
  "page_info": {
    "start_cursor": "WyIwMSIsICJiMmYwODI0Ni1iYWE5LTQyY2QtYmM3Yi04YmM4MjY3M2E2NTgiXQ==",
    "end_cursor": "WyIwNSIsICJmMjZhZjZiMC00ZWE4LTQ3MDgtODU2NC0wN2JmYzI4ZGQ5ZTgiXQ==",
    "has_previous_page": true,
    "has_next_page": true
  }
}

{{baseUrl}}/entities/MyCustomEntity?filter-op[cf_priority]=gt&filter[cf_priority]=3

Success response

{
		"is_delete_protected": false,
		"id": "012bc5a7-23e8-15a0-a51b-e6c5462eb415",
		"modified": "2023-09-27 07:32:01.480723+00:00",
		"created": "2023-09-27 07:32:01.480781+00:00",
		"owner": "http://example.com",
		"type": "http://example.com",
		"unit": "http://example.com",
		"name": "Custom Entity Record 1",
		"owner_id": "00000000-0000-0000-0000-000000011a7d",
		"share_mode": 0,
		"table_name": "ce_custom_entity1n",
		"type_id": "018ad56d-879c-b0dd-3c3a-75c59ab97a23",
		"unit_id": "7d9467e0-d885-4729-877e-5c9e1e057b4a",
		"is_deleted": false,
		"sharing_units": [],
		"sharing_clients": [],
		"documents": [],
		"is_favorite": false,
		"revision": 4364,
		"cf_priority": 4,
		"cf_lookup_ce_mycustomentity_leadoppty": []
}

PreviousCreate Product, Product Line Item NextUpload Document

Last updated 1 year ago