<% user.full_name %>
<% util.level ? util.level.title : '' %>
Explorer Pioneer Apollo Viking Voyager Pathfinder Orion
Points
<% user.points ? user.points.toLocaleString() : 0 %>
Badges
<% util.badgeCount %>
Streaks
Congratulations You've <% util.newestBadge.isCurriculum ? 'completed' : 'earned' %> the
<% util.newestBadge.title %> <% util.newestBadge.isCurriculum ? 'curriculum' : 'badge' %>!
previous
next
Share to Social Media
Linked In Facebook
Status
<% util.level ? util.level.title : '' %>
<% util.level ? util.level.points : '' %>
<% util.nextLevel ? util.nextLevel.title : '' %>
<% util.nextLevel ? util.nextLevel.points : '' %>
Level up! <% util.levelPointsRemaining %> points to go
Level up! <% util.levelPointsRemaining %> points to go
Badges
Completed Hitchhikers Track Completed Content Track Completed Pages Track Completed Page Builder Track Completed Search Backend Track Completed Search Frontend Theme Track Completed Search UI React Track Completed Solution Templates and the Admin Console Track Completed Technical Skills Track Completed Platform Basics Track Completed Listings Track Completed Reviews Track Completed Industry Overview Track Completed Analytics Track Completed Industry Overview & Product Basics Track Completed Multi-Language Experiences Track Completed Chat Track
<% util.expandBadges ? 'Less' : 'More' %>
Playground Accounts
New +
No Playground Accounts
Create Playground +
View Profile
Log Out loading
Mission Complete! 🚀
Congratulations, you’ve completed your first module!

We hope you enjoy exploring the rest of the site. Please don’t forget to leave us feedback - we are constantly looking to improve. Happy Hitchhiking!
Home
Welcome to Hitchhikers! 👋
To learn more about the platform we encourage you to get started by completing the Hitchhikers Program Track and earning your first badge!
Start Here
Close notification
< DOCS HOME
Search
Content Delivery APIs
No results in this galaxy.
Try searching all of Hitchhikers here.
Introduction
Overview - Policies and Conventions
API Availability
Authentication
Versioning
Serialization
Content-Type Headers
PUT Requests
Dates and Times
Account ID
Actor Headers
Response Format
Client vs Yext-assigned IDs
Logging
Errors
Issues and Warnings
Status Codes
Errors and Debugging — Secure Token API
Changelog
October 30, 2024 Release
September 18, 2024 Release
September 10, 2024 Release
August 7, 2024 Release
July 2, 2024 Release
May 15, 2024 Release
April 3, 2024 Release
Content
Content
Content: Get
Content: List
ECLs
Menus: Get
Bios: Get
Products: Get
Events (Legacy): Get
Q&A Submission
Q&A Submission
Question: Create
Review Submission
Review Submission
Review: Create
Review: Update
Review: Delete
Search
Universal Search
Universal Search: Autocomplete
Universal Search: Query
Vertical Search
Vertical Search: Autocomplete
Vertical Search: Query
Vertical Search: Filter Search
Generate Answer
Answer: Generate
Chat
Chat
Chat: Message Endpoint
Legacy
Entities
Entities: List
Entities: Get
Entities: GeoSearch
Entities Schema: Get
Entity Language Profiles: Get
Entity Language Profiles: List
Entity Language Profiles: List All
Locations
Language Profiles (Legacy): Get
Language Profiles Schema (Legacy): Get
Locations (Legacy): Get
Locations (Legacy): List
Locations Schema (Legacy): Get
Locations (Legacy): GeoSearch
home
API docs by Redocly

Entities: List

Retrieve a list of Entities within an account

NOTE: Responses will contain resolved values for embedded fields

path Parameters
accountId
required
string >= 0 characters
query Parameters
v
required
string >= 0 characters

A date in YYYYMMDD format.

convertMarkdownToHTML
string >= 0 characters

Optional parameter to return fields of type Markdown as HTML.

  • false: Markdown fields will be returned as JSON
  • true: Markdown fields will be returned as HTML
convertRichTextToHTML
string >= 0 characters

Optional parameter to return fields of type Rich Text as HTML.

  • false: Rich Text fields will be returned as JSON
  • true: Rich Text fields will be returned as HTML
entityTypes
string >= 0 characters

Comma-separated list of Entity types to filter on. Example: "location,event"

Should be from the following types:

  • atm
  • event
  • faq
  • financialProfessional
  • healthcareFacility
  • healthcareProfessional
  • hotel
  • hotelRoomType
  • job
  • location
  • organization
  • product
  • restaurant

OR the API name of a custom entity type.

fields
string >= 0 characters

Comma-separated list of field names. When present, only the fields listed will be returned. You can use dot notation to specify substructures (e.g., "address.line1"). Custom fields are specified in the same way, albeit with their c_* name.

filter
string >= 0 characters

This parameter represents one or more filtering conditions that are applied to the set of entities that would otherwise be returned. This parameter should be provided as a URL-encoded string containing a JSON object.

For example, if the filter JSON is {"name":{"$eq":"John"}}, then the filter param after URL-encoding will be: filter=%7B%22name%22%3A%7B%22%24eq%22%3A%22John%22%7D%7D

Basic Filter Structure

The filter object at its core consists of a matcher, a field, and an argument.

For example, in the following filter JSON:

{
"name":{
"$eq":"John"
}
}

$eq is the matcher, or filtering operation (equals, in this example),

name is the field being filtered by, and

John is value to be matched against.

Combining Multiple Filters

Multiple filters can be combined into one object using combinators. For example, the following filter JSON combines multiple filters using the combinator $and. $or is also supported.

{
"$and":[
{
"firstName":{
"$eq":"John"
}
},
{
"countryCode":{
"$in":[
"US",
"GB"
]
}
}
]
}

Filter Negation

Certain filter types may be negated. For example:

{
"$not": {
"name": {
"$eq": "John"
}
}
}

This can also be written more simply with a ! in the $eq parameter. The following filter would have the same effect:

{
"name":{
"!$eq":"John"
}
}

Filter Complement

You can also search for the complement of a filter. This filter would match entities that do not contain "hello" in their descriptions, or do not have a description set. This is different from negation which can only match entities who have the negated field set to something.

{
"$complement":{
"description":{
"$contains":"hello"
}
}
}

Addressing Subfields

Subfields of fields can be addressed using the "dot" notation while filtering. For example, if you have a custom field called c_myCustomField:

{
"c_myCustomField":{
"age": 30,
"name": "Jim",
}
}

While filtering, subfields may be addressed using the "dot" notation.

{
"c_myCustomField.name":{
"!$eq":"John"
}
}

Fields that are nested deeper may be addressed using dot notation, as well. For example, if name in the above example was a compound field with two subfields first and last, first may be addressed as c_myCustomField.name.first.

Field Support

Entity fields correspond to certain filter types, which support matchers. Going by the example above, the field name supports the TEXT filter type, which supports $eq (equals) and $startsWith (starts with).

TEXT

The TEXT filter type is supported for text fields. (e.g., name, countryCode)

Matcher Details
$eq (equals) 
{
"countryCode":{
"$eq":"US"
}
},
{
"countryCode":{
"!$eq":"US"
}
}

Supports negation. Case insensitive.

$startsWith

Matches if the field starts with the argument value.

e.g., "Amazing" starts with "amaz"

{
"address.line1":{
"$startsWith": "Jo"
}
}

Supports negation. Case insensitive.

$in

Matches if field value is a member of the argument list.

{
"firstName":{
"$in": ["John", "Jimmy"]
}
}

Does not support negation. Negation can be mimicked by using an "OR" matcher, for example:

