Knowledge API Integration Guide

About Yext

The Yext Knowledge Engine™ helps your business manage the public facts about your brand everywhere they appear online, facilitating face-to-face and digital interactions that boost brand awareness, drive foot traffic, and increase sales.

The Yext Knowledge API allows you to integrate with the products (endpoints) included in your Yext subscription.

Getting Started

As you get ready to integrate with Yext via API, here’s a step-by-step walkthrough of our integration process. This guide includes what we require from you and what you can expect from us.

Phase 1: Setting up a test environment

1. Create a Yext Developer Account to test the API integration.

2. While logged in to your Developer Account, go to your Developer Console by pointing to your name in the upper-right corner of the page and clicking Developer Console in the drop-down menu.

3. In the Developer Console, you’ll need to create an app with the appropriate API endpoints. To do so, click + New App, complete the form, and select the endpoints you want to test:
  • Locations — create, delete, and update location content
  • Analytics — build and retrieve reports on performance metrics
  • PowerListings® — monitor location listings
  • Reviews — monitor, generate, and respond to customer reviews
  • Account Settings — manage users
  • Assets — manage text, photos, and videos in your asset library
If you are not sure which endpoints to select, contact your Account Manager or email our API Support team. Be sure to specify the desired functionality.

Please note that the following endpoint groups cannot be tested in your Developer Account:
  • Analytics
  • PowerListings®
  • Social
  • Reviews

Phase 2: Review documentation

4. Review the Yext Knowledge API documentation: 5. After reviewing the API documentation and creating your app, confirm the following information with your Account Manager:
  • Name of Developer Account
  • App or apps created
  • Desired endpoints
  • Fields you’d like to to update / retrieve
Our team will then load a copy of your production data into your Developer Account. Please allow 3-5 business days for the data to appear in your Developer Account.

Phase 3: Client testing and QA

6. Once the production data is in your Developer Account, you can begin testing the Yext Knowledge API using the information at the bottom of this page:
  • Field requirements
    • We’ve listed the data field specifications that are supported by Yext. Your data sent via API must meet these standards.
  • Test cases
    • We’ve created a list of required test cases that you need to complete in your Developer Account. We require that you test your data for 5-10 business days to ensure that your integration meets all the cases.

Phase 4: Yext QA

7. When you’ve successfully performed all the test cases and you feel comfortable that your data meets Yext’s requirements, contact your Account Manager to initiate Yext QA.

8. Our Operations team will review the information you’ve pushed to your Developer Account to guarantee that all quality standards are met and that the data is production-ready. This process can take about 5-10 business days, though the actual timeframe may vary.

9. Once our Operations team confirms that your data is production-ready, we’ll ask you to set up your app in your production dashboard.

10. Make the necessary configuration changes on your side to account for the differences between your production account and the Developer account (e.g., API keys, IDs for custom fields).

Phase 5: Launch

11. Before the initial push to your production account, you’ll coordinate with our Operations team so they can monitor, catch, and correct any issues that may arise.

12. Once any issues have been resolved, you’ll be live and integrated with Yext!

If you have any questions during this process, contact your Account Manager or email our API Support team.

Additional resources

QA criteria

The information you need to complete Phase 3 of the integration appears below.

Field Requirements

Required profile fields

address
  • Dos:
    • Provide an address properly cased and under 255 characters in length
    • Provide an address that is a valid street address
    • Provide an address with valid characters in international addresses
  • Don’ts:
    • Do not provide an address in all capitals, all lowercase, in an invalid format, or exceeding 255 characters in length
    • Do not provide an address that is a cross street
    • Do not provide an address with invalid accents or punctuation in international addresses
  • Good Example:
    • 1 Madison Avenue
  • Bad Example:
    • 1 MADISON AVENUE
    • Madison Avenue & 23rd Street
locationName
  • Dos:
    • Provide a business name, properly cased, that is at least 3 and no more than 100 characters in length
  • Don’ts:
    • Do not provide a business name in all capitals, all lowercase, or an invalid format
    • Do not provide a business name under 3 characters or over 100 characters in length
  • Good Example:
    • Arby’s Restaurant
  • Bad Example:
    • ARBY’S RESTAURANT
categoryIds
  • Dos:
    • Provide a brand category and at least one additional category
  • Don’ts:
    • Do not provide zero categories or no brand category
