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.
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
GET methods on entity collections support a few parameters for querying, filtering and pagination of the results. Parameters are:
| || ||Limits the number of returned entities. (Default=25)|
| || ||Starting offset of returned entities. (Default=0)|
| || ||Used to sort retrieved entities.|
| || ||Filters returned entities by given property/value pairs.|
| || ||Retrieves entities which were modified after specified date.|
| || ||Select only specific fields from the entity.|
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 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:
To achieve a reverse chronological ordering of retrieved entities, use:
-PPL_CHRONOLOGICAL|-CREATED for sorting.
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:
| || || ||Returns entities with equal field values.|
| || || ||Returns entities with not equal field values.|
| || || ||Returns entities with greater field values.|
| || || ||Returns entities with lesser field values.|
| || || ||Returns entities with greater or equal field values.|
| || || ||Returns entities with lesser or equal field values.|
| || || ||Returns entities with left like field values.|
| || || ||Returns entities with right like field values.|
| || || ||Returns entities with full like field values.|
| || || ||Returns entities with value in list of values. Values are separated by single ":". E.g. ?filter=FIRST_NAME::Todd:Richard::in|
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:
To use an escape character for non-escaping purpose, simply use double backslash "\\", so a query for company name "N\A" will look like.
And after URI encode:
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: