Introduction
The API includes search methods for most of its objects. Overall, the search methods for each object work in the same way. Each search method looks through groups of its object type (for example, Contacts within a List or all Folders in the system) to find those that match user-supplied criteria, returns data for each matching item. If no search criteria are supplied, the search methods return data arrays for all items.
When to Use Get and Count Methods
Most search methods have corresponding get methods and count methods.
If you want to retrieve a single object and you know its ID, use the get method. The get method searches for one record and is much faster.
If you only need to know the number of objects, and not the details of each object, use the Count method. It can use the same search criteria and spends much less time transferring data.
Obtaining IDs
You can use the basic search method for each type of object to obtain its ID for use in another method. If possible, use information that is unique to the object so that you don't get more than a few records returned. For example, if you know a Contact's List ID and Email address, you can use searchContacts to search the List for the Email address and get back a few Contacts (or one Contact if there are no duplicates) and find the Contact ID in the data returned. This is true of any object. For example, if you know the name of a Message but not its ID, you can use searchMessages to search on the name. The method responds with no more than a few matching Messages, from which you can find the Message you are looking for, and use its ID.
Optional Parameters
Many of the search methods include optional limit, sort_by, sort_order, and offset parameters. You can use the first three individually. limit is the maximum number of items returned from the results. sort_by is the name of the value to sort the results by before returning them. If you do not specify an sort_by, the search method returns results unsorted. The value for sort_order is only significant if you specify sort_by. sort_order is descending by default, but you can also specify ascending. offset specifies how many results to skip before returning them.
Pagination
You can use limit, sort_by, sort_order, and offset together for the purpose of paginating your results. Most likely you want pages to appear in some significant order and direction, such as ascending by last_name. In this case, you set sort_by to last_name and order_direction to ASC. Sorting takes place in the system after it retrieves results. Then it narrows the results using offset and limit and returns them. To show 20 of the results in last_name order per page, set up a series of searches with limit and offset containing the following values:
- 1st page: limit=20, offset=0
- 2nd page: limit=20, offset=20
- 3rd page: limit=20, offset=40
and so on.
Using Search Criteria
The search methods use search arrays to specify search criteria. Search arrays have the format:
For example:
All search arrays are contained within multidimensional arrays (container arrays that contain one or more arrays). The following example shows how a container array holding two search arrays uses the searchLists method. Since multiple search arrays are ANDed, this example looks for Contacts in List 12345 who want to buy a house.
// Create a Search Object container
$searchLists = array();
// Add single search criteria Arrays to the container
$searchLists[] = array( 'id' 'exactly' '12345');
$searchLists[] = array( 'buy' 'exactly' 'yes');
// Call the API to find the Contacts in List '12345' that want to buy.
$response = request($ch, $encoder->request('searchLists', array($list_id, $searchLists))
Valid Relational Operators
| Operator | Data Type |
|---|---|
| exactly | string/int |
| not | string/int |
| greater_than | int |
| less_than | int |
| in | comma separated strings and/or ints |
| starts_with | string/int |
| ends_with | string/int |
| contains | string/int |
If an Operator is invalid, it defaults to exactly.