{
"$and":[
{
"firstName":{
"!$eq": "John"
}
},
{
"firstName":{
"!$eq": "Jimmy"
}
}
]
}
$contains 
{
"c_myString":{
"$contains":"sample"
}
}

This filter will match if "sample" is contained in any string within c_myString.

Note that this matching is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAny 
{
"c_myString":{
"$containsAny":[
"sample1", "sample2"
]
}
}

This filter will match if either "sample1" or "sample2" is contained in any string within c_myString. The argument list can contain more than two strings.

Note that this matching is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAll 
{
"c_myString":{
"$containsAll":[
"sample1",
"sample2"
]
}
}

This filter will match if both "sample1" and "sample2" are contained in any string within c_myString. The argument list can contain more than two strings.

Note that this matching is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

BOOLEAN

The BOOLEAN filter type is supported for boolean fields and Yes / No custom fields.

Matcher Details
$eq 
{
"isFreeEvent": {
"$eq": true
}
}

For booleans, the filter takes a boolean value, not a string. Supports negation.

STRUCT

The STRUCT filter type is supported for compound fields with subfields.

*e.g., address, featuredMessage, fields of custom types*

Matcher Details
$hasProperty

Matches if argument is a key (subfield) of field being filtered by. This filter type is useful for filtering by compound fields or to check if certain fields have a value set.

{
"address": {
"$hasProperty": "line1"
}
}

Note that if a given property of a compound field is not set, the filter will not match. For example, if line1 of address is not set for an entity, then the above matcher will not match the entity.

Supports negation.

OPTION

The OPTION filter type is supported for options custom fields and fields that have a predetermined list of valid values.

*e.g., eventStatus, gender, SINGLE_OPTION and MULTI_OPTION types of custom fields.*

Matcher Details
$eq

Matching is case insensitive and insensitive to consecutive whitespace.

e.g., "XYZ 123" matches "xyz 123"

{
"eventStatus": {
"$eq": "SCHEDULED"
}
}

Supports negation. Negating $eq on the list will match any field that does not hold any of the provided values.

$in 
{
"eventStatus": {
"$in": [
"SCHEDULED",
"POSTPONED"
]
}
}

Does not support negation. However, negation can be mimicked by using an $and matcher to negate individually over the desired values. For example:

{
"$and": [
{
"eventStatus":{
"!$eq": "SCHEDULED"
}
},
{
"firstName":{
"!$eq": "POSTPONED"
}
}
]
}

PHONE

The PHONE filter type is supported for phone number fields only. PHONE will support the same matchers as TEXT, except that for $eq, the same phone number with or without calling code will match.

Matcher Details
$eq 
{
"mainPhone":{
"$eq":"+18187076189"
}
},
{
"mainPhone":{
"$eq":"8187076189"
}
},
{
"mainPhone":{
"!$eq":"9177076189"
}
}

Supports negation. Case insensitive.

$startsWith

Matches if the field starts with the argument value.

e.g., "8187076189" starts with "818"

{
"mainPhone":{
"$startsWith": "818"
}
}

Supports negation. Case insensitive.

$in

Matches if field value is a member of the argument list.

{
"mainPhone":{
"$in": [
"8185551616",
"9171112211"
]
}
}

Does not support negation. However, negation can be mimicked by using an $and matcher to negate individually over the desired values.

INTEGER, FLOAT, DATE, DATETIME, and TIME

These filter types are strictly ordered -- therefore, they support the following matchers:

  • Equals
  • Less Than / Less Than or Equal To
  • Greater Than / Greater Than or Equal To
Matcher Details
$eq

Equals

{
"ageRange.maxValue": {
"$eq": "80"
}
}

Supports negation.

$lt

Less than

{
"time.start": {
"$lt": "2018-08-28T05:56"
}
}
$gt

Greater than

{
"ageRange.maxValue": {
"$gt": "50"
}
}
$le

Less than or equal to

{
"ageRange.maxValue": {
"$le": "40"
}
}
$ge

Greater than or equal to

{
"time.end": {
"$ge":  "2018-08-28T05:56"
}
}
Combinations

While we do not support "between" in our filtering syntax, it is possible to combine multiple matchers for a result similar to an "and" operation:

{
"ageRange.maxValue : {
"$gt" : 10,
"$lt": 20
}
}

LIST OF TEXT

Any field that has a list of valid values and supports any of the previously mentioned filter types will also support the $contains matcher.

Matcher Details
$eq 
{
"c_myStringList": {
"$eq": "sample"
}
}

This filter will match if "sample" EXACTLY matches any string within c_myStringList.

Supports negation.

$eqAny 
{
"c_myStringList": {
"$eqAny": [
"sample1",
"sample2"
]
}
}

This filter will match if any one of "sample1" or "sample2" EXACTLY match a string within c_myStringList . The argument can have more than two strings.

Supports negation.

$eqAll 
{
"c_myStringList": {
"$eqAll": [
"sample1",
"sample2"
]
}
}

This filter will match if both "sample1" AND "sample2" EXACTLY match a string within c_myStringList. The argument can have more than two strings.

Supports negation.

$contains 
{
"c_myStringList":{
"$contains":"sample"
}
}

This filter will match if "sample" is contained in any string within c_myStringList.

Note that this matching is "left edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This is a sample", "Sample one", "Sample 2" but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAny 
{
"c_myStringList": {
"$containsAny": [
"sample1",
"sample2"
]
}
}

This filter will match if either "sample1" or "sample2" is contained in any string within c_myStringList. The argument list can have more than two strings.

Note that similar to $contains, the matching for $containsAny is "left edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This is a sample", "Sample one", "Sample 2" but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAll 
{
"c_myStringList": {
"$containsAll": [
"sample1",
"sample2"
]
}
}

This filter will match if BOTH "sample1" and "sample2" are contained in strings within c_myStringList. The argument list can have more than two strings.

Note that similar to $contains, the matching for $containsAll is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

$startsWith 
{
"c_myStringList": {
"$startsWith":"sample"
}
}

This filter will match if any string within c_myStringList starts with "sample".

Does not supports negation. Case Insensitive.

LIST OF BOOLEAN, OPTION, PHONE, INTEGER, FLOAT, DATE, DATETIME, OR TIME

Matcher Details
$eq 
{
"c_myDateList": {
"$eq": "2019-01-01"
}
}

This filter will match if "2019-01-01" EXACTLY matches any date within c_myDateList.

Supports negation.

$eqAny 
{
"c_myIntegerList": {
"$eqAny": [1, 2]
}
}

This filter will match if 1 or 2 EXACTLY match any integer within c_myIntegerList. The argument list can have more than two elements.

Supports negation.

$eqAll 
{
"c_myStringList": {
"$eqAll": [
"sample1",
"sample2"
]
}
}

This filter will match if both "2019-01-01" AND "2019-01-02" EXACTLY match a date within c_myDateList. The argument list can have more than two elements.

Supports negation.

LIST OF STRUCT

Filtering on lists of struct types is a bit nuanced. Filtering can only be done on lists of structs of the SAME type. For example, if c_myStructList is a list of compound fields with the subfields age and name, then one can address the age properties of each field in c_myStructList as a flattened list of integers and filtering upon them. For example, the following filter:

{
"c_myStructList.age":{
"$eq": 20
}
}

will match if any field in the list has an age property equal to 20. Similarly, any filter that can be applied to lists of integers could be applied to age in this case ($eq, $eqAll, $eqAny).

HOURS

By filtering on an hours field, you can find which entities are open or closed at a specified time or during a certain time range. All of these filters also take an entity’s holiday hours and reopen date into account.

Matcher Details
$openAt 
{
"hours": {
"$openAt":
"2019-01-06T13:45"
}
}

