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.

KnowledgeAPIEnterprise

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:
  • Entities — create, delete, and update entity content
  • Analytics — build and retrieve reports on performance metrics
  • Listings — 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
  • Locations (legacy) — create, delete, and update location content (Note: For new integrations, use the Entities endpoint. The Locations API is maintenance only and will not have new features added to the Yext Knowledge Graph.)
If you are not sure which endpoints to select, contact your CSM or Implementation 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
  • Listings
  • Social
  • Reviews

Phase 2: Review documentation

4. Review the Yext Knowledge API documentation: 5. After reviewing the API documentation and creating your app, provide your CSM or Implementation manager with the following information(if neither of these apply, please reach out to API Support):
  • Name of your Developer Account
  • Contact email address associated with your Developer Account
  • The type of integration you are looking to build, with a brief description of the use case. e.g. Are you planning to push and pull data (i.e. Read/Write API Permissions)? Or are you planning to only pull data? (i.e. Read Only)
  • The API endpoints you are building against (e.g. Entities, Analytics, Reviews, Listings, etc).
  • If your integration involves pushing data to Yext, you will need to test your integration in your Developer Account
  • If you are planning an SSO integration alongside your Entities integration, please let us know. We will work to create a sandbox environment for you to test in. You can also refer to our SSO Implementation Guide.
  • If you have any other points of contact / other developers working on the integration apart from the Developer Account creator, please provide their email addresses
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. You should receive a confirmation email when this is complete. If you do not, please reach out to our API Support team at apisupport@yext.com.

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 relevant test cases and you feel comfortable that your data meets Yext’s requirements, contact your CSM or Implementation Manager to initiate Yext QA.

8. A member of your Platform Services or Implementation 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 team confirms that your data is production-ready, we’ll ask you to set up your app in your production account’s Developer Console.

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 your Implementation Manager 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 CSM or Implementation 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.line1
  • 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
name
  • 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
    • Do not include a phone number or a geo-modifier in your name
  • Good Example:
    • Good Food Restaurant
  • Bad Examples:
    • GOOD FOOD RESTAURANT
    • Good Food Restaurant (917) 555-2323
    • Good Food Restaurant Midtown New York
categoryIds
  • Provide a brand category and at least one additional category
address.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
address.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
mainPhone
  • Dos:
    • Provide a unique local phone number for each location
    • Do provide a country code in the phone number if you intend to provide a phone number that does not match the entity’s country
  • Don’ts:
    • Do not provide duplicate phone numbers or a toll-free number, unless you are including a local phone number (localPhone), as well
postalCode
  • Dos:
    • For US locations, provide a five-digit postal code
  • Don’ts:
    • Do not provide any additional digits
region
  • Dos:
    • Properly case the state
  • Don’ts:
    • Do not provide in all lowercase or in an invalid format
  • Good Example:
    • MA
  • Bad Example:
    • Ma
meta.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

address.line2
  • 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.line1 field or provide values that exceed 255 characters in length
  • Good Example:
    • address.line1: 1 Madison Avenue, address.line2: 5 Fl
  • Bad Example:
    • address.line1: 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:
    • GreatBrand is one of the nation’s largest title-lending companies.
  • Bad Example:
    • GreatBrand 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
address.extraDescription
  • Dos:
    • Provide valid additional information with a value no more than 255 characters in length
  • Don’ts:
    • Do not provide malls/location descriptors or landmarks in name, address.line1, or address.line2
    • Do not provide an extra description with address.line1 or address.line2 value
    • Do not provide additional information exceeding 255 characters
  • Good Example:
    • name: Dr. John Smith, address.line1: 1 Madison Avenue, address.line2: 5 Fl, address.extraDescription: Madison Plaza
  • Bad Example:
    • name: Dr. John Smith Madison Plaza, address.line1: 1 Madison Avenue, Madison Plaza, address.line2: 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
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 Entities with all supported fields

  • Create entities
  • Create an Entity (UTF-8 encoding)
  • Update Entities – Simple Fields
    • Update 5 Entities with simple fields (Name, Address, Phone, Website, etc.) (only send fields that changed)
    • Guide: Manage Entities
    • Documentation: Entities: Update
  • Update Entities – Complex Fields
  • NOTE: Only changes (deltas) should be sent in PUT Entity requests. Entity IDs should never change once set. A localPhone value must be provided if the (mainPhone) is a toll-free number or a tracked number. If mainPhone 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

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