Parameters

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.

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.

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:

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:

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

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

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.

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.

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.

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):

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.

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.

Logical Operators

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