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.

get

/entities/Clients

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

/entities/Clients

GET /api/v100/rest/spaces/<space_id>/entities/Clients HTTP/1.1
Host: us-east.pipelinersales.com/api/v100/rest/spaces/<space_id>
Accept: */*

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

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

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

get

/entities/{custom_entity_api_name}Type

Returns CustomEntity Types

Path parameters

custom_entity_api_namestringRequired

Custom entity api name

Responses

200

CustomEntityType data

application/json

404

Sent when invalid ID is given

application / json

500

unexpected error

application / json

get

/entities/{custom_entity_api_name}Type

GET /api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}Type HTTP/1.1
Host: us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}
Accept: */*

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

post

/entities/{custom_entity_api_name}

Creates new CustomEntity

Path parameters

custom_entity_api_namestringRequired

Custom entity api name

Query parameters

validation-levelinteger · int32Optional

Specify validation level of CustomEntity 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-timeRead-onlyOptional

Creation time.

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

namestringOptional

Name of the entity and its default text representation.

Example: string

owner_idstring · uuidRequired

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

share_modeinteger · enumOptional

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

Example: 0Possible values:

type_idstring · uuidRequired

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

unit_idstring · uuidOptional

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

revisioninteger · int32Optional

Revision when entity was lastly changed.

Example: 1

Responses

201

Creation confirmation. Returns created CustomEntity

application/json

500

unexpected error

application / json

post

/entities/{custom_entity_api_name}

POST /api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name} HTTP/1.1
Host: us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}
Content-Type: application / json
Accept: */*
Content-Length: 332

{
  "name": "string",
  "owner_id": "01234567-abcd-dcba-ffff-000000000000",
  "share_mode": 0,
  "type_id": "01234567-abcd-dcba-ffff-000000000000",
  "unit_id": "01234567-abcd-dcba-ffff-000000000000",
  "sharing_units": [
    {
      "id": "https://example.com"
    }
  ],
  "sharing_clients": [
    {
      "id": "https://example.com"
    }
  ],
  "documents": [
    {
      "id": "https://example.com"
    }
  ],
  "revision": 1
}

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

get

/entities/Opportunities

Returns all defined Opportunities

Query parameters

include-deletedbooleanOptional

if enabled, deleted Opportunities 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.

beforestringOptional

Cursor until which to take entities to result set.

afterstringOptional

Cursor after which to start taking entities to result set.

expandstringOptional

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

Example: filter-op[name]=eq

load-onlystringOptional

Example: load-only=id,name,owner.id

Responses

200

list of Opportunities

application/json

500

unexpected error

application / json

get

/entities/Opportunities

GET /api/v100/rest/spaces/{space_id}/entities/Opportunities HTTP/1.1
Host: us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}
Accept: */*

{
  "success": true,
  "data": [],
  "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

patch

/entities/{custom_entity_api_name}/{id}

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

Path parameters

custom_entity_api_namestringRequired

Custom entity api name

idstring · uuidRequired

ID of CustomEntity to update

Query parameters

validation-levelinteger · int32Optional

Specify validation level of CustomEntity on update. 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

namestringOptional

Name of the entity and its default text representation.

Example: string

owner_idstring · uuidOptional

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

share_modeinteger · enumOptional

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

Example: 0Possible values:

type_idstring · uuidOptional

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

unit_idstring · uuidOptional

Relation to single entity instance.

Example: 01234567-abcd-dcba-ffff-000000000000

revisioninteger · int32Optional

Revision when entity was lastly changed.

Example: 1

Responses

200

Modification confirmation. Returns resulting CustomEntity

application/json

404

Sent when invalid ID is given

application / json

500

unexpected error

application / json

patch

/entities/{custom_entity_api_name}/{id}

PATCH /api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name}/{id} HTTP/1.1
Host: us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}
Content-Type: application/json
Accept: */*
Content-Length: 332

{
  "name": "string",
  "owner_id": "01234567-abcd-dcba-ffff-000000000000",
  "share_mode": 0,
  "type_id": "01234567-abcd-dcba-ffff-000000000000",
  "unit_id": "01234567-abcd-dcba-ffff-000000000000",
  "sharing_units": [
    {
      "id": "https://example.com"
    }
  ],
  "sharing_clients": [
    {
      "id": "https://example.com"
    }
  ],
  "documents": [
    {
      "id": "https://example.com"
    }
  ],
  "revision": 1
}

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

get

/entities/{custom_entity_api_name}

Returns all defined {custom_entity_api_name}

Path parameters

custom_entity_api_namestringRequired

Custom entity api name

Query parameters

include-deletedbooleanOptional

if enabled, deleted {custom_entity_api_name} 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.

beforestringOptional

Cursor until which to take entities to result set.

afterstringOptional

Cursor after which to start taking entities to result set.

expandstringOptional

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

Example: filter-op[name]=eq

load-onlystringOptional

Example: load-only=id,name,owner.id

Responses

200

list of {custom_entity_api_name}

application/json

500

unexpected error

application / json

get

/entities/{custom_entity_api_name}

GET /api/v100/rest/spaces/{space_id}/entities/{custom_entity_api_name} HTTP/1.1
Host: us-east.api.pipelinersales.com/api/v100/rest/spaces/{space_id}
Accept: */*

{
  "success": true,
  "data": [],
  "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 2 years ago

hashtagTutorial Assignment

hashtag0. Required fields

hashtag1. Prepare Data

hashtagOwner_id

hashtagType_id

hashtag2. Create Custom Entity record

hashtagCustomEntities.create

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

hashtagGet Opportunity_id

hashtagOpportunities.list

hashtagCustomEntities.update

hashtag4. Filter existing Custom Entity record by custom field

hashtagCustomEntities.list

Tutorial Assignment

0. Required fields

1. Prepare Data

Owner_id

Type_id

2. Create Custom Entity record

CustomEntities.create

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

Get Opportunity_id

Opportunities.list

CustomEntities.update

4. Filter existing Custom Entity record by custom field

CustomEntities.list