Parameters

CORE APIs allow you to use parameters to add extra logic before or after a method is executed. In other words, parameters allow you to specify any further action that you want to take on the resources. For GET requests, parameters are passed as a query string:

/activity?page=1,50

For POST and PUT requests, parameters not included in the URL are to be sent in the body of the request with a Content-Type of application/x-www-form-urlencoded:

Request

CORE APIs support the following query parameters for endpoints that retrieve a list of records:

  • Fields - Allows you to specify the model properties you want in the response body
  • Where - Allows you to retrieve only those records that match a query expression
  • OrderBy - Allows you to sort the records in ascending or descending order, by a specified property
  • Page - Allows you to specify the page number to retrieve and the total number of records per page
  • Expand - Allows you to retrieve nested or additional resources in the response body
  • Count - Allows you to count the total number of records in the list

OrderBy can be used only with properties that have the Sortable attribute and Where can be used only with properties that have the Filterable attribute.


Fields

Use the fields parameter to specify only those model properties that you want in the response body. To return the complete model, use (*) in the fields parameter. Multiple model properties are separated by a comma.
Example: An API call to the activity endpoint with the id, name, description, and billable properties in the fields parameter.

Request

Count

The count parameter allows you to retrieve the total number of records in the response. You need to combine it with the fields parameter as fields = count (*) to retrieve the record count instead of the list of records. Note that you cannot use the orderby and page parameters when using count. However, you can combine it with the where parameter to count the number of records in the filtered list.
Example: An API call to count the total number of activity records.

Request

Response

Where

Use the where parameter to retrieve only those records that match a query expression. You can combine multiple filterable properties in a single query expression using logical operators. However, long and complex where queries can cause time outs. We recommend that you keep them as simple as possible.

When passing a complex query in the where parameter, it is safer to enclose it in double quotes. Moreover, field values with type string or date-time must be enclosed in single quotes. You should also apply URL encoding to the where clause in the query parameter (after the =) where possible. Here is an example of the where parameter and its URL-encoded form:

where="isActive=true AND id='7d2b0c83-4459-4fd6-a6a0-00bd0271bb6d'"
where=%22isActive%3Dtrue%20AND%20id%3D'7d2b0c83-4459-4fd6-a6a0-00bd0271bb6d'%22

When filtering based on a nested object property, pass the complete nested structure in the where parameter. For example, to retrieve approved time entries, the request would be:

https://base_url/api/timeentry?where="workflow.action=2"
https://base_url/api/timeentry?where=%22workflow.action%3D2%22 (URL-encoded form)

When passing filterable enums in the where parameter, make sure you pass the values of the enums and not their descriptions. For dates, CORE APIs support the ISO 8601 date-time format: YYYY-MM-DDThh:mm:ss.

Example: An API call that lists only those activities whose isActive property is true.

Request

Example Enum: An API call that only lists accounts with type = 2 [Bank Account].

Request

Example for date: An API call that lists only those time entries whose date is greater than or equal to 2019-06-29 and less than or equal to 2019-07-30.

Request

OrderBy

Use the orderby parameter to specify the property by which you want to sort the records. For example, you could choose to sort the retrieved list of activities by the sortable property name. By default, the retrieved records are listed in ascending order. You can change from ascending to descending order (and vice versa) using the asc and desc keywords. Use the syntax shown in the following examples to retrieve the results in the order you want.

Example: This query returns the list of activities sorted in ascending order by activity name.

Request

You can also use the desc keyword to sort the response in descending order.

Example: This query returns the same result as the above query, but in descending order.

Request

Page

When calling the list endpoints, if there are a large number of records to retrieve, the response is paginated. This means the records are grouped into pages with a fixed number of records per page. When you call a list endpoint and the number of records exceeds 25, only the first page containing 25 records is returned in the response by default. To get to the next page of records or change the number of records returned per page, you need to use the page parameter. It allows you to specify the page number and number of records per page with the following syntax:
page = [page number], [number of records per page]

Important

  • Specifying the number of records per page is optional and, if not specified, the default value of 25 is used. If you do not use the expand parameter, you can set the number of records per page to a maximum of 1000.
  • When using the expand parameter, you are only allowed to retrieve a maximum of 100 records per page.
  • When requesting page 0 or a non-positive integer [-1,-2, -3, etc.], the endpoint returns the first page.
  • When requesting a page beyond the last calculated page, the endpoint returns NULL (204 No Content), marking the end of the result set.

Example: An API call to the activity endpoint requesting page number 2 and 3 records per page (page=2,3):

Request

Expand

By default, the list endpoints only return flat models in the response body and any nested resources are not retrieved. You can use the expand parameter to retrieve the nested resources. You can even request multiple nested resources separated by a comma using the expand parameter.

Example: An API call to the employee endpoint requesting the customFields nested resource.

Request

Operators

You can use operators in the where parameter to create expressions that specify the criteria to be used to filter the results. Operators are represented by special characters or keywords and are similar to SQL operators in function. For example, the equality operator is represented by an equal to sign (=) and the operator that tests for a null value is represented by the keywords IS NULL. CORE APIs allow you to use the following classes of operators:

Comparison Operators

A comparison (or relational) operator is a mathematical symbol which is used to compare two values. Comparison operators are used to test for conditions and only those records that match the condition are returned in the result. For example, you can use them in expressions that test whether a property equals a certain value, is greater than or equal to a certain value, and so on.

OperatorsDescription
=The equal to operator is used to test whether a proerty equals a certain value.
!=,<>The not equal to operator is used to test whether a property is not equal to a certain value.
>The greater than operator is used to test whether a property is greater than a certain value.
<The less than operator is used to test whether a property is less than a certain value.
>=The greater than equal to operator is used to test whether a property is greater than or equal to a certain value.
<=The less than equal to operator is used to test whether a property is less than or equal to a certain value.
INThe IN operator tests whether a property is within a set of specified values separated by commas.
NOT INThe NOT IN operator tests whether a property is not within a set of specified values separated by commas.
BETWEENThe BETWEEN operator tests whether a property lies within a range of values. The range consists of a beginning value, followed by an AND keyword, and an ending value.
LIKEThe LIKE operator tests whether a string type property matches a specified pattern. The pattern may include regular as well as wildcard characters.
NOT LIKEThe NOT LIKE operator tests whether a string type property does not match a specified pattern.
Logical Operators

Logical operators allow you to combine two or more comparison expressions into a single complex expression using the AND or OR logic.

OperatorsDescription
ANDThe logical AND operator combines two comparison expressions and returns results where both expressions are true.
ORThe logical OR operator combines two comparison expressions and returns results where either of the expressions are true.
Request
Request
Request