city
  • Dos:
    • Provide a city, properly cased
    • For locations on military bases, provide the city name, not the base name
  • Don’ts:
    • Do not provide a city in all capitals, all lowercase, or in an invalid format
    • Do not provide a military base name as the city
  • Good Example:
    • Elko New Market
    • Fort Lewis
  • Bad Example:
    • ELko New MarkeT
    • Joint Base Lewis McChord
countryCode
  • Dos:
    • Provide a valid two-character ISO 3166-1 country code
  • Don’ts:
    • Do not a provide an invalid country code or any format other than the ISO abbreviation
featuredMessage
  • Dos:
    • Provide a Featured Message up to 50 characters in length
  • Don’ts:
    • Do not provide a Featured Message that exceeds 50 characters in length
phone
  • Dos:
    • Provide a unique local phone number for each location
  • Don’ts:
    • Do not provide duplicate phone numbers or a toll-free number, unless you are including a local phone number (localPhone), as well
zip
  • Dos:
    • For US locations, provide a five-digit postal code
  • Don’ts:
    • Do not provide any additional digits
state
  • Dos:
    • Properly case the state
  • Don’ts:
    • Do not provide in all lowercase or in an invalid format
  • Good Example:
    • MA
  • Bad Example:
    • Ma
id
  • Dos:
    • Provide unique store IDs for each location that are no more than 64 characters in length
  • Don’ts:
    • Do not provide duplicate store IDs or store IDs exceeding 64 characters in length

Recommended profile fields

address2
  • Dos:
    • Provide an appropriate value for the second address line that is no more than 255 characters in length
  • Don’ts:
    • Do not provide second address line values in the address field or provide values that exceed 255 characters in length
  • Good Example:
    • address: 1 Madison Avenue, address2: 5 Fl
  • Bad Example:
    • address: 1 Madison Avenue Fl 5
associations
  • Dos:
    • Provide a comma-separated list that is no more than 500 characters in length
  • Don’ts:
    • Do not provide a list separated by any other punctuation or exceeding 500 characters in length
brands
  • Dos:
    • Provide a comma-separated list that is no more than 500 characters in length
  • Don’ts:
    • Do not provide a list separated by any other punctuation or exceeding 500 characters in length
description
  • Dos:
    • Provide valid punctuation in the business description
  • Don’ts:
    • Do not provide business descriptions with invalid symbols in the place of correct punctuation
  • Good Example:
    • TitleMax is one of the nation’s largest title-lending companies.
  • Bad Example:
    • TitleMax is one of the nation’s largest title-lending companies.
hours
  • Dos:
    • Provide business hours in the correct format
  • Don’ts:
    • Do not provide hours in formats other than those accepted by the Yext system
  • Good Example:
    • Mon-Sun 9:00AM-9:00PM
  • Bad Example:
    • Mon Sun9:9
displayAddress
  • Dos:
    • Provide a valid display address value no more than 255 characters in length
  • Don’ts:
    • Do not provide malls/location descriptors or landmarks in locationName, address, or address2
    • Do not provide a display address with an address or address2 value
    • Do not provide a display address exceeding 255 characters
  • Good Example:
    • locationName: Dr. John Smith, address: 1 Madison Avenue, address2: 5 Fl, displayAddress: Madison Plaza
  • Bad Example:
    • locationName: Dr. John Smith Madison Plaza, address: 1 Madison Avenue, Madison Plaza, address2: 5 Fl Madison Plaza
facebookPageUrl
  • Dos:
    • Provide a valid Facebook Page URL
  • Don’ts:
    • Do not provide additional URL information, such as tab information or “?”s
  • Good Example:
    • www.facebook.com/ExampleCo-Oregon-1403472319959487
  • Bad Example:
    • https://www.facebook.com/ExampleCo-Oregon-1403472319959487/?hc_ref=SEARCH&fref=nf
keywords
  • Dos:
    • Provide a comma-separated list no more than 500 characters in length
  • Don’ts:
    • Do not provide a list separated by any other punctuation or exceeding 500 characters in length
languages
  • Dos:
    • Provide a comma-separated list no more than 500 characters in length
  • Don’ts:
    • Do not provide a list separated by any other punctuation or exceeding 500 characters in length
products
  • Dos:
    • Provide a comma-separated list no more than 500 characters in length
  • Don’ts:
    • Do not provide a list separated by any other punctuation or exceeding 500 characters in length
services
  • Dos:
    • Provide a comma-separated list no more than 500 characters in length
  • Don’ts:
    • Do not provide a list separated by any other punctuation or exceeding 500 characters in length