This filter would match entities open at the specified time.

$closedAt 
{
"hours": {
"$closedAt:
"2019-01-06T13:45"
}
}
$openForAllOf 
{
"hours": {
"$openForAllOf": {
"start":
"2019-01-06T13:45",
"end":
"2019-01-06T15:00"
}
}
}

This filter would match only those entities that are open for the entire range between 2019-01-06T13:45 and 2019-01-06T15:00.

{
"hours": {
"$openForAllOf":
"2019-05-10"
}
}

This filter would match entities open for the entire 24 hour period on 2019-05-10.

You can also supply a year, a month, or an hour to filter for entities open for the entire year, month, or hour, respectively.

$openForAnyOf 
{
"hours": {
"$openForAnyOf": {
"start": "now",
"end": "now+2h"
}
}
}

This filter will match any entities that are open for at least a portion of the time range between now and two hours from now.

$closedForAllOf 
{
"hours": {
"$closedForAllOf": {
"start":
"2019-01-06T13:45",
"end":
"2019-01-06T15:00"
}
}
}

This filter will match only those entities that are closed for the entire given time range.

$closedForAnyOf 
{
"hours": {
"$closedForAnyOf": {
"start":
"2019-01-06T13:45",
"end":
"2019-01-06T15:00"
}
}
}

This filter will match any entities that are closed for at least a portion of the given time range.

Filtering by Dates and Times

Time zones

The filtering language supports searching both in local time and within a certain time zone. Searching in local time will simply ignore the time zone on the target entities, while providing one will convert the zone of your queried time to the zone of the target entities.

To search in local time, simply provide the date or time without any zone: 2019-06-07T15:30 or 2019-06-07.

To conduct a zoned search, provide the name of the time zone in brackets after the time, as it is shown in the tz database: 2019-06-07T15:30[America/New_York] or 2019-06-06[America/Phoenix].

Date and time types

In addition to searching with dates and datetimes, you can also query with years, months, and hours. For example, the filter:

{
"time.start": {
"$eq": "2018"
}
}

would match all start times in the year 2018. The same logic would apply for a month (2019-05), a date (2019-05-01), or an hour (2019-05-01T06).

These types also work with ordered searches. For example:

{
"time.start": {
"$lt": "2018"
}
}

would match start times before 2018 (i.e., anything in 2017 or before). On the other hand, the same query with a $le matcher would include anything in or before 2018.

"Now" and Date Math

Instead of providing a static date or time, you can also use now in place of any date time. When you do so, the system will calculate the time when the query is made and conduct a zoned search.

In order to search for a future or past time relative to now, you can use date math. For example, you can enter now+3h or now-1d, which would mean 3 hours from now and 1 day ago, respectively. You can also add and subtract minutes (m), months (M), and years (y).

It is also possible to add or subtract time from a static date or datetime. Simply add || between the static value and any addition or subtraction. For example, 2019-02-03||+1d would be the same as 2019-02-04.

You can also convert date and time types to other types. For example, to convert the datetime 2019-05-06T22:15 to a date, use 2019-05-06T22:15||/d. Doing so would yield the same result as using 2019-05-06. This method also works with now: now/d will give you today’s date without the time.

Filtering Across an Entity

It is possible to search for a specific text string across all fields of an entity by using the $anywhere matcher.

Matcher Details
$anywhere

Matches if the argument text appears anywhere in the entity (including subfields, structs, and lists)

{
"$anywhere": "hello"
}

This filter will match all entities that contain the string "hello" or strings that begin with "hello".

Examples

The following filter will match against entities that:

  • Are of type event (note that entity types can also be filtered by the entityTypes query parameter)
  • Have a name that starts with the text "Century"
  • Have a maximum age between 10 and 20
  • Have a minimum age between 5 and 7
  • Start after 7 PM (19:00) on August 28, 2018
{
"$and":[
{
"entityType":{
"$eq":"event"
}
},
{
"name":{
"$startsWith":"Century"
}
},
{
"ageRange.maxValue":{
"$gt":10,
"$lt":20
}
},
{
"ageRange.minValue":{
"$gt":5,
"$lt":7
}
},
{
"time.start":{
"$ge":"2018-08-28T19:00"
}
}
]
}
format
string >= 0 characters
Default: "markdown"

Present if and only if at least one field is of type "Legacy Rich Text."

Valid values:

  • markdown
  • html
  • none
languages
string >= 0 characters

Comma-separated list of language codes.

When present, the system will return Entities that have profiles in one or more of the provided languages. For each Location, only the first available profile from the provided list of languages will be returned. The keyword "primary" can be used to refer to a Location’s primary profile without providing a specific language code. If an Entity does not have profiles in any of the languages provided, that Entity's primary profile will be returned.

limit
number multiple of 1 <= 50
Default: "10"

Number of results to return.

offset
number multiple of 1
Default: "0"

Number of results to skip. Used to page through results. Cannot be used together with pageToken.

For Live API requests, the offset cannot be higher than 9,950. For Knowledge API the maximum limit is only enforced if a filter and/or sortBy parameter are given.

pageToken
string >= 0 characters

If a response to a previous request contained the pageToken field, pass that field's value as the pageToken parameter to retrieve the next page of data.

savedFilterIds
string >= 0 characters

A comma-separated list of saved filter IDs.

When present, the system will return entities that are included in the filters matching all of the provided IDs.

sortBy
string >= 0 characters

A list of fields and sort directions to order results by. Each ordering in the list should be in the format {"field_name", "sort_direction"}, where sort_direction is either ASCENDING or DESCENDING.

For example, to order by name the sort order would be [{"name":"ASCENDING"}]. To order by name and then description, the sort order would be [{"name":"ASCENDING"},{"description":"ASCENDING"}].

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Entities: Get

Retrieve information for an Entity with a given ID

NOTE: Responses will contain resolved values for embedded fields

path Parameters
accountId
required
string >= 0 characters
entityId
required
string >= 0 characters

The external ID of the requested Entity

query Parameters
v
required
string >= 0 characters

A date in YYYYMMDD format.

convertMarkdownToHTML
string >= 0 characters

Optional parameter to return fields of type Markdown as HTML.

  • false: Markdown fields will be returned as JSON
  • true: Markdown fields will be returned as HTML
convertRichTextToHTML
string >= 0 characters

Optional parameter to return fields of type Rich Text as HTML.

  • false: Rich Text fields will be returned as JSON
  • true: Rich Text fields will be returned as HTML
fields
string >= 0 characters

Comma-separated list of field names. When present, only the fields listed will be returned. You can use dot notation to specify substructures (e.g., "address.line1"). Custom fields are specified in the same way, albeit with their c_* name.

format
string >= 0 characters
Default: "markdown"

Present if and only if at least one field is of type "Legacy Rich Text."

Valid values:

  • markdown
  • html
  • none

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Entities: GeoSearch

Gets multiple Entities with addresses near a given geographical point, ordered by proximity to that point and restricted to a radius.

NOTE: Responses will contain resolved values for embedded fields

path Parameters
accountId
required
string >= 0 characters
query Parameters
location
required
string >= 0 characters

Only entities near this position will be returned. The values can be specified in one of two ways:

  1. Latitude and Longitude: The latitude and longitude of the point, separated by a comma (e.g."40.740957,-73.987565"),

  2. Address: A free-form address to geocode into a latitude and longitude (e.g., "1 Madison Ave, New York, NY 10010" or "New York, NY").

Note that providing an address that resolves to an area, like a city or a postal code, does not restrict the search to exactly that area; it simply centers the search circle on a point in that area.

v
required
string >= 0 characters

A date in YYYYMMDD format.

countryBias
string >= 0 characters

