loading

Entities: List

Retrieve a list of Entities within an account

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

A date in YYYYMMDD format.

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 "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.

resolvePlaceholders
boolean
Default: "false"

Optional parameter to resolve all embedded fields in a Location object response.

  • false: Location object returns placeholder labels, e.g., "Your [[CITY]] store"
  • true: Location object returns placeholder values, e.g., "Your Fairfax store"
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: Create

Create a new Entity

NOTE:

  • If the v parameter is before 20181129: the 201 response contains the created Entity's id
  • If the v parameter is on or after 20181129: the 201 response contains the created Entity in its entirety
path Parameters
accountId
required
string >= 0 characters
query Parameters
entityType
required
string >= 0 characters

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

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

OR the API name of a custom entity type.

v
required
string >= 0 characters

A date in YYYYMMDD format.

format
string >= 0 characters
Default: "markdown"

The formatting language used to parse rich text field values. Present and required if an only if the request contains a field with type "Rich Text."

Valid values:

  • markdown
  • html
stripUnsupportedFormats
boolean

Optional parameter to strip unsupported formats in rich text fields. When this parameter is included, the unsupported formats in rich text fields will be stripped and saved as plain text; otherwise if this parameter is not included, unsupported formats will return an error.

templateFields
string >= 0 characters

Comma-separated list of top-level fields to apply from the template. If provided, only the fields specified will be applied to the entity.

Ignored if templateId is not provided.

templateId
string >= 0 characters

The ID of the template to apply to the entity

NOTE: Some fields that are part of the provided template but not present in the API will be applied - e.g. Linked Accounts

Request Body schema: application/json

The entity to be created

EntityType
string

This is used only to filter the fields below and should NOT be included in any API calls. Specify the entity type in the query parameter described above.

object

Contains the metadata about the entity.

name
string [ 0 .. 5000 ] characters

Cannot Include:

  • HTML markup
  • a phone number
object

Contains the address of the entity (or where the entity is located)

Must be a valid address Cannot be a P.O. Box

If the entity is an event, either an address value or a linkedLocation value can be provided.

object

Contains the daily access hours, holiday access hours, and reopen date for the Entity.

Each day is represented by a sub-field of accessHours. (e.g. monday, tuesday, etc.) Open times can be specified per day through the openIntervals field and the isClosed flag. Similarly, holiday access hours are represented by the holidayHours sub-field. Setting the reopenDate sub-field indicates that the business is temporarily closed and will reopen on the specified date. SPECIAL CASES:

  • To indicate that an Entity is open 24 hours on a specific day, set start to 00:00 and end to 23:59 in openIntervals for that day.
  • To indicate that an Entity has split hours on specific day (e.g., open from 9:00 AM to 12:00 PM and again from 1:00 PM to 5:00 PM), supply up to two openIntervals values with non-overlapping sets of hours.
  • If you are providing openIntervals, you may not set isClosed to true for that day.
additionalHoursText
string [ 0 .. 255 ] characters

Additional information about hours that does not fit in hours (e.g., "Closed during the winter")

alternateNames
Array of strings unique

Other names for your business that you would like us to use when tracking your search performance

Array must be ordered.

Array may have a maximum of 3 elements.

Array item description:

Cannot Include:

  • HTML markup
alternatePhone
string >= 0 characters

Must be a valid phone number.

If the phone number's calling code is for a country other than the one given in the entity's countryCode, the phone number provided must contain the calling code (e.g., +44 in +442038083831). Otherwise, the calling code is optional.

alternateWebsites
Array of strings <uri> unique

Other websites for your business that we should search for when tracking your search performance

Array must be ordered.

Array may have a maximum of 3 elements.

Array item description:

Cannot Include:

  • common domain names, e.g., google.com, youtube.com, etc.
categoryIds
Array of strings

Yext Category IDs.

IDs must be valid and selectable (i.e., cannot be parent categories).

NOTE: The list of category IDs that you send us must be comprehensive. For example, if you send us a list of IDs that does not include IDs that you sent in your last update, Yext considers the missing categories to be deleted, and we remove them from your listings.

closed
boolean

Indicates whether the entity is closed

customKeywords
Array of strings unique

Additional keywords you would like us to use when tracking your search performance

Array must be ordered.

Array may have a maximum of 5 elements.

description
string [ 10 .. 15000 ] characters

A description of the entity

Cannot Include:

  • HTML markup
object

Coordinates where the map pin for the entity should be displayed, as provided by you

object

Contains the daily drive-through hours, holiday drive-through hours, and reopen date for the Entity.

