Locations (Legacy): List

Get multiple Locations (primary profiles only).

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

limit
integer <= 50
Default: 10

Number of results to return.

offset
integer
Default: 0

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

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"
pageToken
string

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

Responses

Response samples

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

Locations (Legacy): Create

Create a new Location.

Required fields

  • locationName
  • address
  • city
  • state
  • zip

Optional fields that trigger warnings

Submitting invalid values for certain optional fields will not trigger an error response. Instead, the success response will contain warning messages explaining why the invalid optional values were not stored in the system. The fields that generate warning messages are:

  • logo
  • photos
  • twitterHandle
  • facebookPageUrl
  • languages
path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

Request Body schema: application/json
id
string <= 50 characters

Primary key. Unique alphanumeric (Latin-1) ID assigned by the Customer.

accountId
string <= 50 characters

Must refer to an account.id that already exists.

locationType
string
Enum: "LOCATION" "HEALTHCARE_PROFESSIONAL" "HEALTHCARE_FACILITY" "RESTAURANT" "ATM"
locationName
string <= 100 characters

Cannot include:

  • inappropriate language
  • HTML markup or entities
  • a URL or domain name
  • a phone number
  • control characters ([\x00-\x1F\x7F])

Should be in appropriate letter case (e.g., not in all capital letters)

firstName
string

The first name of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

middleName
string

The middle name of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

lastName
string

The last name of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

officeName
string

The name of the office where the healthcare professional works, if different from locationName

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

gender
string
Enum: "FEMALE" "F" "MALE" "M" "UNSPECIFIED"

The gender of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

npi
string

The National Provider Identifier (NPI) of the healthcare provider

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL or HEALTHCARE_FACILITY.

address
string <= 255 characters

Must be a valid address

Cannot be a P.O. Box

address2
string <= 255 characters

Cannot be a P.O. Box

suppressAddress
boolean

If true, do not show street address on listings. Defaults to false.

displayAddress
string <= 255 characters

Provides additional information to help consumers get to the location. This string appears along with the location's address (e.g., In Menlo Mall, 3rd Floor).

It may also be used in conjunction with a hidden address (i.e., when suppressAddress is true) to give consumers information about where the location is found (e.g., Servicing the New York area).

Cannot be a P.O. Box

city
string <= 80 characters
state
string <= 80 characters

For US locations, the two-character code of the location’s state, or DC for the District of Columbia For non-US locations, the name of the location’s province / region / state

sublocality
string <= 255 characters

The name of the location's sublocality.

zip
string <= 10 characters

The location's postal code. For US locations, this field contains the five- or nine-digit ZIP code (the hyphen is optional). Validations are only done on zip if countryCode is US.

countryCode
string <= 2 characters

The two-character ISO 3166-1 code of the location's country or region. If omitted, US is used.

object

Area that is served by this location. It may be specified as a radius from the location's address or as a list of cities and/or postal codes.

Only for Google Business Profile: Currently, serviceArea is only supported by Google Business Profile and will not affect your listings on other sites.

phone
string

Must be a valid phone number.

isPhoneTracked
boolean

Set to true if the number listed in phone is a tracked phone number.

NOTE: When updating isPhoneTracked, you must provide a value for phone in the same request.

localPhone
string

Must be a valid, non-toll-free phone number.

Required if:

  • isPhoneTracked is true and the non-tracked number is a toll-free number, OR
  • isPhoneTracked is false and phone is a toll-free number
alternatePhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

faxPhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

mobilePhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

tollFreePhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

ttyPhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

categoryIds
Array of strings

Yext Category IDs. A Location must have at least one and at most 10 Categories.

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.

featuredMessage
string <= 50 characters

The Featured Message. Default: Call today!

Cannot include:

  • inappropriate language
  • HTML markup
  • a URL or domain name
  • a phone number
  • control characters ([\x00-\x1F\x7F])
  • insufficient spacing

If you submit a Featured Message that contains profanity or more than 50 characters, it will be ignored. The success response will contain a warning message explaining why your Featured Message wasn't stored in the system.

featuredMessageUrl
string <= 255 characters

Valid URL to which the Featured Message is linked

websiteUrl
string <= 255 characters

The URL of the location's website. This URL will be shown on your listings unless you specify a value for displayWebsiteUrl.

Must be a valid URL and is required whenever displayWebsiteUrl is specified.

displayWebsiteUrl
string <= 255 characters

The URL that is shown on your listings in place of websiteUrl. You can use displayWebsiteUrl to display a short, memorable web address that redirects consumers to the URL given in websiteUrl.

Must be a valid URL and be specified along with websiteUrl.

reservationUrl
string <= 255 characters

A valid URL used for reservations at this location.

displayReservationUrl
string <= 255 characters

The URL that is shown on your listings in place of reservationUrl. You can use displayReservationUrl to display a short, memorable web address that redirects consumers to the URL given in reservationUrl.

Must be a valid URL and be specified along with reservationUrl.

menuUrl
string <= 255 characters

The URL of the location's menu.

displayMenuUrl
string <= 255 characters

The URL that is shown on your listings in place of menuUrl. You can use displayMenuUrl to display a short, memorable web address that redirects consumers to the URL given in menuUrl.

Must be a valid URL and be specified along with menuUrl.

orderUrl
string <= 255 characters

The URL used to place orders that will be fulfilled at the location.

displayOrderUrl
string <= 255 characters

The URL that is shown on your listings in place of orderUrl. You can use displayOrderUrl to display a short, memorable web address that redirects consumers to the URL given in orderUrl.

Must be a valid URL and be specified along with orderUrl.

hours
string <= 255 characters

Hours should be submitted as a comma-separated list of days, where each day's hours are specified as follows:

d:oh:om:ch:cm

  • d = day of the week –
    • 1 – Sunday
    • 2 – Monday
    • 3 – Tuesday
    • 4 – Wednesday
    • 5 – Thursday
    • 6 – Friday
    • 7 – Saturday
  • oh:om = opening time in 24-hour format
  • ch:cm = closing time in 24-hour format

Times with single-digit hours (e.g., 9 AM) can be submitted with or without a leading zero (9:00 or 09:00).

Example: open 9 AM to 5 PM Monday and Tuesday, open 10 AM to 4 PM on Saturday – 2:9:00:17:00,3:9:00:17:00,7:10:00:16:00

SPECIAL CASES:

  • To indicate that a location is open 24 hours on a specific day, set 00:00 as both the opening and closing time for that day.
    • Example: open all day on Saturdays – 7:00:00:00:00
  • To indicate that a location is closed on a specific day, omit that day from the list or set it as closed ("closed" is not case sensitive).
    • Example: closed on Sundays – 1:closed
    • NOTE: If a location is closed seven days a week, set at least one day to closed. Otherwise, hours is an empty string, and we assume you are not submitting hours information for that location.
  • To indicate that a location has split hours on a specific day, submit a set of hours for each block of time the location is open.
    • Example: open from 9:00 AM to 12:00 PM and again from 1:00 PM to 5:00 PM on Mondays – 2:9:00:12:00,2:13:00:17:00

NOTE: To set hours for specific days of the year rather than days of the week, use holidayHours.

additionalHoursText
string <= 255 characters

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

Array of objects

Holiday hours for this location.

NOTE: hours must be set in order for holidayHours to appear on your listings)

description
string [ 10 .. 5000 ] characters
conditionsTreated
Array of strings

A list of the conditions treated by the healthcare provider

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL or HEALTHCARE_FACILITY.

certifications
Array of strings

A list of the certifications held by the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

Array of objects

A list of the types of education and training completed by the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

degrees
Array of strings

A list of the degrees earned by the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

Valid values:

  • ANP (Adult Nurse Practitioner)
  • APN (Advanced Practice Nurse)
  • APRN (Advanced Practice Registered Nurse)
  • ARNP (Advanced Registered Nurse Practitioner)
  • CNM (Certified Nurse Midwife)
  • CNP (Certified Nurse Practitioner)
  • CNS (Clinical Nurse Specialist)
  • CPNP (Certified Pediatric Nurse Practitioner)
  • CRNA (Certified Registered Nurse Anesthetist)
  • CRNP (Certified Registered Nurse Practitioner)
  • DC (Doctor of Chiropractic)
  • DDS (Doctor of Dental Surgery)
  • DMD (Doctor of Dental Medicine)
  • DO (Doctor of Osteopathy)
  • DPM (Doctor of Podiatric Medicine)
  • DVM (Doctor of Veterinary Medicine)
  • FNP (Family Nurse Practitioner)
  • GNP (Geriatric Nurse Practitioner)
  • LAC (Licensed Acupuncturist)
  • LPN (Licensed Practical Nurse)
  • MD (Medical Doctor)
  • ND (Naturopathic Doctor)
  • NP (Nurse Practitioner)
  • OD (Doctor of Optometry)
  • PA (Physician Assistant)
  • PAC (Physician Assistant Certified)
  • PHARMD (Doctor of Pharmacy)
  • PHD (Doctor of Philosophy)
  • PNP (Pediatric Nurse Practitioner)
  • VMD (Veterinary Medical Doctor)
  • WHNP (Womens Health Nurse Practitioner)
