The API lets you fetch lists of data such as projects, jobs, orders, people, configurations and so on.
Lists are implemented in a standard way whatever the data is you want to retrieveRetrieves an aggregation (statistics) on the data, such as:
- Total jobs per job status
- Total deadlines per month
- etc.
URL
...
(POST) ./list(POST) ./list/full
PARAMETERS
Appending /full to the URL returns results with all the data fields.
/aggregations/{id}PARAMETERS
URL parameters are:
id | The aggregation to retrieve.Use ./list/aggregations to get a list of all available aggregations with their ids. If not specified, the system uses the default aggregation. This always is the aggregation with ID "default". | string, Optional |
The other parameters are included as a JSON object in the request body:
...
| query | Optional query string using a simple but powerful query language. Example:
The aggregation will be calculated for the queried data only. | Optional, string? | ||
| filter | An alternative, more structured way of filtering data. Contains an array of filter criteria. The exact details are field specific and are explained in the page of the specific API method.
| Optional, object[]? | ||
| fields | Optional array of fields to include in the results. By default, the API returns the most commonly used fields. Use the API method ./list/fields returns all available fields. Example:
| Optional, string[]? | ||
| allfields | If set to true then the query will return all fields. This has the same effect as adding /full to the URL. For performance reasons, we do not recommend this options. | Optional, bool? | ||
| sort
| Defines the sort order of the list. The array contains JSON objects, each with these properties:
Example:
Note: All lists always use a default sort order if none is specified here.
| Optional, object[]? | ||
| take | Optional. Number of element to retrieve (used for pagination). If not specified then default is 20. The maximum value is 500. | Optional, int? | ||
| skip | Optional. Number of element to skip (used for pagination). If not specified then default is 0. | Optional, int? |
About fields in results
If you execute a "list/full" query you get:
- All fields.
If you execute a "list" query you get:
- All fields listed in the query's fields parameter
- And all fields with isdata = true (these cannot be removed)
If you execute a "list" query without specifying the fields:
- And all fields with isdata = true or iscoldef = true (the columns displayed by default)
RESULTS
The method returns a JSON object with these properties:
| total | Total number of filtered accounts, i.e. accounts complying with the "filter". | int |
| count | Number of returned rows. | int |
| rows | Array of rows each containing all the field values. Each row contains the fields listed in layout.cols | array<object> |
| querytree | If the query is composed of ".Matches()" and "AND" clauses only (info), this property returns a JSON graph of the query. | object? |
Each element in rows contains the field values:
| Code Block |
|---|
{
"count": 20,
"total": 345,
"rows":
[
{
"jobid": 1001,
"reference": "Client A - 1002",
"iscodyt": true,
...
},
...
]
} |
Note that a field value can be of any type.
ACCESS RIGHTS
Please keep in mind that your access rights delimit both the data and the field values you can retrieve.
With limited rights you may not see all the jobs, maybe just yours.
With limited rights you may not see some customer details.
...
RESULTS
The method returns a JSON object with these properties:
| total | Total number of aggregated data rows. | int |
| buckets | A list of buckets. A bucket is the aggregated value, the total count of records with the value and descriptive information:
| int |
| properties | The details of the selected aggregation. Also see ./list/aggregations | array<object> |
EXAMPLES
An aggregation by job status:
| Code Block |
|---|
{
"total": 120,
"buckets": [
{
"value": 0,
"title": "Draft",
"css": "status draft",
"query": "{status}.Matches(0)",
"count": 119
},
{
"value": 2,
"title": "Inactive",
"css": "status inactive",
"query": "{status}.Matches(2)",
"count": 1
}
],
"properties": {
"id": "bystatus",
"name": "Job counts per status",
"desc": "Indicates total jobs per job status."
}
}
|