The two-character ISO 3166-1 code of the country where the geocoder should be biased.

The value of the countryBias parameter influences the search results, but it does not guarantee that the geocoded location will be in the country provided.

If both countryBias and geocoderBias are provided, geocoderBias is given priority, but both values are considered in the search.

entityTypes
string >= 0 characters

Comma-separated list of Entity types to filter on. Example: "location,event"

Should be from the following types:

  • atm
  • event
  • faq
  • financialProfessional
  • healthcareFacility
  • healthcareProfessional
  • hotel
  • hotelRoomType
  • job
  • location
  • organization
  • product
  • restaurant

OR the API name of a custom entity type.

fields
string >= 0 characters

Comma-separated list of field names. When present, only the fields listed will be returned. You can use dot notation to specify substructures (e.g., "address.line1"). Custom fields are specified in the same way, albeit with their c_* name.

filter
string >= 0 characters

This parameter represents one or more filtering conditions that are applied to the set of entities that would otherwise be returned. This parameter should be provided as a URL-encoded string containing a JSON object.

For example, if the filter JSON is {"name":{"$eq":"John"}}, then the filter param after URL-encoding will be: filter=%7B%22name%22%3A%7B%22%24eq%22%3A%22John%22%7D%7D

Basic Filter Structure

The filter object at its core consists of a matcher, a field, and an argument.

For example, in the following filter JSON:

{
"name":{
"$eq":"John"
}
}

$eq is the matcher, or filtering operation (equals, in this example),

name is the field being filtered by, and

John is value to be matched against.

Combining Multiple Filters

Multiple filters can be combined into one object using combinators. For example, the following filter JSON combines multiple filters using the combinator $and. $or is also supported.

{
"$and":[
{
"firstName":{
"$eq":"John"
}
},
{
"countryCode":{
"$in":[
"US",
"GB"
]
}
}
]
}

Filter Negation

Certain filter types may be negated. For example:

{
"$not": {
"name": {
"$eq": "John"
}
}
}

This can also be written more simply with a ! in the $eq parameter. The following filter would have the same effect:

{
"name":{
"!$eq":"John"
}
}

Filter Complement

You can also search for the complement of a filter. This filter would match entities that do not contain "hello" in their descriptions, or do not have a description set. This is different from negation which can only match entities who have the negated field set to something.

{
"$complement":{
"description":{
"$contains":"hello"
}
}
}

Addressing Subfields

Subfields of fields can be addressed using the "dot" notation while filtering. For example, if you have a custom field called c_myCustomField:

{
"c_myCustomField":{
"age": 30,
"name": "Jim",
}
}

While filtering, subfields may be addressed using the "dot" notation.

{
"c_myCustomField.name":{
"!$eq":"John"
}
}

Fields that are nested deeper may be addressed using dot notation, as well. For example, if name in the above example was a compound field with two subfields first and last, first may be addressed as c_myCustomField.name.first.

Field Support

Entity fields correspond to certain filter types, which support matchers. Going by the example above, the field name supports the TEXT filter type, which supports $eq (equals) and $startsWith (starts with).

TEXT

The TEXT filter type is supported for text fields. (e.g., name, countryCode)

Matcher Details
$eq (equals) 
{
"countryCode":{
"$eq":"US"
}
},
{
"countryCode":{
"!$eq":"US"
}
}

Supports negation. Case insensitive.

$startsWith

Matches if the field starts with the argument value.

e.g., "Amazing" starts with "amaz"

{
"address.line1":{
"$startsWith": "Jo"
}
}

Supports negation. Case insensitive.

$in

Matches if field value is a member of the argument list.

{
"firstName":{
"$in": ["John", "Jimmy"]
}
}

Does not support negation. Negation can be mimicked by using an "OR" matcher, for example:

{
"$and":[
{
"firstName":{
"!$eq": "John"
}
},
{
"firstName":{
"!$eq": "Jimmy"
}
}
]
}
$contains 
{
"c_myString":{
"$contains":"sample"
}
}

This filter will match if "sample" is contained in any string within c_myString.

Note that this matching is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAny 
{
"c_myString":{
"$containsAny":[
"sample1", "sample2"
]
}
}

This filter will match if either "sample1" or "sample2" is contained in any string within c_myString. The argument list can contain more than two strings.

Note that this matching is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAll 
{
"c_myString":{
"$containsAll":[
"sample1",
"sample2"
]
}
}

This filter will match if both "sample1" and "sample2" are contained in any string within c_myString. The argument list can contain more than two strings.

Note that this matching is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

BOOLEAN

The BOOLEAN filter type is supported for boolean fields and Yes / No custom fields.

Matcher Details
$eq 
{
"isFreeEvent": {
"$eq": true
}
}

For booleans, the filter takes a boolean value, not a string. Supports negation.

STRUCT

The STRUCT filter type is supported for compound fields with subfields.

*e.g., address, featuredMessage, fields of custom types*

Matcher Details
$hasProperty

Matches if argument is a key (subfield) of field being filtered by. This filter type is useful for filtering by compound fields or to check if certain fields have a value set.

{
"address": {
"$hasProperty": "line1"
}
}

Note that if a given property of a compound field is not set, the filter will not match. For example, if line1 of address is not set for an entity, then the above matcher will not match the entity.

Supports negation.

OPTION

The OPTION filter type is supported for options custom fields and fields that have a predetermined list of valid values.

*e.g., eventStatus, gender, SINGLE_OPTION and MULTI_OPTION types of custom fields.*

Matcher Details
$eq

Matching is case insensitive and insensitive to consecutive whitespace.

e.g., "XYZ 123" matches "xyz 123"

{
"eventStatus": {
"$eq": "SCHEDULED"
}
}

Supports negation. Negating $eq on the list will match any field that does not hold any of the provided values.

$in 
{
"eventStatus": {
"$in": [
"SCHEDULED",
"POSTPONED"
]
}
}

Does not support negation. However, negation can be mimicked by using an $and matcher to negate individually over the desired values. For example:

{
"$and": [
{
"eventStatus":{
"!$eq": "SCHEDULED"
}
},
{
"firstName":{
"!$eq": "POSTPONED"
}
}
]
}

PHONE

The PHONE filter type is supported for phone number fields only. PHONE will support the same matchers as TEXT, except that for $eq, the same phone number with or without calling code will match.

Matcher Details
$eq 
{
"mainPhone":{
"$eq":"+18187076189"
}
},
{
"mainPhone":{
"$eq":"8187076189"
}
},
{
"mainPhone":{
"!$eq":"9177076189"
}
}

Supports negation. Case insensitive.

$startsWith

Matches if the field starts with the argument value.

e.g., "8187076189" starts with "818"

{
"mainPhone":{
"$startsWith": "818"
}
}

Supports negation. Case insensitive.

$in

Matches if field value is a member of the argument list.

{
"mainPhone":{
"$in": [
"8185551616",
"9171112211"
]
}
}

Does not support negation. However, negation can be mimicked by using an $and matcher to negate individually over the desired values.

INTEGER, FLOAT, DATE, DATETIME, and TIME

These filter types are strictly ordered -- therefore, they support the following matchers:

  • Equals
  • Less Than / Less Than or Equal To
  • Greater Than / Greater Than or Equal To
Matcher Details
$eq

Equals

{
"ageRange.maxValue": {
"$eq": "80"
}
}

Supports negation.

$lt

Less than

{
"time.start": {
"$lt": "2018-08-28T05:56"
}
}
$gt

Greater than

{
"ageRange.maxValue": {
"$gt": "50"
}
}
$le

Less than or equal to

{
"ageRange.maxValue": {
"$le": "40"
}
}
$ge

Greater than or equal to