Each day is represented by a sub-field of driveThroughHours. (e.g. monday, tuesday, etc.) Open times can be specified per day through the openIntervals field and the isClosed flag. Similarly, holiday drive-through hours are represented by the holidayHours sub-field. Setting the reopenDate sub-field indicates that the business is temporarily closed and will reopen on the specified date. SPECIAL CASES:

  • To indicate that an Entity is open 24 hours on a specific day, set start to 00:00 and end to 23:59 in openIntervals for that day.
  • To indicate that an Entity has split hours on specific day (e.g., open from 9:00 AM to 12:00 PM and again from 1:00 PM to 5:00 PM), supply up to two openIntervals values with non-overlapping sets of hours.
  • If you are providing openIntervals, you may not set isClosed to true for that day.
object

Coordinates of the drop-off area for the entity, as provided by you

object

Designates the Facebook Call-to-Action button text and value

Valid contents of value depends on the Call-to-Action's type:

  • NONE: (optional)
  • BOOK_NOW: URL
  • CALL_NOW: Phone number
  • CONTACT_US: URL
  • SEND_MESSAGE: Any string
  • USE_APP: URL
  • PLAY_GAME: URL
  • SHOP_NOW: URL
  • SIGN_UP: URL
  • WATCH_VIDEO: URL
  • SEND_EMAIL: Email address
  • LEARN_MORE: URL
  • PURCHASE_GIFT_CARDS: URL
  • ORDER_NOW: URL
  • FOLLOW_PAGE: Any string
object

The cover photo for the entity's Facebook profile

Displayed as a 851 x 315 pixel image

You may need a cover photo in order for your listing to appear on Facebook. Please check your listings tab to learn more.

Image must be at least 400 x 150 pixels

Image may be no more than 30000 x 30000 pixels

Supported Aspect Ratios:

  • 1 x 1
  • 4 x 3
  • 3 x 2
  • 5 x 3
  • 16 x 9
  • 3 x 1
  • 2 x 3
  • 5 x 7
  • 4 x 5
  • 4 x 1

NOTE: Maximum image size is 5mb after normalization and padding (if applicable). As well, there is a 6 second download limit from the image host.

facebookDescriptor
string [ 3 .. 75 ] characters

Location Descriptors are used for Enterprise businesses that sync Facebook listings using brand page location structure. The Location Descriptor is typically an additional geographic description (e.g. geomodifier) that will appear in parentheses after the name on the Facebook listing.

Cannot Include:

  • HTML markup
facebookName
string >= 0 characters

The name for this entity's Facebook profile. A separate name may be specified to send only to Facebook in order to comply with any specific Facebook rules or naming conventions.

facebookOverrideCity
string >= 0 characters

The city to be displayed on this entity's Facebook profile

facebookPageUrl
string >= 0 characters

URL for the entity's Facebook Page.

Valid formats:

  • facebook.com/profile.php?id=[numId]
  • facebook.com/group.php?gid=[numId]
  • facebook.com/groups/[numId]
  • facebook.com/[Name]
  • facebook.com/pages/[Name]/[numId]

where [Name] is a String and [numId] is an Integer

If you submit a URL that is not in one of the valid formats, it will be ignored. The success response will contain a warning message explaining why the URL wasn't stored in the system.

object

The profile picture for the entity's Facebook profile

You must have a profile picture in order for your listing to appear on Facebook.

Image must be at least 180 x 180 pixels

Image may be no more than 30000 x 30000 pixels

Supported Aspect Ratios:

  • 1 x 1

NOTE: Maximum image size is 5mb after normalization and padding (if applicable). As well, there is a 6 second download limit from the image host.

facebookVanityUrl
string [ 0 .. 50 ] characters

The username that appear's in the Facebook listing URL to help customers find and remember a brand’s Facebook page. The username is also be used for tagging the Facebook page in other users’ posts, and searching for the Facebook page.

fax
string >= 0 characters

Must be a valid fax number.

If the fax number's calling code is for a country other than the one given in the entity's countryCode, the fax number provided must contain the calling code (e.g., +44 in +442038083831). Otherwise, the calling code is optional.

object

Information about the entity's Featured Message

Array of objects unique

A list of questions that are frequently asked about this entity

Array must be ordered.

Array may have a maximum of 100 elements.

geomodifier
string >= 0 characters

Provides additional information on where the entity can be found (e.g., Times Square, Global Center Mall)

googleAttributes
object

The unique IDs of the entity's Google My Business keywords, as well as the unique IDs of any values selected for each keyword.

Valid keywords (e.g., has_drive_through, has_fitting_room, kitchen_in_room) are determined by the entity's primary category. A full list of keywords can be retrieved with the Google Fields: List endpoint.

Keyword values provide more details on how the keyword applies to the entity (e.g., if the keyword is has_drive_through, its values may be true or false).

  • If the v parameter is before 20181204: googleAttributes is formatted as a map of key-value pairs (e.g., [{ "id": "has_wheelchair_accessible_entrance", "values": [ "true" ] }])
  • If the v parameter is on or after 20181204: the contents are formatted as a list of objects (e.g., { "has_wheelchair_accessible_entrance": [ "true" ]})