specialties
  • Dos:
    • Provide a comma-separated list no more than 500 characters in length
  • Don’ts:
    • Do not provide a list separated by any other punctuation or exceeding 500 characters in length
twitterHandle
  • Dos:
    • Provide only the Twitter handle
  • Don’ts:
    • Do not provide http://www.twitter.com/ or any website information besides the handle
  • Good Example:
    • ExampleCo
  • Bad Example:
    • https://twitter.com/ExampleCo
websiteUrl
  • Dos:
    • Provide a URL no more than 200 characters in length
  • Don’ts:
    • Do not provide a URL that exceeds 200 characters in length

Healthcare fields

admittingHospitals
  • Dos:
    • Provide a comma-separated list containing up to 100 hospitals
    • Provide list items that are no more than 100 characters in length
  • Don’ts:
    • Do not provide a list containing more than 100 hospitals
    • Do not provide list items that are over 100 characters in length
certifications
  • Dos:
    • Provide a comma-separated list containing up to 100 certifications
    • Provide list items that are no more than 100 characters in length
  • Don’ts:
    • Do not provide a list containing more than 100 certifications
    • Do not provide list items that are over 100 characters in length
conditionsTreated
  • Dos:
    • Provide a comma-separated list containing up to 100 conditions
    • Provide list items that are no more than 100 characters in length
  • Don’ts:
    • Do not provide a list containing more than 100 conditions
    • Do not provide list items that are over 100 characters in length
educationList
  • Dos:
    • Provide education/training information for all three subfields (type, institution, yearCompleted)
    • Provide a yearCompleted value between 1900 and 2100 (inclusive)
    • Provide an institution name under 100 characters in length.
  • Don’ts:
    • Do not provide incomplete education/training data (missing any of the three subfields).
    • Do not provide a yearCompleted before 1900 or after 2100.
    • Do not provide an institution name that is more than 100 characters in length.
insuranceAccepted
  • Dos:
    • Provide a comma-separated list containing up to 100 insurance policies
    • Provide list items that are no more than 100 characters in length
  • Don’ts:
    • Do not provide a list containing more than 100 insurance policies
    • Do not provide list items that are over 100 characters in length
lastName
  • Dos:
    • Provide a last name up to 35 characters in length
  • Don’ts:
    • Do not provide a last name over 35 characters in length or one that contains a URL
locationType
  • Dos:
    • Provide a valid Location type (LOCATION, HEALTHCARE_FACILITY, or HEALTHCARE_PROFESSIONAL)
  • Don’ts:
    • Do not provide an invalid Location type
middleName
  • Dos:
    • Provide a Middle Name up to 35 characters in length
  • Don’ts:
    • Do not provide a Middle Name over 35 characters in length or one that contains a URL
npi
  • Dos:
    • Provide a valid NPI (National Provider Identifier) no more than 10 characters in length
  • Don’ts:
    • Do not provide an invalid NPI or an NPI over 10 characters in length

Test cases

Full functionality: Creating and updating Locations with all supported fields

  • Create locations
  • Create a Location (UTF-8 encoding)
  • Update Locations – Simple Fields
    • Update 5 locations with simple fields (Name, Address, Phone, Website, etc.) (only send fields that changed)
    • Guide: Manage Locations
    • Documentation: Location: Update
  • Update Locations – Complex Fields
  • Closing a store
  • NOTE: Only changes (deltas) should be sent in PUT Location requests. Location IDs should never change once set. A localPhone value must be provided if the main phone (phone) is a toll-free number or a tracked number. If phone is a tracked number, then set the isPhoneTracked field to true.

Enhanced Content Lists (ECLs): Creating Menus, Bios, Calendars, and Product Lists

User Management: Creating Users for directly logging in to the whitelabelled Yext platform or using single sign-on

  • Create a User
    • Create a User under a new customer. For most cases, the User should be assigned the “Location Manager” role.
    • Guide: Manage Users
    • Documentation: Users: Create
  • Create a User that already exists
  • Modify the username
    • Ingest the error response from the case above, and resubmit that User with a new email or screenname
    • Guide: Manage Users
    • Documentation: Users: Update
  • Change the password
  • Delete the User

Invalid fields: Error catching

Additional Features (Optional)

Maintenance

  • Ensure that your solution accounts for new publishers being added to the network
  • Ensure that your solution accounts for publishers being removed from the network
  • Ensure that your solution will not break if Yext adds fields