{
"time.end": {
"$ge":  "2018-08-28T05:56"
}
}
Combinations

While we do not support "between" in our filtering syntax, it is possible to combine multiple matchers for a result similar to an "and" operation:

{
"ageRange.maxValue : {
"$gt" : 10,
"$lt": 20
}
}

LIST OF TEXT

Any field that has a list of valid values and supports any of the previously mentioned filter types will also support the $contains matcher.

Matcher Details
$eq 
{
"c_myStringList": {
"$eq": "sample"
}
}

This filter will match if "sample" EXACTLY matches any string within c_myStringList.

Supports negation.

$eqAny 
{
"c_myStringList": {
"$eqAny": [
"sample1",
"sample2"
]
}
}

This filter will match if any one of "sample1" or "sample2" EXACTLY match a string within c_myStringList . The argument can have more than two strings.

Supports negation.

$eqAll 
{
"c_myStringList": {
"$eqAll": [
"sample1",
"sample2"
]
}
}

This filter will match if both "sample1" AND "sample2" EXACTLY match a string within c_myStringList. The argument can have more than two strings.

Supports negation.

$contains 
{
"c_myStringList":{
"$contains":"sample"
}
}

This filter will match if "sample" is contained in any string within c_myStringList.

Note that this matching is "left edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This is a sample", "Sample one", "Sample 2" but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAny 
{
"c_myStringList": {
"$containsAny": [
"sample1",
"sample2"
]
}
}

This filter will match if either "sample1" or "sample2" is contained in any string within c_myStringList. The argument list can have more than two strings.

Note that similar to $contains, the matching for $containsAny is "left edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This is a sample", "Sample one", "Sample 2" but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAll 
{
"c_myStringList": {
"$containsAll": [
"sample1",
"sample2"
]
}
}

This filter will match if BOTH "sample1" and "sample2" are contained in strings within c_myStringList. The argument list can have more than two strings.

Note that similar to $contains, the matching for $containsAll is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

$startsWith 
{
"c_myStringList": {
"$startsWith":"sample"
}
}

This filter will match if any string within c_myStringList starts with "sample".

Does not supports negation. Case Insensitive.

LIST OF BOOLEAN, OPTION, PHONE, INTEGER, FLOAT, DATE, DATETIME, OR TIME

Matcher Details
$eq 
{
"c_myDateList": {
"$eq": "2019-01-01"
}
}

This filter will match if "2019-01-01" EXACTLY matches any date within c_myDateList.

Supports negation.

$eqAny 
{
"c_myIntegerList": {
"$eqAny": [1, 2]
}
}

This filter will match if 1 or 2 EXACTLY match any integer within c_myIntegerList. The argument list can have more than two elements.

Supports negation.

$eqAll 
{
"c_myStringList": {
"$eqAll": [
"sample1",
"sample2"
]
}
}

This filter will match if both "2019-01-01" AND "2019-01-02" EXACTLY match a date within c_myDateList. The argument list can have more than two elements.

Supports negation.

LIST OF STRUCT

Filtering on lists of struct types is a bit nuanced. Filtering can only be done on lists of structs of the SAME type. For example, if c_myStructList is a list of compound fields with the subfields age and name, then one can address the age properties of each field in c_myStructList as a flattened list of integers and filtering upon them. For example, the following filter:

{
"c_myStructList.age":{
"$eq": 20
}
}

will match if any field in the list has an age property equal to 20. Similarly, any filter that can be applied to lists of integers could be applied to age in this case ($eq, $eqAll, $eqAny).

HOURS

By filtering on an hours field, you can find which entities are open or closed at a specified time or during a certain time range. All of these filters also take an entity’s holiday hours and reopen date into account.

Matcher Details
$openAt 
{
"hours": {
"$openAt":
"2019-01-06T13:45"
}
}

This filter would match entities open at the specified time.

$closedAt 
{
"hours": {
"$closedAt:
"2019-01-06T13:45"
}
}
$openForAllOf 
{
"hours": {
"$openForAllOf": {
"start":
"2019-01-06T13:45",
"end":
"2019-01-06T15:00"
}
}
}

This filter would match only those entities that are open for the entire range between 2019-01-06T13:45 and 2019-01-06T15:00.

{
"hours": {
"$openForAllOf":
"2019-05-10"
}
}

This filter would match entities open for the entire 24 hour period on 2019-05-10.

You can also supply a year, a month, or an hour to filter for entities open for the entire year, month, or hour, respectively.

$openForAnyOf 
{
"hours": {
"$openForAnyOf": {
"start": "now",
"end": "now+2h"
}
}
}

This filter will match any entities that are open for at least a portion of the time range between now and two hours from now.

$closedForAllOf 
{
"hours": {
"$closedForAllOf": {
"start":
"2019-01-06T13:45",
"end":
"2019-01-06T15:00"
}
}
}

This filter will match only those entities that are closed for the entire given time range.

$closedForAnyOf 
{
"hours": {
"$closedForAnyOf": {
"start":
"2019-01-06T13:45",
"end":
"2019-01-06T15:00"
}
}
}

This filter will match any entities that are closed for at least a portion of the given time range.

Filtering by Dates and Times

Time zones

The filtering language supports searching both in local time and within a certain time zone. Searching in local time will simply ignore the time zone on the target entities, while providing one will convert the zone of your queried time to the zone of the target entities.

To search in local time, simply provide the date or time without any zone: 2019-06-07T15:30 or 2019-06-07.

To conduct a zoned search, provide the name of the time zone in brackets after the time, as it is shown in the tz database: 2019-06-07T15:30[America/New_York] or 2019-06-06[America/Phoenix].

Date and time types

In addition to searching with dates and datetimes, you can also query with years, months, and hours. For example, the filter:

{
"time.start": {
"$eq": "2018"
}
}

would match all start times in the year 2018. The same logic would apply for a month (2019-05), a date (2019-05-01), or an hour (2019-05-01T06).

These types also work with ordered searches. For example:

{
"time.start": {
"$lt": "2018"
}
}

would match start times before 2018 (i.e., anything in 2017 or before). On the other hand, the same query with a $le matcher would include anything in or before 2018.

"Now" and Date Math

Instead of providing a static date or time, you can also use now in place of any date time. When you do so, the system will calculate the time when the query is made and conduct a zoned search.

In order to search for a future or past time relative to now, you can use date math. For example, you can enter now+3h or now-1d, which would mean 3 hours from now and 1 day ago, respectively. You can also add and subtract minutes (m), months (M), and years (y).

It is also possible to add or subtract time from a static date or datetime. Simply add || between the static value and any addition or subtraction. For example, 2019-02-03||+1d would be the same as 2019-02-04.

You can also convert date and time types to other types. For example, to convert the datetime 2019-05-06T22:15 to a date, use 2019-05-06T22:15||/d. Doing so would yield the same result as using 2019-05-06. This method also works with now: now/d will give you today’s date without the time.

Filtering Across an Entity

It is possible to search for a specific text string across all fields of an entity by using the $anywhere matcher.

Matcher Details
$anywhere

Matches if the argument text appears anywhere in the entity (including subfields, structs, and lists)

{
"$anywhere": "hello"
}

This filter will match all entities that contain the string "hello" or strings that begin with "hello".

Examples

The following filter will match against entities that:

  • Are of type event (note that entity types can also be filtered by the entityTypes query parameter)
  • Have a name that starts with the text "Century"
  • Have a maximum age between 10 and 20
  • Have a minimum age between 5 and 7
  • Start after 7 PM (19:00) on August 28, 2018
{
"$and":[
{
"entityType":{
"$eq":"event"
}
},
{
"name":{
"$startsWith":"Century"
}
},
{
"ageRange.maxValue":{
"$gt":10,
"$lt":20
}
},
{
"ageRange.minValue":{
"$gt":5,
"$lt":7
}
},
{
"time.start":{
"$ge":"2018-08-28T19:00"
}
}
]
}
geocoderBias
string >= 0 characters

