Introduction Concepts App Registration Making API Test Calls Authentication OData Search Events and Webhooks Specifications Profiles API Agencies API Licenses API Accounts API Plans API Policies API Events API Carriers API Content API

OData Overview

The Zywave API search is implemented using OData Version 4.01. OData searches are comprised of four optional query parameters: $filter, $oderBy, $skip, and $top. If $filter is not set, no records will be excluded from the result set. If $orderBy is not set, the order of records in the result set will be indeterminate. The $skip parameter defaults to 0 and the $top parameter will default to 100. In other words, if $skip and $top are both omitted from the search, then the first 100 records of the result set (or all records if there are 100 or fewer) will be returned in the order (if any) specified by the $orderBy parameter.

Note: For clarity, the OData query examples provided below are written without escape characters. However, any URI-reserved characters must be escaped.

Filtering

OData filters are built by combining boolean expressions with and, or, and not boolean operators. The expressions within a filter are created by comparing a property with one or more literal values using supported comparison operators. The following comparison operations are supported by the Zywave API; each is accompanied by an example request. Note that string operations are case insensitive.

Operation
Example
Returns
startswith
startswith(Name,'Zyw')
Returns all records where Name starts with 'Zyw'
endswith
endswith(Name,'wave')
Returns all records where the Name ends with 'wave'
contains
contains(Name,'wave')
Returns all records where the Name contains 'wave'
eq (Equals)
Name eq 'Zywave'
Returns all records where Name is 'Zywave'
ne (Not Equals)
Name ne 'Zywave'
Returns all records where Name is not 'Zywave'
gt (Greater Than)
Price gt 4.5
Returns all records where Price is greater than 4.5
ge (Greater Than Or Equals)
Price ge 4.5
Returns all records where Price is greater than or equal to 4.5
lt (Less Than)
Price lt 4.5
Returns all records where Price is less than 4.5
le (Less Than Or Equals)
Price le 4.5
Returns all records where Price is less than or equal to 4.5
in (Exactly Matches At Least One Of)
Name in ('Zyw', 'ave')
Returns all records where Name is either 'Zyw' or 'ave'.

When querying the Zywave API against a DateTime field, use the format YYYY-MM-DDTHH:MM:SS.fffZ. For example, the following filter will return all records with State equal to 'WI' and UpdatedDateTime on or after January of 2019:

State eq 'WI' and UpdatedDateTime ge 2019-01-01T00:00:00.000Z

Note: Zywave API search methods may not support filtering on certain properties of the model. See the relevant endpoint specification for details about which properties may be referenced in the $filter parameter.

Sorting with $orderBy

To order the result set by one or more properties, specify the property name and either asc for ascending or desc for descending in the $orderBy parameter. For example, the following $orderBy value will return records in descending order of updateDateTime (most recent first) and alphabetically by name

updatedDateTime desc, name asc

Pagination with $skip and $top

The Zywave search methods use the OData $skip and $top query options to retrieve specific subsets of the full result set. When the $skip option is used, the first $skip records of the full result set are excluded. When the $top option is used, only the first $top records of the result set are returned. The $skip option is always applied before the $top option. For example, if there are 100 records in the full result set, and you wish to only show records 21 through 25, then $skip should be set to 20 and $top should be set to 5.

If $orderBy is not set, then the order of results retrieved from the server is indeterminate. In order to paginate correctly, you must set the $orderBy parameter.