How to Read Objects

All of the read functions have a similar structure, requiring a page number, an optional filter, and some additional parameters. Read functions return an object or objects pertaining to the call that was made. For example, readContacts, may return 1 or many contact objects. The data fields returned vary depending on the data requested. For a list of all the data fields that could potentially be returned for an object, see the page that documents the object. You can find a list of all the availabe objects here.

NOTE - At peak times, there is a chance there may be a slight delay when reading data.

Limits for Results

The return result of each read function is currently limited to a maximum of 5000 objects. This maximum is not guaranteed and should not be relied upon; in the future the API may allow you to define a custom maximum count value. The ordering of a given return is determined by the API and should be relied upon for batching purposes only.

Retrieving All Results / Paging

In order to retrieve all objects in a result set, you must iterate over all the available pages. This is done by incrementing the pageNumber parameter on subsequent read calls (except for readActivities, see below). When the API returns an empty result set, you know that you have retrieved all objects available. The initial page number is 1. The behavior of making multiple read calls to the same page is not defined and should not be relied upon to perform successfully.

readActivities Paging

The readActivities call takes a slightly different approach to paging. For readActivities, instead of using page numbers, you will specify a readDirection with the following values; FIRST or NEXT. The default is FIRST. If you try to start a query with NEXT, it will throw an error. NEXT allows you to read the next page of results. To view example code that uses FIRST and NEXT, click here.

Filters

Filters allow you to specify conditions that must be met in order for a given object to be returned. These conditions are instantiated as a set of criteria linked by an operator. Each criteria is defined by the attribute to compare the type of comparison to make, and finally the value to compare to. Filters are optional; you may include no filter, or you may include several filters to further refine your result set.