The latitude, longitude, and approximate radius in miles, separated by commas, where the geocoder should be biased.

languages
string >= 0 characters

Comma-separated list of language codes.

When present, the system will return Entities that have profiles in one or more of the provided languages. For each Location, only the first available profile from the provided list of languages will be returned. The keyword "primary" can be used to refer to a Location’s primary profile without providing a specific language code. If an Entity does not have profiles in any of the languages provided, that Entity's primary profile will be returned.

limit
number multiple of 1 <= 50
Default: "10"

Number of results to return.

offset
number multiple of 1
Default: "0"

Number of results to skip. Used to page through results. Cannot be used together with pageToken.

For Live API requests, the offset cannot be higher than 9,950. For Knowledge API the maximum limit is only enforced if a filter and/or sortBy parameter are given.

radius
number [ 0.1 .. 2500 ]
Default: "10"

Indicates the search radius around the provided location in miles

randomization
string >= 0 characters
Default: "0"

Determines the noise level for randomizing sort order. Must be between 0 and 1 inclusive.

A value of 0 results in no randomness: results are returned by order of distance.

A value of 1 results in full randomness: results within the radius are returned in a random order.

Only one of randomization and randomizationToken can be set.

randomizationToken
string >= 0 characters

To be used alongside offset to allow for movement through randomized search results. After the first search with randomization set, randomizationToken is returned, which should be passed into the request as this parameter in order to iterate through subsequent results under the same randomness.

Only one of randomization and randomizationToken can be set.

savedFilterIds
string >= 0 characters

A comma-separated list of saved filter IDs.

When present, the system will return entities that are included in the filters matching all of the provided IDs.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Entities Schema: Get

Gets the schema.org-compliant schema for the primary profile of a single Entity. Schema will vary depending on entity type.

path Parameters
accountId
required
string
entityId
required
string

The external ID of the requested Entity.

languageCode
required
string

The language code corresponding to the language of the profiles that the user wishes to retrieve

entityType
required
string

The type of entity to be created. Should be one of the following:

  • atm
  • event
  • healthcareFacility
  • healthcareProfessional
  • hotel
  • job
  • location
  • restaurant
  • faq

OR the API name of a custom entity type.

query Parameters
v
required
string

A date in YYYYMMDD format.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Entity Language Profiles: Get

Retrieve a Language Profile for an Entity

NOTE:

  • Responses will contain resolved values for embedded fields
  • If the fields parameter is unspecified, responses will contain the full entity profile for the requested language
path Parameters
accountId
required
string >= 0 characters
entityId
required
string >= 0 characters

The external ID of the requested Entity

languageCode
required
string >= 0 characters

The language code corresponding to the language of the profiles that the user wishes to retrieve

query Parameters
v
required
string >= 0 characters

A date in YYYYMMDD format.

convertMarkdownToHTML
string >= 0 characters

Optional parameter to return fields of type Markdown as HTML.

  • false: Markdown fields will be returned as JSON
  • true: Markdown fields will be returned as HTML
convertRichTextToHTML
string >= 0 characters

Optional parameter to return fields of type Rich Text as HTML.

  • false: Rich Text fields will be returned as JSON
  • true: Rich Text fields will be returned as HTML
fields
string >= 0 characters

Comma-separated list of field names. When present, only the fields listed will be returned. You can use dot notation to specify substructures (e.g., "address.line1"). Custom fields are specified in the same way, albeit with their c_* name.

format
string >= 0 characters
Default: "markdown"

Present if and only if at least one field is of type "Legacy Rich Text."

Valid values:

  • markdown
  • html
  • none

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Entity Language Profiles: List

Retrieve Language Profiles for an Entity

NOTE:

  • Responses will contain resolved values for embedded fields
  • If the fields parameter is unspecified, responses will contain the full entity profile for the requested language
path Parameters
accountId
required
string >= 0 characters
entityId
required
string >= 0 characters

The external ID of the requested Entity

query Parameters
v
required
string >= 0 characters

A date in YYYYMMDD format.

convertMarkdownToHTML
string >= 0 characters

Optional parameter to return fields of type Markdown as HTML.

  • false: Markdown fields will be returned as JSON
  • true: Markdown fields will be returned as HTML
convertRichTextToHTML
string >= 0 characters

Optional parameter to return fields of type Rich Text as HTML.

  • false: Rich Text fields will be returned as JSON
  • true: Rich Text fields will be returned as HTML
entityTypes
string >= 0 characters

Comma-separated list of Entity types to filter on. Example: "location,event"

Should be from the following types:

  • atm
  • event
  • faq
  • financialProfessional
  • healthcareFacility
  • healthcareProfessional
  • hotel
  • hotelRoomType
  • job
  • location
  • organization
  • product
  • restaurant

OR the API name of a custom entity type.

fields
string >= 0 characters

Comma-separated list of field names. When present, only the fields listed will be returned. You can use dot notation to specify substructures (e.g., "address.line1"). Custom fields are specified in the same way, albeit with their c_* name.

format
string >= 0 characters
Default: "markdown"

Present if and only if at least one field is of type "Legacy Rich Text."

Valid values:

  • markdown
  • html
  • none
languageCodes
string >= 0 characters

The comma-separated language codes corresponding to the languages of the profile that the user wishes to retrieve

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Entity Language Profiles: List All

Retrieve a list of Language Profiles for Entities within an account

NOTE:

  • Responses will contain resolved values for embedded fields
  • If the fields parameter is unspecified, responses will contain the full entity profile for the requested language
path Parameters
accountId
required
string >= 0 characters
query Parameters
v
required
string >= 0 characters

A date in YYYYMMDD format.

convertMarkdownToHTML
string >= 0 characters

Optional parameter to return fields of type Markdown as HTML.

  • false: Markdown fields will be returned as JSON
  • true: Markdown fields will be returned as HTML
convertRichTextToHTML
string >= 0 characters

Optional parameter to return fields of type Rich Text as HTML.

  • false: Rich Text fields will be returned as JSON
  • true: Rich Text fields will be returned as HTML
entityTypes
string >= 0 characters

Comma-separated list of Entity types to filter on. Example: "location,event"

Should be from the following types:

  • atm
  • event
  • faq
  • financialProfessional
  • healthcareFacility
  • healthcareProfessional
  • hotel
  • hotelRoomType
  • job
  • location
  • organization
  • product
  • restaurant

OR the API name of a custom entity type.

fields
string >= 0 characters

Comma-separated list of field names. When present, only the fields listed will be returned. You can use dot notation to specify substructures (e.g., "address.line1"). Custom fields are specified in the same way, albeit with their c_* name.

filter
string >= 0 characters

This parameter represents one or more filtering conditions that are applied to the set of entities that would otherwise be returned. This parameter should be provided as a URL-encoded string containing a JSON object.

For example, if the filter JSON is {"name":{"$eq":"John"}}, then the filter param after URL-encoding will be: filter=%7B%22name%22%3A%7B%22%24eq%22%3A%22John%22%7D%7D

Basic Filter Structure

The filter object at its core consists of a matcher, a field, and an argument.

For example, in the following filter JSON:

{
"name":{
"$eq":"John"
}
}

$eq is the matcher, or filtering operation (equals, in this example),

name is the field being filtered by, and

John is value to be matched against.

Combining Multiple Filters

Multiple filters can be combined into one object using combinators. For example, the following filter JSON combines multiple filters using the combinator $and. $or is also supported.

