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 available objects here.
NOTE – At peak times, there is a chance there may be a delay when reading data.
Limits for Results
The return result of each read function is currently limited to a maximum of 5000 objects per page, with the exception of readConversions which has a maximum of 100. 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 readRecentInboundActivities and readRecentOutboundActivities, 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 consistently.
The readRecentInboundActivities and readRecentOutboundActivities calls take a slightly different approach to paging. For readRecentInboundActivities and readRecentOutboundActivities, instead of using page numbers, you will specify a readDirection with the following values;
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.
In order to speed up your access to data, we use a technique called caching. What this means in practical terms is that the first time you make an API call, it may take a few minutes to return. However, for the next 100 pages, the API will return your results almost instantly. For the most part, this is very efficient, but there is a catch. These results are only stored in the cache for a few minutes. So, if you request a page and then wait a few minutes and request the next page, it may have to run the slower query again, which could take several minutes.
The best practice for accessing your data quickly is to minimize the delay between page requests.
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.