Pipeliner CRM API Getting Started

Here are some resources that will help you understand the basics of all our APIs.

Pipeliner CRM API Authentication

Every method is authorized by username, password and team’s space name. The REST API layer uses the Basic Authentication method. Each team space has its own API Token and API Password which is used as username and password. These credentials can be obtained through the Customer’s portal. For more information, see related guide how to obtain API credentials.

Every REST call must contain an "Authorization" header with an encoded username and password. If the "Authorization" header is missing, a response with status code "401 Unauthorized" and header WWW-Authenticate: Basic realm="restapi" is sent to the client.

Example:

For "usr" as username and "pwd" as a password, the authentication header is formed as follows:

Authorization: Basic dXNyOnB3ZA==

The value is computed as base64("usr:" + "pwd")

Pipeliner CRM API Querying

The GET methods on entity collections support a few parameters for querying, filtering and pagination of the results. Parameters are:

Parameter Type Description
limit int Limits the number of returned entities. (Default=25)
offset int Starting offset of returned entities. (Default=0)
sort string Used to sort retrieved entities.
filter string Filters returned entities by given property/value pairs.
after string Retrieves entities which were modified after specified date.
loadonly string Select only specific fields from the entity.

Range-Based Responses

For a range-based request via query-string parameters, the server responds with a Content-Range header to indicate how many items are being returned and how many total items exist yet to be retrieved: Content-Range: items 0-24/66

Note that the total items available (e.g. 66 in this case) is not zero-based. Hence, requesting the last few items in this data set would return a Content-Range header as follows: Content-Range: items 40-65/66

Sorting

Sorting utilizes a sort query-string parameter that contains a delimited set of property names. Behavior is, for each property name, sorted in ascending order, and for each property prefixed with a dash ("-") sorted in descending order. Separate each property name/value pair with a vertical bar ("|").

For example, if we want to retrieve Contacts in order of their last name (ascending), first name (ascending) and modification time (descending), the request looks like this:

GET https://api.pipelinersales.com/rest_services/v1/eu_testTeamSpaceDbName/Contacts?sort=SURNAME|FIRST_NAME|-MODIFIED

To achieve a reverse chronological ordering of retrieved entities, use:

-PPL_CHRONOLOGICAL|-CREATED for sorting.

Filtering

The individual filter phrases are separated by a vertical bar ("|") and to separate the names, values and optionally operator a double colon ("::") is used. By default, values are compared by the equality operator. Suppose we want to request Contacts with the name "Todd" who live in "Denver" and have the position of "Manager". Supported Operators:

Operator Condition Limitation Description
eq if(a == b) none Returns entities with equal field values.
ne if(a != b) none Returns entities with not equal field values.
gt if(a > b) none Returns entities with greater field values.
lt if(a < b) none Returns entities with lesser field values.
ge if(a >= b) none Returns entities with greater or equal field values.
le if(a <= b) none Returns entities with lesser or equal field values.
ll if(s%) string only Returns entities with left like field values.
rl if(%s) string only Returns entities with right like field values.
fl if(%s%) string only Returns entities with full like field values.
in if a in [a, b, c] none Returns entities with value in list of values. Values are separated by single ":". E.g. ?filter=FIRST_NAME::Todd:Richard::in

Escaping

In order to use separator characters "|", ":" and "::" for non-separating purpose, it is required to escape them first. To escape these characters use the separator "\".

A request URI for organizations "Example: Corp" and "Another Corp" might look like:

GET .../Accounts?filter=ORGANIZATION::Example\: Corp:Another Corp::in

It is also advised to a URI encode filter value, so the final query will look like:

GET .../Accounts?filter=ORGANIZATION%3A%3AExample%5C%3A%20Corp%3AAnother%20Corp%3A%3Ain

To use an escape character for non-escaping purpose, simply use double backslash "\\", so a query for company name "N\A" will look like.

GET .../Accounts?filter=ORGANIZATION::N\\A

And after URI encode:

GET .../Accounts?filter=ORGANIZATION::N%5C%5CA

Selecting fields

Selecting specific fields can be useful when there are only specific fields. Requested entities are returned faster than on a full entity load. If the loadonly parameter is not set, a full load is performed. Fields are separated by the vertical bar ("|"). Suppose we want to request only the ID and name from Contacts. The requested URI might look like:

GET https://api.pipelinersales.com/rest_services/v1/eu_testTeamSpaceDbName/Contacts?loadonly=FIRST_NAME|MIDDLE_NAME|SURNAME