{
"$and":[
{
"firstName":{
"$eq":"John"
}
},
{
"countryCode":{
"$in":[
"US",
"GB"
]
}
}
]
}

Filter Negation

Certain filter types may be negated. For example:

{
"$not": {
"name": {
"$eq": "John"
}
}
}

This can also be written more simply with a ! in the $eq parameter. The following filter would have the same effect:

{
"name":{
"!$eq":"John"
}
}

Filter Complement

You can also search for the complement of a filter. This filter would match entities that do not contain "hello" in their descriptions, or do not have a description set. This is different from negation which can only match entities who have the negated field set to something.

{
"$complement":{
"description":{
"$contains":"hello"
}
}
}

Addressing Subfields

Subfields of fields can be addressed using the "dot" notation while filtering. For example, if you have a custom field called c_myCustomField:

{
"c_myCustomField":{
"age": 30,
"name": "Jim",
}
}

While filtering, subfields may be addressed using the "dot" notation.

{
"c_myCustomField.name":{
"!$eq":"John"
}
}

Fields that are nested deeper may be addressed using dot notation, as well. For example, if name in the above example was a compound field with two subfields first and last, first may be addressed as c_myCustomField.name.first.

Field Support

Entity fields correspond to certain filter types, which support matchers. Going by the example above, the field name supports the TEXT filter type, which supports $eq (equals) and $startsWith (starts with).

TEXT

The TEXT filter type is supported for text fields. (e.g., name, countryCode)

Matcher Details
$eq (equals) 
{
"countryCode":{
"$eq":"US"
}
},
{
"countryCode":{
"!$eq":"US"
}
}

Supports negation. Case insensitive.

$startsWith

Matches if the field starts with the argument value.

e.g., "Amazing" starts with "amaz"

{
"address.line1":{
"$startsWith": "Jo"
}
}

Supports negation. Case insensitive.

$in

Matches if field value is a member of the argument list.

{
"firstName":{
"$in": ["John", "Jimmy"]
}
}

Does not support negation. Negation can be mimicked by using an "OR" matcher, for example:

{
"$and":[
{
"firstName":{
"!$eq": "John"
}
},
{
"firstName":{
"!$eq": "Jimmy"
}
}
]
}
$contains 
{
"c_myString":{
"$contains":"sample"
}
}

This filter will match if "sample" is contained in any string within c_myString.

Note that this matching is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAny 
{
"c_myString":{
"$containsAny":[
"sample1", "sample2"
]
}
}

This filter will match if either "sample1" or "sample2" is contained in any string within c_myString. The argument list can contain more than two strings.

Note that this matching is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAll 
{
"c_myString":{
"$containsAll":[
"sample1",
"sample2"
]
}
}

This filter will match if both "sample1" and "sample2" are contained in any string within c_myString. The argument list can contain more than two strings.

Note that this matching is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

BOOLEAN

The BOOLEAN filter type is supported for boolean fields and Yes / No custom fields.

Matcher Details
$eq 
{
"isFreeEvent": {
"$eq": true
}
}

For booleans, the filter takes a boolean value, not a string. Supports negation.

STRUCT

The STRUCT filter type is supported for compound fields with subfields.

*e.g., address, featuredMessage, fields of custom types*

Matcher Details
$hasProperty

Matches if argument is a key (subfield) of field being filtered by. This filter type is useful for filtering by compound fields or to check if certain fields have a value set.

{
"address": {
"$hasProperty": "line1"
}
}

Note that if a given property of a compound field is not set, the filter will not match. For example, if line1 of address is not set for an entity, then the above matcher will not match the entity.

Supports negation.

OPTION

The OPTION filter type is supported for options custom fields and fields that have a predetermined list of valid values.

*e.g., eventStatus, gender, SINGLE_OPTION and MULTI_OPTION types of custom fields.*

Matcher Details
$eq

Matching is case insensitive and insensitive to consecutive whitespace.

e.g., "XYZ 123" matches "xyz 123"

{
"eventStatus": {
"$eq": "SCHEDULED"
}
}

Supports negation. Negating $eq on the list will match any field that does not hold any of the provided values.

$in 
{
"eventStatus": {
"$in": [
"SCHEDULED",
"POSTPONED"
]
}
}

Does not support negation. However, negation can be mimicked by using an $and matcher to negate individually over the desired values. For example:

{
"$and": [
{
"eventStatus":{
"!$eq": "SCHEDULED"
}
},
{
"firstName":{
"!$eq": "POSTPONED"
}
}
]
}

PHONE

The PHONE filter type is supported for phone number fields only. PHONE will support the same matchers as TEXT, except that for $eq, the same phone number with or without calling code will match.

Matcher Details
$eq 
{
"mainPhone":{
"$eq":"+18187076189"
}
},
{
"mainPhone":{
"$eq":"8187076189"
}
},
{
"mainPhone":{
"!$eq":"9177076189"
}
}

Supports negation. Case insensitive.

$startsWith

Matches if the field starts with the argument value.

e.g., "8187076189" starts with "818"

{
"mainPhone":{
"$startsWith": "818"
}
}

Supports negation. Case insensitive.

$in

Matches if field value is a member of the argument list.

{
"mainPhone":{
"$in": [
"8185551616",
"9171112211"
]
}
}

Does not support negation. However, negation can be mimicked by using an $and matcher to negate individually over the desired values.

INTEGER, FLOAT, DATE, DATETIME, and TIME

These filter types are strictly ordered -- therefore, they support the following matchers:

  • Equals
  • Less Than / Less Than or Equal To
  • Greater Than / Greater Than or Equal To
Matcher Details
$eq

Equals

{
"ageRange.maxValue": {
"$eq": "80"
}
}

Supports negation.

$lt

Less than

{
"time.start": {
"$lt": "2018-08-28T05:56"
}
}
$gt

Greater than

{
"ageRange.maxValue": {
"$gt": "50"
}
}
$le

Less than or equal to

{
"ageRange.maxValue": {
"$le": "40"
}
}
$ge

Greater than or equal to

{
"time.end": {
"$ge":  "2018-08-28T05:56"
}
}
Combinations

While we do not support "between" in our filtering syntax, it is possible to combine multiple matchers for a result similar to an "and" operation:

{
"ageRange.maxValue : {
"$gt" : 10,
"$lt": 20
}
}

LIST OF TEXT

Any field that has a list of valid values and supports any of the previously mentioned filter types will also support the $contains matcher.

Matcher Details
$eq 
{
"c_myStringList": {
"$eq": "sample"
}
}

This filter will match if "sample" EXACTLY matches any string within c_myStringList.

Supports negation.

$eqAny 
{
"c_myStringList": {
"$eqAny": [
"sample1",
"sample2"
]
}
}

This filter will match if any one of "sample1" or "sample2" EXACTLY match a string within c_myStringList . The argument can have more than two strings.

Supports negation.

$eqAll 
{
"c_myStringList": {
"$eqAll": [
"sample1",
"sample2"
]
}
}

This filter will match if both "sample1" AND "sample2" EXACTLY match a string within c_myStringList. The argument can have more than two strings.

Supports negation.

$contains 
{
"c_myStringList":{
"$contains":"sample"
}
}

This filter will match if "sample" is contained in any string within c_myStringList.

Note that this matching is "left edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This is a sample", "Sample one", "Sample 2" but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAny 
{
"c_myStringList": {
"$containsAny": [
"sample1",
"sample2"
]
}
}

This filter will match if either "sample1" or "sample2" is contained in any string within c_myStringList. The argument list can have more than two strings.

Note that similar to $contains, the matching for $containsAny is "left edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This is a sample", "Sample one", "Sample 2" but not strings like "thisisasamplewithoutspaces".