NOTE: The latest Google Attributes are available via the Google Fields: List endpoint. Google Attributes are managed by Google and are subject to change without notice. To prevent errors, make sure your API implementation is not dependent on the presence of specific attributes.

object

The cover photo for the entity's Google profile

Image must be at least 250 x 250 pixels

googleMyBusinessLabels
Array of strings unique

Google My Business Labels help users organize their locations into groups within GMB.

Array must be ordered.

Array may have a maximum of 10 elements.

Array item description:

Cannot Include:

  • HTML markup
googlePlaceId
string >= 0 characters

The unique identifier of this entity on Google Maps.

object

The profile photo for the entity's Google profile

Image must be at least 250 x 250 pixels

Image may be no more than 500 x 500 pixels

Supported Aspect Ratios:

  • 1 x 1

NOTE: Maximum image size is 5mb after normalization and padding (if applicable). As well, there is a 6 second download limit from the image host.

googleWebsiteOverride
string <uri> >= 0 characters

The URL you would like to submit to Google My Business in place of the one given in websiteUrl (if applicable).

For example, if you want to analyze the traffic driven by your Google listings separately from other traffic, enter the alternate URL that you will use for tracking in this field.

holidayHoursConversationEnabled
boolean

Indicates whether holiday-hour confirmation alerts are enabled for the Yext Knowledge Assistant for this entity

object

Contains the daily hours, holiday hours, and reopen date for the Entity.

Each day is represented by a sub-field of hours. (e.g. monday, tuesday, etc.) Open times can be specified per day through the openIntervals field and the isClosed flag. Similarly, holiday hours are represented by the holidayHours sub-field. Setting the reopenDate sub-field indicates that the business is temporarily closed and will reopen on the specified date. SPECIAL CASES:

  • To indicate that an Entity is open 24 hours on a specific day, set start to 00:00 and end to 23:59 in openIntervals for that day.
  • To indicate that an Entity has split hours on specific day (e.g., open from 9:00 AM to 12:00 PM and again from 1:00 PM to 5:00 PM), supply up to two openIntervals values with non-overlapping sets of hours.
  • If you are providing openIntervals, you may not set isClosed to true for that day.
impressum
string [ 0 .. 2000 ] characters

A statement of the ownership and authorship of a document. Individuals or organizations based in many German-speaking countries are required by law to include an Impressum in published media.

isoRegionCode
string >= 0 characters

The ISO 3166-2 region code for the entity

Yext will determine the entity's code and update isoRegionCode with that value. If Yext is unable to determine the code for the entity, the entity'ss ISO 3166-1 alpha-2 country code will be used.

keywords
Array of strings unique

Keywords that describe the entity.

All strings must be non-empty when trimmed of whitespace.

Array must be ordered.

Array may have a maximum of 100 elements.

Array item description:

Cannot Include:

  • HTML markup
labels
Array of strings

The IDs of the entity labels that have been added to this entity. Entity labels help you identify entities that share a certain characteristic; they do not appear on your entity's listings.

NOTE: You can only add labels that have already been created via our web interface. Currently, it is not possible to create new labels via the API.

landingPageUrl
string <uri> >= 0 characters

The URL of this entity's Landing Page that was created with Yext Pages

localPhone
string >= 0 characters

Must be a valid, non-toll-free phone number, based on the country specified in address.region. Phone numbers for US entities must contain 10 digits.

locatedIn
string

For atms, the external ID of the entity that the atm is installed in. The entity must be in the same business account as the atm.

locationType
string
Enum: "LOCATION" "HEALTHCARE_FACILITY" "HEALTHCARE_PROFESSIONAL" "ATM" "RESTAURANT" "HOTEL"

Indicates the entity's type, if it is not an event

object

An image of the entity's logo

Supported Aspect Ratios:

  • 1 x 1

NOTE: Maximum image size is 5mb after normalization and padding (if applicable). As well, there is a 6 second download limit from the image host.

mainPhone
string >= 0 characters

The main phone number of the entity's point of contact

Must be a valid phone number.

If the phone number's calling code is for a country other than the one given in the entity's countryCode, the phone number provided must contain the calling code (e.g., +44 in +442038083831). Otherwise, the calling code is optional.

mobilePhone
string >= 0 characters

Must be a valid phone number.

If the phone number's calling code is for a country other than the one given in the entity's countryCode, the phone number provided must contain the calling code (e.g., +44 in +442038083831). Otherwise, the calling code is optional.

nudgeEnabled
boolean

Indicates whether Knowledge Nudge is enabled for the Yext Knowledge Assistant for this entity

object

Coordinates of where consumers can be picked up at the entity, as provided by you

priceRange
string
Enum: "UNSPECIFIED" "ONE" "TWO" "THREE" "FOUR"