admittingHospitals
Array of strings

A list of hospitals where the healthcare professional admits patients

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

acceptingNewPatients
boolean

Indicates whether the healthcare provider is accepting new patients

Default is true

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL or HEALTHCARE_FACILITY.

object

A set of field-value pairs indicating whether the location is closed and, if it is closed, the date of its closing.

NOTE: This field does not appear in the GET response unless it has been explicitly set in a PUT request.

paymentOptions
Array of strings

The payment methods accepted at this location

Valid elements depend on the location's country. For US locations, valid elements are:

  • AMERICANEXPRESS
  • CASH
  • CHECK
  • DINERSCLUB
  • DISCOVER
  • FINANCING
  • INVOICE
  • MASTERCARD
  • TRAVELERSCHECK
  • VISA
  • ANDROIDPAY
  • APPLEPAY
  • SAMSUNGPAY
  • BITCOIN
  • PAYPAL
insuranceAccepted
Array of strings

A list of insurance policies accepted by the healthcare provider

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

object
Array of objects

Up to 50 Photos.

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

object

A portrait of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

videoUrls
Array of strings[ items <= 255 characters ]

Valid YouTube URLs for embedding a video on some publisher sites.

NOTE: Currently, only the first URL in the Array appears in your listings.

instagramHandle
string

Valid Instagram username for the location (e.g., NewCityFiat (without the leading "@"))

twitterHandle
string <= 15 characters

Valid Twitter handle for the location (e.g., JohnSmith (without the leading '@')). If you submit an invalid Twitter handle, it will be ignored. The success response will contain a warning message explaining why your Twitter handle wasn't stored in the system.

googleWebsiteOverride
string <= 255 characters

The URL you would like to submit to Google Business Profile 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.

object

The cover photo for your business's Google profile

NOTE: Your cover photo must meet all of the following requirements:

  • have a 16:9 aspect ratio
  • be at least 480 x 270 pixels
  • be no more than 2120 x 1192 pixels
object

The profile photo for your business's Google profile

NOTE: Your profile picture must meet all of the following requirements:

  • be a square
  • be at least 250 x 250 pixels
Array of objects

The Google Business Profile attributes for this location.

facebookPageUrl
string <= 255 characters

URL for the location'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.

NOTE: This value is automatically set to the location's Facebook Page URL. You can only manually set facebookPageUrl if the location meets one of the following criteria:

  • It is not subscribed to a Listings package that contains Facebook.
  • It is opted out of Facebook.
object

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

object

The cover photo for your business's Facebook profile

Displayed as a 851 x 315 pixel image

You must have a cover photo in order for your listing to appear on Facebook.

NOTE: Your cover photo must be at least 400 pixels wide.

object

The profile picture for your business's Facebook profile

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

NOTE: Your profile picture must be larger than 180 x 180 pixels.

uberLinkType
string
Enum: "LINK" "BUTTON"

Indicates whether the embedded Uber link for this location appears as text or a button

When consumers click on this link on a mobile device, the Uber app (if installed) will open with your location set as the trip destination. If the Uber app is not installed, the consumer will be prompted to download it.

uberLinkText
string <= 100 characters

The text of the embedded Uber link

Default is "Ride there with Uber".

NOTE: This field is only available if uberLinkType is LINK.

uberTripBrandingText
string <= 28 characters

The text of the call-to-action that will appear in the Uber app during a trip to your location (e.g., Check out our menu!)

NOTE: If a value for uberTripBrandingText is provided, values must also be provided for uberTripBrandingUrl and uberTripBrandingDescription.

uberTripBrandingUrl
string

The URL that the consumer will be redirected to when tapping on the call-to-action in the Uber app during a trip to your location.

NOTE: If a value for uberTripBrandingUrl is provided, values must also be provided for uberTripBrandingText and uberTripBrandingDescription.

uberTripBrandingDescription
string <= 150 characters

A longer description that will appear near the call-to-action in the Uber app during a trip to your location.

NOTE: If a value for uberTripBrandingDescription is provided, values must also be provided for uberTripBrandingText and uberTripBrandingUrl.

yearEstablished
string <= 4 characters

The year that this location was opened, not the number of years it was open

Minimum of 1000, maximum of current year + 10.

displayLat
number <double>

Latitude where the map pin should be displayed, as provided by you

Between -90.0 and 90.0, inclusive

displayLng
number <double>

Longitude where the map pin should be displayed, as provided by you

Between -180.0 and 180.0, inclusive

routableLat
number <double>

Latitude to use for driving directions to the location, as provided by you

Between -90.0 and 90.0, inclusive

routableLng
number <double>

Longitude to use for driving directions to the location, as provided by you

Between -180.0 and 180.0, inclusive

walkableLat
number <double>

Latitude to use for walking directions to the location, as provided by you

Between -90.0 and 90.0, inclusive

walkableLng
number <double>

Longitude to use for walking directions to the location, as provided by you

Between -180.0 and 180.0, inclusive

pickupLat
number <double>

Latitude to use for pickup spot for the location, as provided by you

Between -90.0 and 90.0, inclusive

pickupLng
number <double>

Longitude to use for pickup spot for the location, as provided by you

Between -180.0 and 180.0, inclusive

dropoffLat
number <double>

Latitude to use for drop off spot for the location, as provided by you

Between -90.0 and 90.0, inclusive

dropoffLng
number <double>

Longitude to use for drop off spot for the location, as provided by you

Between -180.0 and 180.0, inclusive

emails
Array of strings[ items <= 255 characters ]

Up to five emails addresses for reaching this location

Must be valid email addresses

specialities
Array of strings[ items <= 100 characters ]

Up to 100 specialities (e.g., for food and dining: Chicago style)

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

associations
Array of strings[ items <= 100 characters ]

Up to 100 association memberships relevant to the location (e.g., New York Doctors Association)

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

products
Array of strings[ items <= 100 characters ]

Up to 100 products sold at this location

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

services
Array of strings[ items <= 100 characters ]

Up to 100 services offered at this location

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

brands
Array of strings[ items <= 100 characters ]

Up to 100 brands sold by this location

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

language
string <= 10 characters

Language code of the language in which this location's information is provided. This language is considered the Location's primary language in our system.

If you would like to provide your Location data in more than one language, you can create a Language Profile for each of these additional (alternate) languages.

languages
Array of strings[ items <= 100 characters ]

Up to 100 languages spoken at this location.

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

keywords
Array of strings[ items <= 100 characters ]

Up to 100 keywords may be provided

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

menusLabel
string

Label to be used for this location’s Menus. This label will appear on your location's listings.

menuIds
Array of strings

IDs of Menus associated with this location.

bioListsLabel
string

Label to be used for this location’s Bio lists. This label will appear on your location's listings.

bioListIds
Array of strings

IDs of Bio lists associated with this location.

productListsLabel
string

Label to be used for this location’s Product & Services lists. This label will appear on your location's listings.

productListIds
Array of strings

IDs of Product lists associated with this location.

eventListsLabel
string

Label to be used for this location’s Event lists. This label will appear on your location's listings.

eventListIds
Array of strings

IDs of Event lists associated with this location.

folderId
string

The folder that this location is in. Must be a valid, existing Yext Folder ID

labelIds
Array of strings

The IDs of the location labels that have been added to this location. Location labels help you identify locations that share a certain characteristic; they do not appear on your location'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.

In Locations: Update requests:

  • If the v parameter is before 20180223: setting the value of labelIds to an empty array has no effect on the current value
  • If the v parameter is 20180223 or after: setting the value of labelIds to an empty array deletes the current value
object

A set of key-value pairs indicating the location's custom fields and their values. The keys are the ids of the custom fields, and the values are the fields' contents for this location.

To retrieve a list of custom fields for your account, use the Custom Fields: List endpoint.

If a field's type is SINGLE_OPTION or MULTI_OPTION, the option or options that apply to this location must be represented by their **key**s.