Supports negation.

$containsAll 
{
"c_myStringList": {
"$containsAll": [
"sample1",
"sample2"
]
}
}

This filter will match if BOTH "sample1" and "sample2" are contained in strings within c_myStringList. The argument list can have more than two strings.

Note that similar to $contains, the matching for $containsAll is "left-edge n-gram", meaning the argument string must be the beginning of a token. The string "sample" will match strings like "This a sample", "Sample one", and "Sample 2", but not strings like "thisisasamplewithoutspaces".

Supports negation.

$startsWith 
{
"c_myStringList": {
"$startsWith":"sample"
}
}

This filter will match if any string within c_myStringList starts with "sample".

Does not supports negation. Case Insensitive.

LIST OF BOOLEAN, OPTION, PHONE, INTEGER, FLOAT, DATE, DATETIME, OR TIME

Matcher Details
$eq 
{
"c_myDateList": {
"$eq": "2019-01-01"
}
}

This filter will match if "2019-01-01" EXACTLY matches any date within c_myDateList.

Supports negation.

$eqAny 
{
"c_myIntegerList": {
"$eqAny": [1, 2]
}
}

This filter will match if 1 or 2 EXACTLY match any integer within c_myIntegerList. The argument list can have more than two elements.

Supports negation.

$eqAll 
{
"c_myStringList": {
"$eqAll": [
"sample1",
"sample2"
]
}
}

This filter will match if both "2019-01-01" AND "2019-01-02" EXACTLY match a date within c_myDateList. The argument list can have more than two elements.

Supports negation.

LIST OF STRUCT

Filtering on lists of struct types is a bit nuanced. Filtering can only be done on lists of structs of the SAME type. For example, if c_myStructList is a list of compound fields with the subfields age and name, then one can address the age properties of each field in c_myStructList as a flattened list of integers and filtering upon them. For example, the following filter:

{
"c_myStructList.age":{
"$eq": 20
}
}

will match if any field in the list has an age property equal to 20. Similarly, any filter that can be applied to lists of integers could be applied to age in this case ($eq, $eqAll, $eqAny).

HOURS

By filtering on an hours field, you can find which entities are open or closed at a specified time or during a certain time range. All of these filters also take an entity’s holiday hours and reopen date into account.

Matcher Details
$openAt 
{
"hours": {
"$openAt":
"2019-01-06T13:45"
}
}

This filter would match entities open at the specified time.

$closedAt 
{
"hours": {
"$closedAt:
"2019-01-06T13:45"
}
}
$openForAllOf 
{
"hours": {
"$openForAllOf": {
"start":
"2019-01-06T13:45",
"end":
"2019-01-06T15:00"
}
}
}

This filter would match only those entities that are open for the entire range between 2019-01-06T13:45 and 2019-01-06T15:00.

{
"hours": {
"$openForAllOf":
"2019-05-10"
}
}

This filter would match entities open for the entire 24 hour period on 2019-05-10.

You can also supply a year, a month, or an hour to filter for entities open for the entire year, month, or hour, respectively.

$openForAnyOf 
{
"hours": {
"$openForAnyOf": {
"start": "now",
"end": "now+2h"
}
}
}

This filter will match any entities that are open for at least a portion of the time range between now and two hours from now.

$closedForAllOf 
{
"hours": {
"$closedForAllOf": {
"start":
"2019-01-06T13:45",
"end":
"2019-01-06T15:00"
}
}
}

This filter will match only those entities that are closed for the entire given time range.

$closedForAnyOf 
{
"hours": {
"$closedForAnyOf": {
"start":
"2019-01-06T13:45",
"end":
"2019-01-06T15:00"
}
}
}

This filter will match any entities that are closed for at least a portion of the given time range.

Filtering by Dates and Times

Time zones

The filtering language supports searching both in local time and within a certain time zone. Searching in local time will simply ignore the time zone on the target entities, while providing one will convert the zone of your queried time to the zone of the target entities.

To search in local time, simply provide the date or time without any zone: 2019-06-07T15:30 or 2019-06-07.

To conduct a zoned search, provide the name of the time zone in brackets after the time, as it is shown in the tz database: 2019-06-07T15:30[America/New_York] or 2019-06-06[America/Phoenix].

Date and time types

In addition to searching with dates and datetimes, you can also query with years, months, and hours. For example, the filter:

{
"time.start": {
"$eq": "2018"
}
}

would match all start times in the year 2018. The same logic would apply for a month (2019-05), a date (2019-05-01), or an hour (2019-05-01T06).

These types also work with ordered searches. For example:

{
"time.start": {
"$lt": "2018"
}
}

would match start times before 2018 (i.e., anything in 2017 or before). On the other hand, the same query with a $le matcher would include anything in or before 2018.

"Now" and Date Math

Instead of providing a static date or time, you can also use now in place of any date time. When you do so, the system will calculate the time when the query is made and conduct a zoned search.

In order to search for a future or past time relative to now, you can use date math. For example, you can enter now+3h or now-1d, which would mean 3 hours from now and 1 day ago, respectively. You can also add and subtract minutes (m), months (M), and years (y).

It is also possible to add or subtract time from a static date or datetime. Simply add || between the static value and any addition or subtraction. For example, 2019-02-03||+1d would be the same as 2019-02-04.

You can also convert date and time types to other types. For example, to convert the datetime 2019-05-06T22:15 to a date, use 2019-05-06T22:15||/d. Doing so would yield the same result as using 2019-05-06. This method also works with now: now/d will give you today’s date without the time.

Filtering Across an Entity

It is possible to search for a specific text string across all fields of an entity by using the $anywhere matcher.

Matcher Details
$anywhere

Matches if the argument text appears anywhere in the entity (including subfields, structs, and lists)

{
"$anywhere": "hello"
}

This filter will match all entities that contain the string "hello" or strings that begin with "hello".

Examples

The following filter will match against entities that:

  • Are of type event (note that entity types can also be filtered by the entityTypes query parameter)
  • Have a name that starts with the text "Century"
  • Have a maximum age between 10 and 20
  • Have a minimum age between 5 and 7
  • Start after 7 PM (19:00) on August 28, 2018
{
"$and":[
{
"entityType":{
"$eq":"event"
}
},
{
"name":{
"$startsWith":"Century"
}
},
{
"ageRange.maxValue":{
"$gt":10,
"$lt":20
}
},
{
"ageRange.minValue":{
"$gt":5,
"$lt":7
}
},
{
"time.start":{
"$ge":"2018-08-28T19:00"
}
}
]
}
format
string >= 0 characters
Default: "markdown"

Present if and only if at least one field is of type "Legacy Rich Text."

Valid values:

  • markdown
  • html
  • none
languageCodes
string >= 0 characters

The comma-separated language codes corresponding to the languages of the profile that the user wishes to retrieve

limit
number multiple of 1 <= 50
Default: "10"

Number of results to return.

offset
number multiple of 1
Default: "0"

Number of results to skip. Used to page through results. Cannot be used together with pageToken.

For Live API requests, the offset cannot be higher than 9,950. For Knowledge API the maximum limit is only enforced if a filter and/or sortBy parameter are given.

pageToken
string >= 0 characters

If a response to a previous request contained the pageToken field, pass that field's value as the pageToken parameter to retrieve the next page of data.

sortBy
string >= 0 characters

A list of fields and sort directions to order results by. Each ordering in the list should be in the format {"field_name", "sort_direction"}, where sort_direction is either ASCENDING or DESCENDING.

For example, to order by name the sort order would be [{"name":"ASCENDING"}]. To order by name and then description, the sort order would be [{"name":"ASCENDING"},{"description":"ASCENDING"}].

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}
Feedback