he typical price of products sold by this location, on a scale of 1 (low) to 4 (high)

primaryConversationContact
string >= 0 characters

ID of the user who is the primary Knowledge Assistant contact for the entity

questionsAndAnswers
boolean

Indicates whether Yext Knowledge Assistant question-and-answer conversations are enabled for this entity

Array of objects unique

Information about the competitors whose search performance you would like to compare to your own

Array must be ordered.

Array may have a maximum of 5 elements.

rankTrackingEnabled
boolean

Indicates whether Rank Tracking is enabled

rankTrackingFrequency
string
Enum: "WEEKLY" "MONTHLY" "QUARTERLY"

How often we send search queries to track your search performance

rankTrackingQueryTemplates
Array of strings unique
Items Enum: "KEYWORD" "KEYWORD_ZIP" "KEYWORD_CITY" "KEYWORD_IN_CITY" "KEYWORD_NEAR_ME" "KEYWORD_CITY_STATE"

The ways in which your keywords will be arranged in the search queries we use to track your performance

Array must have a minimum of 2 elements.

Array may have a maximum of 4 elements.

rankTrackingSites
Array of strings unique
Items Enum: "GOOGLE_DESKTOP" "GOOGLE_MOBILE" "BING_DESKTOP" "BING_MOBILE" "YAHOO_DESKTOP" "YAHOO_MOBILE"

The search engines that we will use to track your performance

reviewResponseConversationEnabled
boolean

Indicates whether Yext Knowledge Assistant review-response conversations are enabled for this entity

object

Destination coordinates to use for driving directions to the entity, as provided by you

timezone
string >= 0 characters

The timezone of the entity, in the standard IANA time zone database format (tz database). e.g. "America/New_York"

tollFreePhone
string >= 0 characters

Must be a valid phone number.

If the phone number's calling code is for a country other than the one given in the entity's countryCode, the phone number provided must contain the calling code (e.g., +44 in +442038083831). Otherwise, the calling code is optional.

ttyPhone
string >= 0 characters

Must be a valid phone number.

If the phone number's calling code is for a country other than the one given in the entity's countryCode, the phone number provided must contain the calling code (e.g., +44 in +442038083831). Otherwise, the calling code is optional.

object

Destination coordinates to use for walking directions to the entity, as provided by you

object

Information about the website for this entity

Responses

Request samples

Content type
application/json
Example
{
  • "EntityType": "atm",
  • "meta": {
    },
  • "name": "string",
  • "address": {
    },
  • "accessHours": {
    },
  • "additionalHoursText": "string",
  • "alternateNames": [
    ],
  • "alternatePhone": "string",
  • "alternateWebsites": [],
  • "categoryIds": [
    ],
  • "closed": true,
  • "customKeywords": [
    ],
  • "description": "stringstri",
  • "displayCoordinate": {
    },
  • "driveThroughHours": {
    },
  • "dropoffCoordinate": {
    },
  • "facebookCallToAction": {
    },
  • "facebookCoverPhoto": {},
  • "facebookDescriptor": "string",
  • "facebookName": "string",
  • "facebookOverrideCity": "string",
  • "facebookPageUrl": "string",
  • "facebookProfilePhoto": {},
  • "facebookVanityUrl": "string",
  • "fax": "string",
  • "featuredMessage": {},
  • "frequentlyAskedQuestions": [
    ],
  • "geomodifier": "string",
  • "googleAttributes": { },
  • "googleCoverPhoto": {},
  • "googleMyBusinessLabels": [
    ],
  • "googlePlaceId": "string",
  • "googleProfilePhoto": {},
  • "googleWebsiteOverride": "http://example.com",
  • "holidayHoursConversationEnabled": true,
  • "hours": {
    },
  • "impressum": "string",
  • "isoRegionCode": "string",
  • "keywords": [
    ],
  • "labels": [
    ],
  • "landingPageUrl": "http://example.com",
  • "localPhone": "string",
  • "locatedIn": "string",
  • "locationType": "LOCATION",
  • "logo": {},
  • "mainPhone": "string",
  • "mobilePhone": "string",
  • "nudgeEnabled": true,
  • "pickupCoordinate": {
    },
  • "priceRange": "UNSPECIFIED",
  • "primaryConversationContact": "string",
  • "questionsAndAnswers": true,
  • "rankTrackingCompetitors": [],
  • "rankTrackingEnabled": true,
  • "rankTrackingFrequency": "WEEKLY",
  • "rankTrackingQueryTemplates": [
    ],
  • "rankTrackingSites": [
    ],
  • "reviewResponseConversationEnabled": true,
  • "routableCoordinate": {
    },
  • "timezone": "string",
  • "tollFreePhone": "string",
  • "ttyPhone": "string",
  • "walkableCoordinate": {
    },
  • "websiteUrl": {}
}

Response samples

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