Examples of each type of custom field:

  • BOOLEAN:
    • { "9662": "true" }
  • DAILY_TIMES:
    • { "10012": { "dailyTimes": "2:7:00,3:7:00,4:7:00,5:7:00,6:7:00,7:7:00,1:7:00" } }
  • DATE:
    • { "7066": "2016-10-12" }
  • GALLERY:
    • { "7070": [ { "url": "http://a.mktgcdn.com/p/ounkg7aq6Oy029-sRf4CIH64/128x128.jpg" }, { "url": "http://a.mktgcdn.com/p/YkQGqxK8jFBqOlailQ9QIBsgs/1.0000/316x316.png" } ] }
  • HOURS:
    • { "10011": { "hours": "1:7:00:20:00,2:7:00:20:00,3:7:00:20:00,4:7:00:20:00,5:7:00:20:00,6:7:00:20:00,7:7:00:20:00", "additionalHoursText": "Also by appointment" }
  • LOCATION_LIST:
    • { "8098" : [ "locationId1", "locationId2" ] }
  • MULTILINE_TEXT (up to 4,000 characters):
    • { "1592": "Take Route 13 south. Pass Riverrun Reservoir. At the traffic light before the post office, turn right off of Route 13. Pass the library and community center on your right and then pass a diner on your left. Cross over the bridge and at the third intersection, turn left onto Jones Street. We are located on the right side in the middle of the block." }
  • MULTI_OPTION:
    • { "7068": ["2614", "2615"] } ("2614" and "2615" are the options' **key**s)
  • NUMBER:
    • { "7078": "123" }
  • PHOTO:
    • { "7071": { "url": "http://a.mktgcdn.com/p/bRtQXQZP2kEzgy2C8/800x800.jpg", "description": "New storefront", "details": "A picture of the new storefront" } }
    • { "7071": null } (This setting will clear the existing value of the Photo custom field.)
  • SINGLE_OPTION:
    • { "7069": "2617" } ("2617" is the option's key)
  • TEXT (up to 255 characters):
    • { "6157": "Buy One, Get One 50% Off" }
  • TEXT_LIST:
    • { "7072": [ "Item 1", "Item 2", "Item 3" ] }
  • URL:
    • { "9381": "http://www.location.example.com" }
  • VIDEO:
    • { "7077": { "url": "http://www.youtube.com/watch?v=6KQPho" } }
  • VIDEO_GALLERY:
    • { "8452": [ { "url": "http://www.youtube.com/watch?v=B1EC1U" }, { "url": "http://www.youtube.com/watch?v=SkEtnN" } ] }
intelligentSearchTrackingEnabled
boolean

Indicates whether Intelligent Search Tracker is enabled.

The Intelligent Search Tracker allows you to understand your performance in local search.

intelligentSearchTrackingFrequency
string
Enum: "WEEKLY" "MONTHLY" "QUARTERLY"

How often we send search queries to track your search performance.

locationKeywords
Array of strings
Items Enum: "NAME" "PRIMARY_CATEGORY"

Keywords that we will use to track your search performance. These keywords are based on the location information you've stored in our system.

customKeywords
Array of strings

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

queryTemplates
Array of strings
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

alternateNames
Array of strings

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

alternateWebsites
Array of strings

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

Array of objects

The names and websites of the competitors whose search performance you would like to compare to your own

trackingSites
Array of strings
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

isClusterPrimary
boolean

Indicates whether the location is the primary location in its group

attire
string
Enum: "UNSPECIFIED" "DRESSY" "CASUAL" "FORMAL"

The formality of clothing typically worn at this location

NOTE: This field is only available to locations whose locationType is RESTAURANT.

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

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

NOTE: This field is only available to locations whose locationType is RESTAURANT.

mealsServed
Array of strings

Types of meals served at this location

NOTE: This field is only available to locations whose locationType is RESTAURANT.

Valid values:

  • BREAKFAST
  • LUNCH
  • BRUNCH
  • HAPPY_HOUR
  • LATE_NIGHT
locatedIn
string

For ATMs, the external ID of the location that the ATM is installed in. The location must be in the same business account as the ATM.

NOTE: This field is only available to locations whose locationType is ATM.

primaryContact
string

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

reviewResponseConversationEnabled
boolean

Indicates whether or not review response conversations are enabled for the Yext Knowledge Assistant

holidayHoursConfirmationEnabled
boolean

Indicates whether or not holiday hour confirmation alerts are enabled for the Yext Knowledge Assistant

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "accountId": "string",
  • "locationType": "LOCATION",
  • "locationName": "string",
  • "firstName": "string",
  • "middleName": "string",
  • "lastName": "string",
  • "officeName": "string",
  • "gender": "FEMALE",
  • "npi": "string",
  • "address": "string",
  • "address2": "string",
  • "suppressAddress": true,
  • "displayAddress": "string",
  • "city": "string",
  • "state": "string",
  • "sublocality": "string",
  • "zip": "string",
  • "countryCode": "st",
  • "serviceArea": {
    },
  • "phone": "string",
  • "isPhoneTracked": true,
  • "localPhone": "string",
  • "alternatePhone": "string",
  • "faxPhone": "string",
  • "mobilePhone": "string",
  • "tollFreePhone": "string",
  • "ttyPhone": "string",
  • "categoryIds": [
    ],
  • "featuredMessage": "string",
  • "featuredMessageUrl": "string",
  • "websiteUrl": "string",
  • "displayWebsiteUrl": "string",
  • "reservationUrl": "string",
  • "displayReservationUrl": "string",
  • "menuUrl": "string",
  • "displayMenuUrl": "string",
  • "orderUrl": "string",
  • "displayOrderUrl": "string",
  • "hours": "string",
  • "additionalHoursText": "string",
  • "holidayHours": [
    ],
  • "description": "stringstri",
  • "conditionsTreated": [
    ],
  • "certifications": [
    ],
  • "educationList": [
    ],
  • "degrees": [
    ],
  • "admittingHospitals": [
    ],
  • "acceptingNewPatients": true,
  • "closed": {
    },
  • "paymentOptions": [
    ],
  • "insuranceAccepted": [
    ],
  • "logo": {
    },
  • "photos": [
    ],
  • "headshot": {
    },
  • "videoUrls": [
    ],
  • "instagramHandle": "string",
  • "twitterHandle": "string",
  • "googleWebsiteOverride": "string",
  • "googleCoverPhoto": {
    },
  • "googleProfilePhoto": {
    },
  • "googleAttributes": [
    ],
  • "facebookPageUrl": "string",
  • "facebookCallToAction": {
    },
  • "facebookCoverPhoto": {
    },
  • "facebookProfilePicture": {
    },
  • "uberLinkType": "LINK",
  • "uberLinkText": "string",
  • "uberTripBrandingText": "string",
  • "uberTripBrandingUrl": "string",
  • "uberTripBrandingDescription": "string",
  • "yearEstablished": "stri",
  • "displayLat": 0,
  • "displayLng": 0,
  • "routableLat": 0,
  • "routableLng": 0,
  • "walkableLat": 0,
  • "walkableLng": 0,
  • "pickupLat": 0,
  • "pickupLng": 0,
  • "dropoffLat": 0,
  • "dropoffLng": 0,
  • "emails": [
    ],
  • "specialities": [
    ],
  • "associations": [
    ],
  • "products": [
    ],
  • "services": [
    ],
  • "brands": [
    ],
  • "language": "string",
  • "languages": [
    ],
  • "keywords": [
    ],
  • "menusLabel": "string",
  • "menuIds": [
    ],
  • "bioListsLabel": "string",
  • "bioListIds": [
    ],
  • "productListsLabel": "string",
  • "productListIds": [
    ],
  • "eventListsLabel": "string",
  • "eventListIds": [
    ],
  • "folderId": "string",
  • "labelIds": [
    ],
  • "customFields": {
    },
  • "intelligentSearchTrackingEnabled": true,
  • "intelligentSearchTrackingFrequency": "WEEKLY",
  • "locationKeywords": [
    ],
  • "customKeywords": [
    ],
  • "queryTemplates": [
    ],
  • "alternateNames": [
    ],
  • "alternateWebsites": [
    ],
  • "competitors": [
    ],
  • "trackingSites": [
    ],
  • "isClusterPrimary": true,
  • "attire": "UNSPECIFIED",
  • "priceRange": "UNSPECIFIED",
  • "mealsServed": [
    ],
  • "locatedIn": "string",
  • "primaryContact": "string",
  • "reviewResponseConversationEnabled": true,
  • "holidayHoursConfirmationEnabled": true
}

Response samples

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

Locations (Legacy): Search

Get multiple Locations (primary profiles only) that match provided filters.

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

limit
integer <= 50
Default: 10

Number of results to return.

offset
integer <= 9950
Default: 0

Number of results to skip. Used to page through results.

filters
string

A set of filters that is applied to the set of locations that would otherwise be returned. Should be provided as a URL-encoded string containing a JSON array. The array should have one or more filter objects defined. All filter objects will apply as an intersection (i.e., AND). Field names reference Location fields, as well as custom fields using the format custom###, where "###" is the custom field’s id.

For example, to provide a filter that would match location names containing the word "gourmet", the filter parameter would be [{"name":{"contains":["gourmet"]}}], which URL-encoded would be %5B%7B%22name%22%3A%7B%22contains%22%3A%5B%22gourmet%22%5D%7D%7D%5D.

NOTE: "x", "xx", and "xxx" are reserved keywords that, when passed in a contains matcher for a Full or Text filter, will cause that filter to match on all locations.

The filter types are the following. Note there may be multiple available specifications for a given filter type:

Filter Type Syntax Description
Full fieldName: {contains: $search} $search is the search string
Text fieldName: {$type: [$search,...]} $type is one of [contains,doesNotContain,startsWith,equalTo], $search is an array of search strings, combined with OR
Text fieldName: $type $type is one of [empty,notEmpty]
Number fieldName: {$type: $value} $type is one of [eq,lt,gt,le,ge], $value is the numeric value
Number fieldName: {$type: [$value1, $value2]} $type is one of [between], $value1 and $value2 are numeric values
Date fieldName: {$type: $value} $type is one of [eq,lt,gt,le,ge], $value is a string of "YYYY-MM-DD" formatted date
Date fieldName: $type $type is one of [empty,notEmpty]
Date fieldName: {$type: [$value1, $value2]} $type is one of [between], $value1 and $value2 are strings of "YYYY-MM-DD" formatted date
Categories fieldName: {$type: [$id,...]} $type is one of [includes,notIncludes], $id is an array of numeric category IDs, combined with OR
Categories fieldName: $type $type is one of [none]
Assets fieldName: {$type: [$id,...]} $type is one of [includes,notIncludes], $id is an array of numeric category IDs, combined with OR
Assets fieldName: $type $type is one of [none]
Country fieldName: {$type: [$country,...]} $type is one of [includes,notIncludes], $country is an array of country code strings, combined with OR
PrimaryLanguage fieldName: {$type: [$language,...]} $type is one of [is,isNot], $language is an array of language code strings, combined with OR
AlternateLanguage fieldName: {$type: [$language,...]} $type is one of [includes, notIncludes], $language is an array of language code strings, combined with OR
StringSingle fieldName: {$type: [$string,...]} $type is one of [is,isNot], $string is an array of strings, combined with OR
StringList fieldName: {$type: [$string,...]} $type is one of [includes,notIncludes], $string is an array of strings, combined with OR
LocationType fieldName: {$type: [$id,...]} $type is one of [is,isNot], $id is an array of location type IDs, combined with OR
Bool fieldName: $type $type is one of [true,false]
Option fieldName: {$type: $id} $type is one of [is,isNot], $id is an option ID (For single option custom fields)
Option fieldName: {$type: [$id,...]} $type is one of [includes,notIncludes], $id is an array of option IDs, combined with OR (For multi option custom fields)
Folder fieldName: [$id,...] $id is a numeric folder ID
Folder fieldName: $id $id is a numeric folder ID
Folder fieldName: {$type: [$id,...]} $id is a numeric folder ID, $type is one of ['isIn', 'isNotIn']
Labels fieldName: {$type: [$id,...]} $type is one of [includes,notIncludes], $id is an array of label IDs, combined with OR

The following fields can be specified in the request (Field name/Filter Type/Example(s)):

Field Name Filter Type Example(s)
location Full "location": {"contains": "Atlanta"}
name Text "name": {"startsWith": ["Guitar"]}, "name": {"contains": ["A","B"]}
address Text "address": {"startsWith": ["South"]}
address2 Text "address2": {"contains": ["Suite"]}
city Text "city": {"contains": ["Atlanta"]}
state Text "state": {"contains": ["AK","VA"]}
zip Text "zip": {"contains": ["M5K 7QB"]}
phones Text "phones": {"startsWith": ["703","571"]}
specialOffer Text "specialOffer": "notEmpty"
emails Text "emails": {"doesNotContain": ["@yext.com"]}
website Text "website": {"equalTo": ["https://www.yext.com/"]}
categories Categories "categories": {"includes": [23,755,34]}
closed Bool "closed": true
storeId Text "storeId": {"equalTo": ["MCD0001"]}
countryCode Country "countryCode": {"notIncludes": ["US"]}
products Text "products": {"startsWith": ["Burger","Fries"]}
services Text "services": {"contains": ["Manicures"]}
specialities Text "services": "notEmpty"
associations Text "associations": "empty"
brands Text "brands": {"equalTo": ["North Face"]}
languages Text "languages": {"equalTo": ["English","Spanish"]}
keywords Text "keywords": {"startsWith": ["Franchise"]}
menuIds IdList "menuIds": {"includes": ["m-23","755","menu34"]}
productListIds IdList "productListIds": {"notIncludes": ["pl-2"]}
calendarIds IdList "calendarIds": {"notIncludes": ["cal34"]}
bioIds IdList "bioIds": {"includes": ["b23","34"]}
custom### Text (for Multiline Text, URL, Text List, and Text Custom Fields), Number, Date, Bool, or Option "custom123": {"equalTo": ["asdf"]}
folder Folder "folder": 123, "folder": [123,456]
primary_language PrimaryLanguage "primary_language": {"is": "fr_CA"}
alternateProfileLanguage AlternateLanguage "alternateProfileLanguage": {"includes": ["en", "fr"]}
npi StringSingle "npi": {"is": ["1234567890", "1111111111"]}
conditionsTreated Text "conditionsTreated": {"startsWith": ["Influenza"]}, "conditionsTreated": {"contains": ["A","B"]}
lastUpdated Date "lastUpdated": {"eq": "2018-01-01"}, "lastUpdated": {"between": ["2017-01-01", "2018-01-01"]}
fieldsWithData Fields "fieldsWithData": ["email", "hours"]
fieldsWithoutData Fields "fieldsWithoutData": ["logo", "video"]
reviewCount Number "review_count": {"gt": 1}, "review_count ": {"lt": 10}
averageRating Number "averageRating": {"lt": 3}
locationType LocationType "locationType": {"is": [1]}, "locationType": {"isNot": [123]}
gender StringSingle "gender": {"is": ["FEMALE"]}, "gender": {"isNot": ["MALE"]}
degrees StringList "degrees": {"includes": ["MD"]}, "degrees": {"notIncludes": ["PHD"]}
experiences StringList "experiences": {"includes": ["FELLOWSHIP"]}, "experiences": {"notIncludes":["INTERNSHIP"]}
yearCompleted Number "yearCompleted": {"gt": 2000}, "yearCompleted": {"lt": 2015}
acceptingNewPatients Bool "acceptingNewPatients": true
firstName Text "firstName": {"startsWith": ["David"]}, "firstName": {"contains": ["A","B"]}
middleName Text "middleName": {"startsWith": ["P"]}, "middleName": {"contains": ["N","E"]}
lastName Text "lastName": {"startsWith": ["Sm"]}, "lastName": {"contains": ["Y","Z"]}
officeName Text "officeName": {"startsWith": ["Chiropractic"]}, "officeName": {"contains":["Center","P"]}
certifications Text "certifications": {"contains": ["Radiation Oncology"]}
institutionName Text "institutionName": {"startsWith": ["New York"]}
insuranceAccepted Text "insuranceAccepted": {"startsWith": ["United"]}, "insuranceAccepted":{"contains": ["C","Health"]}
admittingHospitals Text "admittingHospitals": {"startsWith": ["Children's"]}, "admittingHospitals":{"contains": ["Medical","University"]}
subscriptions IdList "subscriptions": {"notIncludes": ["123"]}
facebookAccounts IdList "facebookAccounts": {"notIncludes": ["1111"]}
foursquareAccounts IdList "foursquareAccounts": {"notIncludes": ["1111"]}
googleplusAccounts IdList "googleplusAccounts": {"notIncludes": ["1111"]}
labels Labels "labels": {"includes": [1, 100]}

Responses

Response samples

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

Locations (Legacy): Get

Gets the primary profile for a single Location.

path Parameters
accountId
required
string
locationId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

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"

Responses

Response samples

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

Locations (Legacy): Update

Updates the primary profile for a Location.

NOTE: Despite using the PUT method, Locations: Update only updates supplied fields. Omitted fields are not modified.

NOTE: The Location's primary profile language can be changed by calling this endpoint with a different, but unused, language code.

path Parameters
accountId
required
string
locationId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

Request Body schema: application/json
id
string <= 50 characters

Primary key. Unique alphanumeric (Latin-1) ID assigned by the Customer.

accountId
string <= 50 characters

Must refer to an account.id that already exists.

locationType
string
Enum: "LOCATION" "HEALTHCARE_PROFESSIONAL" "HEALTHCARE_FACILITY" "RESTAURANT" "ATM"
locationName
string <= 100 characters

Cannot include:

  • inappropriate language
  • HTML markup or entities
  • a URL or domain name
  • a phone number
  • control characters ([\x00-\x1F\x7F])

Should be in appropriate letter case (e.g., not in all capital letters)

firstName
string

The first name of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

middleName
string

The middle name of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

lastName
string

The last name of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

officeName
string

The name of the office where the healthcare professional works, if different from locationName

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

gender
string
Enum: "FEMALE" "F" "MALE" "M" "UNSPECIFIED"

The gender of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

npi
string

The National Provider Identifier (NPI) of the healthcare provider

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL or HEALTHCARE_FACILITY.

address
string <= 255 characters

Must be a valid address

Cannot be a P.O. Box

address2
string <= 255 characters

Cannot be a P.O. Box

suppressAddress
boolean

If true, do not show street address on listings. Defaults to false.

displayAddress
string <= 255 characters

Provides additional information to help consumers get to the location. This string appears along with the location's address (e.g., In Menlo Mall, 3rd Floor).

It may also be used in conjunction with a hidden address (i.e., when suppressAddress is true) to give consumers information about where the location is found (e.g., Servicing the New York area).

Cannot be a P.O. Box

city
string <= 80 characters
state
string <= 80 characters

For US locations, the two-character code of the location’s state, or DC for the District of Columbia For non-US locations, the name of the location’s province / region / state

sublocality
string <= 255 characters

The name of the location's sublocality.

zip
string <= 10 characters

The location's postal code. For US locations, this field contains the five- or nine-digit ZIP code (the hyphen is optional). Validations are only done on zip if countryCode is US.

countryCode
string <= 2 characters

The two-character ISO 3166-1 code of the location's country or region. If omitted, US is used.

object

Area that is served by this location. It may be specified as a radius from the location's address or as a list of cities and/or postal codes.

Only for Google Business Profile: Currently, serviceArea is only supported by Google Business Profile and will not affect your listings on other sites.

phone
string

Must be a valid phone number.

isPhoneTracked
boolean

Set to true if the number listed in phone is a tracked phone number.

NOTE: When updating isPhoneTracked, you must provide a value for phone in the same request.

localPhone
string

Must be a valid, non-toll-free phone number.

Required if:

  • isPhoneTracked is true and the non-tracked number is a toll-free number, OR
  • isPhoneTracked is false and phone is a toll-free number
alternatePhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

faxPhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

mobilePhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

tollFreePhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

ttyPhone
string

Must be a valid phone number, based on the country specified in countryCode. Phone numbers for US locations must contain 10 digits.

categoryIds
Array of strings

Yext Category IDs. A Location must have at least one and at most 10 Categories.

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.

featuredMessage
string <= 50 characters

The Featured Message. Default: Call today!

Cannot include:

  • inappropriate language
  • HTML markup
  • a URL or domain name
  • a phone number
  • control characters ([\x00-\x1F\x7F])
  • insufficient spacing

If you submit a Featured Message that contains profanity or more than 50 characters, it will be ignored. The success response will contain a warning message explaining why your Featured Message wasn't stored in the system.

featuredMessageUrl
string <= 255 characters

Valid URL to which the Featured Message is linked

websiteUrl
string <= 255 characters

The URL of the location's website. This URL will be shown on your listings unless you specify a value for displayWebsiteUrl.

Must be a valid URL and is required whenever displayWebsiteUrl is specified.

displayWebsiteUrl
string <= 255 characters

The URL that is shown on your listings in place of websiteUrl. You can use displayWebsiteUrl to display a short, memorable web address that redirects consumers to the URL given in websiteUrl.

Must be a valid URL and be specified along with websiteUrl.

reservationUrl
string <= 255 characters

A valid URL used for reservations at this location.

displayReservationUrl
string <= 255 characters

The URL that is shown on your listings in place of reservationUrl. You can use displayReservationUrl to display a short, memorable web address that redirects consumers to the URL given in reservationUrl.

Must be a valid URL and be specified along with reservationUrl.

menuUrl
string <= 255 characters

The URL of the location's menu.

displayMenuUrl
string <= 255 characters

The URL that is shown on your listings in place of menuUrl. You can use displayMenuUrl to display a short, memorable web address that redirects consumers to the URL given in menuUrl.

Must be a valid URL and be specified along with menuUrl.

orderUrl
string <= 255 characters

The URL used to place orders that will be fulfilled at the location.

displayOrderUrl
string <= 255 characters

The URL that is shown on your listings in place of orderUrl. You can use displayOrderUrl to display a short, memorable web address that redirects consumers to the URL given in orderUrl.

Must be a valid URL and be specified along with orderUrl.

hours
string <= 255 characters

Hours should be submitted as a comma-separated list of days, where each day's hours are specified as follows:

d:oh:om:ch:cm

  • d = day of the week –
    • 1 – Sunday
    • 2 – Monday
    • 3 – Tuesday
    • 4 – Wednesday
    • 5 – Thursday
    • 6 – Friday
    • 7 – Saturday
  • oh:om = opening time in 24-hour format
  • ch:cm = closing time in 24-hour format

Times with single-digit hours (e.g., 9 AM) can be submitted with or without a leading zero (9:00 or 09:00).

Example: open 9 AM to 5 PM Monday and Tuesday, open 10 AM to 4 PM on Saturday – 2:9:00:17:00,3:9:00:17:00,7:10:00:16:00

SPECIAL CASES:

  • To indicate that a location is open 24 hours on a specific day, set 00:00 as both the opening and closing time for that day.
    • Example: open all day on Saturdays – 7:00:00:00:00
  • To indicate that a location is closed on a specific day, omit that day from the list or set it as closed ("closed" is not case sensitive).
    • Example: closed on Sundays – 1:closed
    • NOTE: If a location is closed seven days a week, set at least one day to closed. Otherwise, hours is an empty string, and we assume you are not submitting hours information for that location.
  • To indicate that a location has split hours on a specific day, submit a set of hours for each block of time the location is open.
    • Example: open from 9:00 AM to 12:00 PM and again from 1:00 PM to 5:00 PM on Mondays – 2:9:00:12:00,2:13:00:17:00

NOTE: To set hours for specific days of the year rather than days of the week, use holidayHours.

additionalHoursText
string <= 255 characters

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

Array of objects

Holiday hours for this location.

NOTE: hours must be set in order for holidayHours to appear on your listings)

description
string [ 10 .. 5000 ] characters
conditionsTreated
Array of strings

A list of the conditions treated by the healthcare provider

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL or HEALTHCARE_FACILITY.

certifications
Array of strings

A list of the certifications held by the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

Array of objects

A list of the types of education and training completed by the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

degrees
Array of strings

A list of the degrees earned by the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

Valid values:

  • ANP (Adult Nurse Practitioner)
  • APN (Advanced Practice Nurse)
  • APRN (Advanced Practice Registered Nurse)
  • ARNP (Advanced Registered Nurse Practitioner)
  • CNM (Certified Nurse Midwife)
  • CNP (Certified Nurse Practitioner)
  • CNS (Clinical Nurse Specialist)
  • CPNP (Certified Pediatric Nurse Practitioner)
  • CRNA (Certified Registered Nurse Anesthetist)
  • CRNP (Certified Registered Nurse Practitioner)
  • DC (Doctor of Chiropractic)
  • DDS (Doctor of Dental Surgery)
  • DMD (Doctor of Dental Medicine)
  • DO (Doctor of Osteopathy)
  • DPM (Doctor of Podiatric Medicine)
  • DVM (Doctor of Veterinary Medicine)
  • FNP (Family Nurse Practitioner)
  • GNP (Geriatric Nurse Practitioner)
  • LAC (Licensed Acupuncturist)
  • LPN (Licensed Practical Nurse)
  • MD (Medical Doctor)
  • ND (Naturopathic Doctor)
  • NP (Nurse Practitioner)
  • OD (Doctor of Optometry)
  • PA (Physician Assistant)
  • PAC (Physician Assistant Certified)
  • PHARMD (Doctor of Pharmacy)
  • PHD (Doctor of Philosophy)
  • PNP (Pediatric Nurse Practitioner)
  • VMD (Veterinary Medical Doctor)
  • WHNP (Womens Health Nurse Practitioner)
admittingHospitals
Array of strings

A list of hospitals where the healthcare professional admits patients

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

acceptingNewPatients
boolean

Indicates whether the healthcare provider is accepting new patients

Default is true

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL or HEALTHCARE_FACILITY.

object

A set of field-value pairs indicating whether the location is closed and, if it is closed, the date of its closing.

NOTE: This field does not appear in the GET response unless it has been explicitly set in a PUT request.

paymentOptions
Array of strings

The payment methods accepted at this location

Valid elements depend on the location's country. For US locations, valid elements are:

  • AMERICANEXPRESS
  • CASH
  • CHECK
  • DINERSCLUB
  • DISCOVER
  • FINANCING
  • INVOICE
  • MASTERCARD
  • TRAVELERSCHECK
  • VISA
  • ANDROIDPAY
  • APPLEPAY
  • SAMSUNGPAY
  • BITCOIN
  • PAYPAL
insuranceAccepted
Array of strings

A list of insurance policies accepted by the healthcare provider

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

object
Array of objects

Up to 50 Photos.

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

object

A portrait of the healthcare professional

NOTE: This field is only available to locations whose locationType is HEALTHCARE_PROFESSIONAL.

videoUrls
Array of strings[ items <= 255 characters ]

Valid YouTube URLs for embedding a video on some publisher sites.

NOTE: Currently, only the first URL in the Array appears in your listings.

instagramHandle
string

Valid Instagram username for the location (e.g., NewCityFiat (without the leading "@"))

twitterHandle
string <= 15 characters

Valid Twitter handle for the location (e.g., JohnSmith (without the leading '@')). If you submit an invalid Twitter handle, it will be ignored. The success response will contain a warning message explaining why your Twitter handle wasn't stored in the system.

googleWebsiteOverride
string <= 255 characters

The URL you would like to submit to Google Business Profile 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.

object

The cover photo for your business's Google profile

NOTE: Your cover photo must meet all of the following requirements:

  • have a 16:9 aspect ratio
  • be at least 480 x 270 pixels
  • be no more than 2120 x 1192 pixels
object

The profile photo for your business's Google profile

NOTE: Your profile picture must meet all of the following requirements:

  • be a square
  • be at least 250 x 250 pixels
Array of objects

The Google Business Profile attributes for this location.

facebookPageUrl
string <= 255 characters

URL for the location'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.

NOTE: This value is automatically set to the location's Facebook Page URL. You can only manually set facebookPageUrl if the location meets one of the following criteria:

  • It is not subscribed to a Listings package that contains Facebook.
  • It is opted out of Facebook.
object

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

object

The cover photo for your business's Facebook profile

Displayed as a 851 x 315 pixel image

You must have a cover photo in order for your listing to appear on Facebook.

NOTE: Your cover photo must be at least 400 pixels wide.

object

The profile picture for your business's Facebook profile

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

NOTE: Your profile picture must be larger than 180 x 180 pixels.

uberLinkType
string
Enum: "LINK" "BUTTON"

Indicates whether the embedded Uber link for this location appears as text or a button

When consumers click on this link on a mobile device, the Uber app (if installed) will open with your location set as the trip destination. If the Uber app is not installed, the consumer will be prompted to download it.

uberLinkText
string <= 100 characters

The text of the embedded Uber link

Default is "Ride there with Uber".

NOTE: This field is only available if uberLinkType is LINK.

uberTripBrandingText
string <= 28 characters

The text of the call-to-action that will appear in the Uber app during a trip to your location (e.g., Check out our menu!)

NOTE: If a value for uberTripBrandingText is provided, values must also be provided for uberTripBrandingUrl and uberTripBrandingDescription.

uberTripBrandingUrl
string

The URL that the consumer will be redirected to when tapping on the call-to-action in the Uber app during a trip to your location.

NOTE: If a value for uberTripBrandingUrl is provided, values must also be provided for uberTripBrandingText and uberTripBrandingDescription.

uberTripBrandingDescription
string <= 150 characters

A longer description that will appear near the call-to-action in the Uber app during a trip to your location.

NOTE: If a value for uberTripBrandingDescription is provided, values must also be provided for uberTripBrandingText and uberTripBrandingUrl.

yearEstablished
string <= 4 characters

The year that this location was opened, not the number of years it was open

Minimum of 1000, maximum of current year + 10.

displayLat
number <double>

Latitude where the map pin should be displayed, as provided by you

Between -90.0 and 90.0, inclusive

displayLng
number <double>

Longitude where the map pin should be displayed, as provided by you

Between -180.0 and 180.0, inclusive

routableLat
number <double>

Latitude to use for driving directions to the location, as provided by you

Between -90.0 and 90.0, inclusive

routableLng
number <double>

Longitude to use for driving directions to the location, as provided by you

Between -180.0 and 180.0, inclusive

walkableLat
number <double>

Latitude to use for walking directions to the location, as provided by you

Between -90.0 and 90.0, inclusive

walkableLng
number <double>

Longitude to use for walking directions to the location, as provided by you

Between -180.0 and 180.0, inclusive

pickupLat
number <double>

Latitude to use for pickup spot for the location, as provided by you

Between -90.0 and 90.0, inclusive

pickupLng
number <double>

Longitude to use for pickup spot for the location, as provided by you

Between -180.0 and 180.0, inclusive

dropoffLat
number <double>

Latitude to use for drop off spot for the location, as provided by you

Between -90.0 and 90.0, inclusive

dropoffLng
number <double>

Longitude to use for drop off spot for the location, as provided by you

Between -180.0 and 180.0, inclusive

emails
Array of strings[ items <= 255 characters ]

Up to five emails addresses for reaching this location

Must be valid email addresses

specialities
Array of strings[ items <= 100 characters ]

Up to 100 specialities (e.g., for food and dining: Chicago style)

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

associations
Array of strings[ items <= 100 characters ]

Up to 100 association memberships relevant to the location (e.g., New York Doctors Association)

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

products
Array of strings[ items <= 100 characters ]

Up to 100 products sold at this location

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

services
Array of strings[ items <= 100 characters ]

Up to 100 services offered at this location

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

brands
Array of strings[ items <= 100 characters ]

Up to 100 brands sold by this location

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

language
string <= 10 characters

Language code of the language in which this location's information is provided. This language is considered the Location's primary language in our system.

If you would like to provide your Location data in more than one language, you can create a Language Profile for each of these additional (alternate) languages.

languages
Array of strings[ items <= 100 characters ]

Up to 100 languages spoken at this location.

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

keywords
Array of strings[ items <= 100 characters ]

Up to 100 keywords may be provided

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

menusLabel
string

Label to be used for this location’s Menus. This label will appear on your location's listings.

menuIds
Array of strings

IDs of Menus associated with this location.

bioListsLabel
string

Label to be used for this location’s Bio lists. This label will appear on your location's listings.

bioListIds
Array of strings

IDs of Bio lists associated with this location.

productListsLabel
string

Label to be used for this location’s Product & Services lists. This label will appear on your location's listings.

productListIds
Array of strings

IDs of Product lists associated with this location.

eventListsLabel
string

Label to be used for this location’s Event lists. This label will appear on your location's listings.

eventListIds
Array of strings

IDs of Event lists associated with this location.

folderId
string

The folder that this location is in. Must be a valid, existing Yext Folder ID

labelIds
Array of strings

The IDs of the location labels that have been added to this location. Location labels help you identify locations that share a certain characteristic; they do not appear on your location'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.

In Locations: Update requests:

  • If the v parameter is before 20180223: setting the value of labelIds to an empty array has no effect on the current value
  • If the v parameter is 20180223 or after: setting the value of labelIds to an empty array deletes the current value
object

A set of key-value pairs indicating the location's custom fields and their values. The keys are the ids of the custom fields, and the values are the fields' contents for this location.

To retrieve a list of custom fields for your account, use the Custom Fields: List endpoint.

If a field's type is SINGLE_OPTION or MULTI_OPTION, the option or options that apply to this location must be represented by their **key**s.

Examples of each type of custom field:

  • BOOLEAN:
    • { "9662": "true" }
  • DAILY_TIMES:
    • { "10012": { "dailyTimes": "2:7:00,3:7:00,4:7:00,5:7:00,6:7:00,7:7:00,1:7:00" } }
  • DATE:
    • { "7066": "2016-10-12" }
  • GALLERY:
    • { "7070": [ { "url": "http://a.mktgcdn.com/p/ounkg7aq6Oy029-sRf4CIH64/128x128.jpg" }, { "url": "http://a.mktgcdn.com/p/YkQGqxK8jFBqOlailQ9QIBsgs/1.0000/316x316.png" } ] }
  • HOURS:
    • { "10011": { "hours": "1:7:00:20:00,2:7:00:20:00,3:7:00:20:00,4:7:00:20:00,5:7:00:20:00,6:7:00:20:00,7:7:00:20:00", "additionalHoursText": "Also by appointment" }
  • LOCATION_LIST:
    • { "8098" : [ "locationId1", "locationId2" ] }
  • MULTILINE_TEXT (up to 4,000 characters):
    • { "1592": "Take Route 13 south. Pass Riverrun Reservoir. At the traffic light before the post office, turn right off of Route 13. Pass the library and community center on your right and then pass a diner on your left. Cross over the bridge and at the third intersection, turn left onto Jones Street. We are located on the right side in the middle of the block." }
  • MULTI_OPTION:
    • { "7068": ["2614", "2615"] } ("2614" and "2615" are the options' **key**s)
  • NUMBER:
    • { "7078": "123" }
  • PHOTO:
    • { "7071": { "url": "http://a.mktgcdn.com/p/bRtQXQZP2kEzgy2C8/800x800.jpg", "description": "New storefront", "details": "A picture of the new storefront" } }
    • { "7071": null } (This setting will clear the existing value of the Photo custom field.)
  • SINGLE_OPTION:
    • { "7069": "2617" } ("2617" is the option's key)
  • TEXT (up to 255 characters):
    • { "6157": "Buy One, Get One 50% Off" }
  • TEXT_LIST:
    • { "7072": [ "Item 1", "Item 2", "Item 3" ] }
  • URL:
    • { "9381": "http://www.location.example.com" }
  • VIDEO:
    • { "7077": { "url": "http://www.youtube.com/watch?v=6KQPho" } }
  • VIDEO_GALLERY:
    • { "8452": [ { "url": "http://www.youtube.com/watch?v=B1EC1U" }, { "url": "http://www.youtube.com/watch?v=SkEtnN" } ] }
intelligentSearchTrackingEnabled
boolean

Indicates whether Intelligent Search Tracker is enabled.

The Intelligent Search Tracker allows you to understand your performance in local search.

intelligentSearchTrackingFrequency
string
Enum: "WEEKLY" "MONTHLY" "QUARTERLY"

How often we send search queries to track your search performance.

locationKeywords
Array of strings
Items Enum: "NAME" "PRIMARY_CATEGORY"

Keywords that we will use to track your search performance. These keywords are based on the location information you've stored in our system.

customKeywords
Array of strings

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

queryTemplates
Array of strings
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

alternateNames
Array of strings

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

alternateWebsites
Array of strings

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

Array of objects

The names and websites of the competitors whose search performance you would like to compare to your own

trackingSites
Array of strings
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

isClusterPrimary
boolean

Indicates whether the location is the primary location in its group

attire
string
Enum: "UNSPECIFIED" "DRESSY" "CASUAL" "FORMAL"

The formality of clothing typically worn at this location

NOTE: This field is only available to locations whose locationType is RESTAURANT.

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

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

NOTE: This field is only available to locations whose locationType is RESTAURANT.

mealsServed
Array of strings

Types of meals served at this location

NOTE: This field is only available to locations whose locationType is RESTAURANT.

Valid values:

  • BREAKFAST
  • LUNCH
  • BRUNCH
  • HAPPY_HOUR
  • LATE_NIGHT
locatedIn
string

For ATMs, the external ID of the location that the ATM is installed in. The location must be in the same business account as the ATM.

NOTE: This field is only available to locations whose locationType is ATM.

primaryContact
string

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

reviewResponseConversationEnabled
boolean

Indicates whether or not review response conversations are enabled for the Yext Knowledge Assistant

holidayHoursConfirmationEnabled
boolean

Indicates whether or not holiday hour confirmation alerts are enabled for the Yext Knowledge Assistant

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "accountId": "string",
  • "locationType": "LOCATION",
  • "locationName": "string",
  • "firstName": "string",
  • "middleName": "string",
  • "lastName": "string",
  • "officeName": "string",
  • "gender": "FEMALE",
  • "npi": "string",
  • "address": "string",
  • "address2": "string",
  • "suppressAddress": true,
  • "displayAddress": "string",
  • "city": "string",
  • "state": "string",
  • "sublocality": "string",
  • "zip": "string",
  • "countryCode": "st",
  • "serviceArea": {
    },
  • "phone": "string",
  • "isPhoneTracked": true,
  • "localPhone": "string",
  • "alternatePhone": "string",
  • "faxPhone": "string",
  • "mobilePhone": "string",
  • "tollFreePhone": "string",
  • "ttyPhone": "string",
  • "categoryIds": [
    ],
  • "featuredMessage": "string",
  • "featuredMessageUrl": "string",
  • "websiteUrl": "string",
  • "displayWebsiteUrl": "string",
  • "reservationUrl": "string",
  • "displayReservationUrl": "string",
  • "menuUrl": "string",
  • "displayMenuUrl": "string",
  • "orderUrl": "string",
  • "displayOrderUrl": "string",
  • "hours": "string",
  • "additionalHoursText": "string",
  • "holidayHours": [
    ],
  • "description": "stringstri",
  • "conditionsTreated": [
    ],
  • "certifications": [
    ],
  • "educationList": [
    ],
  • "degrees": [
    ],
  • "admittingHospitals": [
    ],
  • "acceptingNewPatients": true,
  • "closed": {
    },
  • "paymentOptions": [
    ],
  • "insuranceAccepted": [
    ],
  • "logo": {
    },
  • "photos": [
    ],
  • "headshot": {
    },
  • "videoUrls": [
    ],
  • "instagramHandle": "string",
  • "twitterHandle": "string",
  • "googleWebsiteOverride": "string",
  • "googleCoverPhoto": {
    },
  • "googleProfilePhoto": {
    },
  • "googleAttributes": [
    ],
  • "facebookPageUrl": "string",
  • "facebookCallToAction": {
    },
  • "facebookCoverPhoto": {
    },
  • "facebookProfilePicture": {
    },
  • "uberLinkType": "LINK",
  • "uberLinkText": "string",
  • "uberTripBrandingText": "string",
  • "uberTripBrandingUrl": "string",
  • "uberTripBrandingDescription": "string",
  • "yearEstablished": "stri",
  • "displayLat": 0,
  • "displayLng": 0,
  • "routableLat": 0,
  • "routableLng": 0,
  • "walkableLat": 0,
  • "walkableLng": 0,
  • "pickupLat": 0,
  • "pickupLng": 0,
  • "dropoffLat": 0,
  • "dropoffLng": 0,
  • "emails": [
    ],
  • "specialities": [
    ],
  • "associations": [
    ],
  • "products": [
    ],
  • "services": [
    ],
  • "brands": [
    ],
  • "language": "string",
  • "languages": [
    ],
  • "keywords": [
    ],
  • "menusLabel": "string",
  • "menuIds": [
    ],
  • "bioListsLabel": "string",
  • "bioListIds": [
    ],
  • "productListsLabel": "string",
  • "productListIds": [
    ],
  • "eventListsLabel": "string",
  • "eventListIds": [
    ],
  • "folderId": "string",
  • "labelIds": [
    ],
  • "customFields": {
    },
  • "intelligentSearchTrackingEnabled": true,
  • "intelligentSearchTrackingFrequency": "WEEKLY",
  • "locationKeywords": [
    ],
  • "customKeywords": [
    ],
  • "queryTemplates": [
    ],
  • "alternateNames": [
    ],
  • "alternateWebsites": [
    ],
  • "competitors": [
    ],
  • "trackingSites": [
    ],
  • "isClusterPrimary": true,
  • "attire": "UNSPECIFIED",
  • "priceRange": "UNSPECIFIED",
  • "mealsServed": [
    ],
  • "locatedIn": "string",
  • "primaryContact": "string",
  • "reviewResponseConversationEnabled": true,
  • "holidayHoursConfirmationEnabled": true
}

Response samples

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

Custom Fields: List

Returns a list of Custom Fields in an Account.

NOTE: Custom Fields of unsupported types will be filtered out.

The Custom Fields API will be deprecated in Spring '24. See here for more details.

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

offset
integer
Default: 0

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

limit
integer <= 1000
Default: 100

Number of results to return.

pageToken
string

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.

Responses

Response samples

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

Custom Fields: Create

Creates new Custom Field(s) in an Account.

NOTE: If the v parameter is on or after 20220615, the request body must be an array, as to allow multiple field creates per request.

The Custom Fields API will be deprecated in Spring '24. See here for more details.

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

Request Body schema: application/json
Array
required
object

The Custom Field's name (including default value and translations).

After March 19th 2020, if users Update Custom Field's name using older versions of the API without explicitly specifiying translations, any existing translations will be cleared.

Example: "name": { "value": "The promotions", "translations": [ { "languageCode": "fr", "value": "Les promotions" } ] }

Array of objects

Present if and only if type is SINGLE_OPTION or MULTI_OPTION.

List of options (key, value, and translations) for the Custom Field.

Example: { { "key": "TEMPORARILY_CLOSED", "value": "Temporarily Closed" }, { "key": "COMING_SOON", "value": "Coming Soon" }, { "key": "CLOSED", "value": "Closed" "translations": [ { "languageCode": "fr", "value": "Fermé" } ] }, { "key": "OPEN", "value": "Open" } }

The behavior of the options' keys depends on which Custom Fields endpoint you are using:

  • Get and List: The options' keys will be included in the response.
  • Create: Do not specify option keys. They will be automatically assigned when the field is created.
  • Update: If you include an option with an existing key, the option with that key will be updated with the value you specify. If you would like to add an option, specify its value but not its key, as the key will be automatically assigned when the option is added.
    • NOTE: If you do not include an existing option in your Update request, it will be deleted.
group
string
Default: "NONE"
Enum: "NONE" "GROUP_1" "GROUP_2" "GROUP_3" "GROUP_4" "GROUP_5" "GROUP_6" "GROUP_7" "GROUP_8" "GROUP_9" "GROUP_10" "GROUP_11" "GROUP_12" "GROUP_13" "GROUP_14" "GROUP_15" "GROUP_16" "GROUP_17" "GROUP_18" "GROUP_19" "GROUP_20" "GROUP_21" "GROUP_22" "GROUP_23" "GROUP_24" "GROUP_25" "GROUP_26" "GROUP_27" "GROUP_28" "GROUP_29" "GROUP_30"

The Custom Field's group.

object

The Custom Field's description (including value and translations) which, if provided, will be shown as a tooltip next to the Custom Field in the Knowledge Manager. Providing a description is highly recommended when creating apps for the App Directory.

After March 19th 2020, if users Update Custom Field's description using older versions of the API without explicitly specifiying translations, any existing translations will be cleared.

Example: "description": { "value": "This is the list of promotions", "translations": [ { "languageCode": "fr", "value": "Ceci est la liste des promotions" } ] }

alternateLanguageBehavior
string
Default: "PRIMARY_ONLY"

Custom Field multi-language profile behavior, which is one of:

PRIMARY_ONLY: The Custom Field can only have a value set on its primary language profile.

OVERRIDABLE: The Custom Field can have a value set on any alternate language profiles, which will override the primary language profile value when the alternate language profile is requested. When requested, if a value is not set for an alternate language profile, the primary language profile value will be returned.

LANGUAGE_SPECIFIC: The Custom Field can have a value set on any alternate language profiles. When requested, if a value is not set for an alternate language profile, no value will be returned.

object

A Custom Field validation object, describing validation rules when a Custom Field value is set or updated.

entityAvailability
Array of strings
Items Enum: "location" "event" "healthcareProfessional" "healthcareFacility" "atm" "restaurant"

A list of entity types that the Custom Field is available to.

id
string

ID that should be used when referencing the field in API calls. This ID will also serve as the Custom Field's key in our upcoming Entities API endpoints. Note that in Locations endpoints, Custom Fields are still referenced by their numeric id, which can be obtained by calling the Custom Fields: List endpoint with a v param before 20180809. (For Create requests) Must have a prefix of c_ and contain only alphanumeric characters or underscores.

type
required
string
Enum: "BOOLEAN" "CTA" "DAILY_TIMES" "DATE" "GALLERY" "HOURS" "ENTITY_RELATIONSHIP" "MARKDOWN" "MULTILINE_TEXT" "MULTI_OPTION" "NUMBER" "PHOTO" "RICH_TEXT" "RICH_TEXT_V2" "SINGLE_OPTION" "TEXT" "TEXT_LIST" "URL" "VIDEO" "VIDEO_GALLERY"

The data type of the Custom Field's contents. Only the types listed here are supported. Note that the ENTITY_LIST type has been renamed to ENTITY_RELATIONSHIP. The former can still be obtained by calling Custom Fields endpoints with a v param before 20220615. Before 20180809, this type was named LOCATION_LIST.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Custom Fields: Get

Gets a specific Custom Field in an Account.

The Custom Fields API will be deprecated in Spring '24. See here for more details.

path Parameters
accountId
required
string
customFieldId
required
string

ID that should be used when referencing the field in API calls. This ID will also serve as the Custom Field's key in our upcoming Entities API endpoints. Note that the Custom Fields can still be accessed using their numeric id by invoking the endpoints with a v param before 20180809.

query Parameters
v
required
string

A date in YYYYMMDD format.

Responses

Response samples

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

Custom Fields: Update

Updates a single Custom Field in an Account.

Note that the only updatable values in an existing Custom Field are its name, group, description, alternate language behavior, as well as available options if its type is SINGLE_OPTION or MULTI_OPTION.

  • If options are modified, every location with that option selected will have the new value.
  • If options are deleted, all locations with that option will no longer have that option selected.
  • If the deleted options are the only options selected for a location, the location will no longer have a value set for that Custom Field.

The Custom Fields API will be deprecated in Spring '24. See here for more details.

path Parameters
accountId
required
string
customFieldId
required
string

ID that should be used when referencing the field in API calls. This ID will also serve as the Custom Field's key in our upcoming Entities API endpoints. Note that the Custom Fields can still be accessed using their numeric id by invoking the endpoints with a v param before 20180809.

query Parameters
v
required
string

A date in YYYYMMDD format.

Request Body schema: application/json
required
object

The Custom Field's name (including default value and translations).

After March 19th 2020, if users Update Custom Field's name using older versions of the API without explicitly specifiying translations, any existing translations will be cleared.

Example: "name": { "value": "The promotions", "translations": [ { "languageCode": "fr", "value": "Les promotions" } ] }

Array of objects

Present if and only if type is SINGLE_OPTION or MULTI_OPTION.

List of options (key, value, and translations) for the Custom Field.

Example: { { "key": "TEMPORARILY_CLOSED", "value": "Temporarily Closed" }, { "key": "COMING_SOON", "value": "Coming Soon" }, { "key": "CLOSED", "value": "Closed" "translations": [ { "languageCode": "fr", "value": "Fermé" } ] }, { "key": "OPEN", "value": "Open" } }

The behavior of the options' keys depends on which Custom Fields endpoint you are using:

  • Get and List: The options' keys will be included in the response.
  • Create: Do not specify option keys. They will be automatically assigned when the field is created.
  • Update: If you include an option with an existing key, the option with that key will be updated with the value you specify. If you would like to add an option, specify its value but not its key, as the key will be automatically assigned when the option is added.
    • NOTE: If you do not include an existing option in your Update request, it will be deleted.
group
string
Default: "NONE"
Enum: "NONE" "GROUP_1" "GROUP_2" "GROUP_3" "GROUP_4" "GROUP_5" "GROUP_6" "GROUP_7" "GROUP_8" "GROUP_9" "GROUP_10" "GROUP_11" "GROUP_12" "GROUP_13" "GROUP_14" "GROUP_15" "GROUP_16" "GROUP_17" "GROUP_18" "GROUP_19" "GROUP_20" "GROUP_21" "GROUP_22" "GROUP_23" "GROUP_24" "GROUP_25" "GROUP_26" "GROUP_27" "GROUP_28" "GROUP_29" "GROUP_30"

The Custom Field's group.

object

The Custom Field's description (including value and translations) which, if provided, will be shown as a tooltip next to the Custom Field in the Knowledge Manager. Providing a description is highly recommended when creating apps for the App Directory.

After March 19th 2020, if users Update Custom Field's description using older versions of the API without explicitly specifiying translations, any existing translations will be cleared.

Example: "description": { "value": "This is the list of promotions", "translations": [ { "languageCode": "fr", "value": "Ceci est la liste des promotions" } ] }

alternateLanguageBehavior
string
Default: "PRIMARY_ONLY"

Custom Field multi-language profile behavior, which is one of:

PRIMARY_ONLY: The Custom Field can only have a value set on its primary language profile.

OVERRIDABLE: The Custom Field can have a value set on any alternate language profiles, which will override the primary language profile value when the alternate language profile is requested. When requested, if a value is not set for an alternate language profile, the primary language profile value will be returned.

LANGUAGE_SPECIFIC: The Custom Field can have a value set on any alternate language profiles. When requested, if a value is not set for an alternate language profile, no value will be returned.

object

A Custom Field validation object, describing validation rules when a Custom Field value is set or updated.

entityAvailability
Array of strings
Items Enum: "location" "event" "healthcareProfessional" "healthcareFacility" "atm" "restaurant"

A list of entity types that the Custom Field is available to.

Responses

Request samples

Content type
application/json
{
  • "name": {
    },
  • "options": [
    ],
  • "group": "NONE",
  • "description": {
    },
  • "alternateLanguageBehavior": "PRIMARY_ONLY",
  • "validation": {
    },
  • "entityAvailability": [
    ]
}

Response samples

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

Custom Fields: Delete

Deletes a Custom Field in an Account.

The Custom Field will be removed from all locations, and all content entered in the Custom Field will be deleted permanently.

The Custom Fields API will be deprecated in Spring '24. See here for more details.

path Parameters
accountId
required
string
customFieldId
required
string

ID that should be used when referencing the field in API calls. This ID will also serve as the Custom Field's key in our upcoming Entities API endpoints. Note that the Custom Fields can still be accessed using their numeric id by invoking the endpoints with a v param before 20180809.

query Parameters
v
required
string

A date in YYYYMMDD format.

Responses

Response samples

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

Language Profiles (Legacy): List

Get Language Profiles for a Location.

path Parameters
accountId
required
string
locationId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

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"

Responses

Response samples

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

Language Profiles (Legacy): Get

Gets the the requested Language Profile for a given Location.

path Parameters
accountId
required
string
locationId
required
string
language_code
required
string

Locale code.

query Parameters
v
required
string

A date in YYYYMMDD format.

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"

Responses

Response samples

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