WelcomeThis guide will introduce you to the Yext App Directory, teach you how to build publishable apps using our APIs, and outline the process to submit apps to the App Directory.
What’s in this guide:
The Yext App DirectoryThe Yext App Directory is a catalog of turnkey integrations (or “apps”) between the Yext Knowledge Engine and various platforms. While any developer can build custom apps to integrate with their own instance of the Yext Knowledge Engine, apps that are published to the Yext App Directory can be discovered and easily enabled by all Yext customers. These apps can help customers leverage existing data in other platforms, manage data, or perform actions on their behalf in the Yext Knowledge Engine.
As an App Partner, publishing your app in the Yext App Directory gives you the opportunity to deliver powerful value-added integrations for our mutual customers. It also offers you a new channel for customer acquisition, as existing Yext customers can browse for new solutions to solve their business needs.
back to top
The Yext Knowledge EngineThe Yext Knowledge Engine is a robust platform allowing businesses to manage data about their brand, including locations, products, bios, menus, events, and other custom attributes. The Yext Knowledge Engine then gives businesses the power to control that data across the digital landscape with our Listings, Pages, and Reviews products. Finally, the Yext Knowledge Engine allows businesses to realize the value of the platform through our Analytics offerings.
To learn more, visit the Products page on our website.
back to top
What apps can doApps built for the Yext App Directory have full access to the robust APIs available in the Yext Knowledge Engine. These APIs allow apps to:
- Manage data in Knowledge Manager
- Check the status of business listings and publisher suggestions in the Listings product
- Access analytics data on how consumers interact with Yext customers’ information online
- Monitor, respond to, generate, and manage reviews in the Reviews product
- Manage administrative functions, such as adding users and custom fields
Location data management and syncing: An app could monitor updates to location data in an external system or in the Yext Knowledge Engine and make those same updates in a linked system. This capability would allow customers to use existing methods or introduce new processes to manage location data without replacing systems.
Analytics data export: An app could periodically export analytics data from the Yext Knowledge Engine into a business intelligence (BI) or data analysis tool to make insights more accessible to stakeholders.
Review generation: An app could export customer data from a customer relationship management (CRM) system to generate first- or third- party review invitations.
Lead generation: An app could capture customer leads from Yext’s white-labeled Partner Scan tool and import them into a CRM.
Digital assets import: An app could import digital assets from existing platforms into the Yext Knowledge Engine to be used throughout the product.
COMING SOON The following APIs are not available as of this writing but will be included in a future release. If you would like to use these APIs, please contact us, as we may be able to provide preliminary API documentation:back to top
- Leads API
- Social API
Typical app usersYext customers are responsible both for ensuring data about their brand is correct and for leveraging that data within their role to deliver value to their businesses. As an app developer, you should keep this audience in mind for the apps you create. In particular, apps should be easy to use for people in the roles listed below, without requiring advanced technical knowledge or having to involve multiple stakeholders. These qualities–and the complexity they introduce–may negatively impact your app’s adoption.
Depending on the scope of your app, users may include:
- Digital Marketing Managers/Directors/VPs
- Search Optimization Managers (organic and paid)
- Customer Experience Managers
- Social Media Managers
- CMOs, COOs, CTOs (for smaller Enterprise customers)
- Marketing Associates/Specialists
- SEO Managers
- Product Managers
- Strategy Associates/Directors
- CEOs, CMOs, Founders, Presidents
- Business Owners
- Store Managers
Costs associated with the Yext App DirectoryThe Yext App Directory is not a marketplace, and there are no developer fees to use Yext APIs, integrate with the Yext Knowledge Engine, or publish to the App Directory.
Unlike consumer marketplaces such as the Apple App Store or the Google Play Store, apps are not purchased by Yext customers. App Directory listings simply point to your app to handle installation, configuration, and maintenance.
Since many platforms are subscription-based, your app may require that the Yext customer become a paid customer of your platform. Yext does not collect a commission on newly acquired customers that come through the App Directory.
back to top
Apps and the App DirectoryApps built for the Yext Knowledge Engine are modeled similarly to other Software-as-a-Service platforms with third-party integrations:
- Apps are standalone and are not hosted on Yext’s infrastructure.
- Apps have a web-based user interface.
- Apps do not change the user experience of the Yext Knowledge Engine platform and only integrate via available Yext APIs.
- Apps are linked to Yext customer accounts via a standard OAuth process.
- syncing location data between Platform ABC and Yext, and
- triggering reviews invitations in Yext based on customer data in Platform ABC.
back to top
App modelsSince apps are not hosted on Yext’s infrastructure, the most common app models are adapter apps and third-party apps.
Adapter appsAdapter apps can be thought of as standalone apps running on infrastructure outside of both Yext and an external platform. For example, an app that integrates with both Yext and Twitter would not be hosted by either platform and would run in a standalone environment with a full app logic, database, and user interface stack. Adapter apps generally have no inherited user context on either platform, and they need to prompt customers to link to each platform to gain access. This option is for app developers who are building integrations with external platforms that they do not control, or if the external platform also has a concept of an “app” or “integrations” directory.
Some examples include:
- integrating Yext with Twitter to tweet when hours for a business have changed, and
- integrating Yext with Google Calendar to populate a calendar with listed events in Yext.
Third-party appsThird-party apps are apps that are built directly into the external platform that will integrate with Yext. For example, a cloud business-intelligence platform may have a built-in analytics data import framework. Creating a custom data connector to import Yext Analytics data into that platform would allow the app to be hosted and run on the external platform’s infrastructure. Since the app runs in the external platform, it may already have a user context in that platform. This option is for app developers who are building integrations into an external platform that they host/manage.
Some examples include:
- a built-in integration to Domo (analytics/BI platform) to ingest Yext Analytics data, and
- a built-in integration into a physician master data-management system to dual-sync Yext healthcare entities.
App DirectoryThe Yext App Directory is a public listing of apps that have been reviewed and approved by Yext, as well as the interface where Yext customers can search for and learn more about apps.
Example App Directory browse page
Each published app will have its own App Directory listing page with its name, description, and other attributes. From these pages, Yext customers can choose to install apps, launch apps (if already installed), or uninstall apps they’ve installed from the App Directory. To learn more about what happens when each of these actions is performed, see App installation states.
Example App Directory listing page
The App Directory does not host app-specific configuration or user interfaces – it only redirects customers to your app’s App Installation URL or App Launch URL, depending on whether your app is installed for a Yext customer. For more details, see App Directory configuration.
The App Directory can be browsed publicly, but only Yext users who have “Manage Apps” permissions in the Yext Knowledge Engine are able to install, launch, and uninstall apps.
back to top
The customer journeyThe flowchart below shows the customer journey for various states of the app and how each system plays a role in the process.
back to top
App installation statesFrom the App Directory, Yext customers can install, launch, or uninstall your apps. Each installation state has different behavior for the customer and the app:
Before installationIf your app is not linked to the customer’s account, we consider the app not installed. When a customer browses the App Directory listing page for your app, they will see a “Visit Site to Install” call-to-action button, which will launch your app via the App Installation URL.
“Visit site to install” button
App installedAn app is considered installed if:
- the App’s client ID and API key were used to exchange an authorization code for an access token, and
- that access token is still valid.
“Launch App” and “Uninstall” buttons
UninstallationA customer can choose to uninstall your app either through the app listing page or through a custom action in your app. When the “Uninstall” button is clicked on the app listing page or your app calls the Accounts: Unlink endpoint:
- the access token associated with the customer’s account is invalidated, and
- the Account Unlink webhook event is fired.
Please note that by the time your app receives the webhook payload, the access token will have already been invalidated, so you will not be able to perform any Yext API calls.
back to top
Build your first app on Yext
1 – Sign up for a Developer AccountIf you are not already a Yext customer, sign up for a Yext Developer Account to get instant access to a fully functional instance of the Yext Knowledge Engine, including the APIs you will be building on. Sample data is preloaded in the Developer Account so you can start integrating right away.
2 – Create your App in the Developer ConsoleThe Developer Console is where you will create and manage your apps, monitor your app usage, and set up notifications. You can find the Developer Console by hovering over your name in the upper-right corner of the Yext platform:
In the Developer Console, create a new app by clicking on + New App in the “Your Apps” section and entering values for the required fields. More information about each field can be found in App configuration.
PERMISSIONS AND ENDPOINTS When choosing Permissions and Endpoints to access during the app-creation process, ensure that you are only requesting the most limited set of permissions/endpoints needed for your use case.Once you create your app, you’ll receive a client ID and API key in the “App Details” page, which you will need to build your app.
If you need access to PowerListings®, Reviews, or Analytics endpoints, contact the App Developer Support team so we can enable those features in your Developer Account.
3 – Build your AppApps are able to use any endpoints selected during the app-creation process. While your app is completely customizable, we generally see many apps following the adapter app model, with the workflow below:
a. Splash pageAn optional splash page gives you the opportunity to introduce the customer to your app after they’ve decided to install it. You may want to describe any steps that the customer will go through in the app, or you can provide any manual instructions the customer needs to follow before installation. This page will generally have a call-to-action button asking the customer to start linking their Yext and external accounts.
Generally, you will list this page in the App Directory configuration as your App Installation URL, which is the URL we redirect customers to when they would like to install your app. For more information, see App Directory configuration.
Example splash page
b. Link related accounts via OAuthMost apps integrate with Yext and another platform. Depending on where your app is hosted, you will need to request access tokens for use in your app by prompting the customer to authenticate to both services and authorize the app to perform actions on behalf of the customer.
On the Yext side, we have implemented a standard OAuth 2.0 framework for authentication and authorization. Redirecting to our OAuth flow allows us to securely authenticate with customers and prompt them to approve or reject the permissions your app requires. For more information, see OAuth and Permission Scopes.
Example Yext OAuth authorization prompt
On other platforms, we strongly recommend using an OAuth flow to authenticate/authorize the customer. If OAuth is not provided in the other platform, your app can request that the customer provide a static API key. This method is strongly discouraged, as it negatively impacts the customer experience (see Typical app users) and can give your app more permissions than needed.
However, if your app is built directly into the other platform, you may already have the context needed to perform actions on the customer’s behalf. In this case, you may not need to prompt the customer further.
WARNING Your app should never prompt for, cache, or store user credentials directly (e.g., username and password) for Yext or another platform. You should only store access tokens or other revocable authorization keys, and you must store them securely (e.g., encrypted at rest, not in plain text).Generally, in the App Directory configuration, you will list this entry point into the combined OAuth flow for both platforms as your App Launch URL, which is the URL we redirect customers to when we have detected they have already linked your app to their Yext account. This URL should launch the combined OAuth flow to determine user context and then present the customer with app configuration. If you decide not to have an optional splash page, this entry point will also be your App Installation URL. For more information, see App Directory configuration.
Apps generally do not have a separate user datastore; we recommend using a unique account identifier from both Yext and the other platform to determine a user context. App configuration can be tied to that user context. With this method, if a customer presents authentication and authorization for a matching Yext account and other platform account (regardless of the actual user credentials), they are presented with the same app configuration. To learn more, see Identifying Yext Objects.
c. Configure the integrationMost apps require the customer to perform a one-time or ongoing configuration. For example, apps may need to know which data attributes are related between systems or how the app should behave when it performs ongoing background tasks. Usually, this configuration is required for the app to complete its integration.
Once the app has determined the user context, it can present the customer with the relevant configuration options.
Example App configuration page
d. Manage the integrationOnce configured, most apps will start their integration. The app might start processing business logic immediately, or it may listen for webhooks from Yext or an external system to trigger events (see Working with Webhooks for additional information).
Some apps will require customers to manage the integration as it runs. For example, a data-sync app may give the customer an overview/management page showing the status of their sync jobs, allowing the customer to enable or disable specific syncs or perform actions to resolve any issues that arise.
If your app has a management page, the flow that starts from the App Launch URL should determine the user context, determine that App configuration is already complete, and immediately show the management interface.
Example App management page
4 – Test your appOnce you’ve developed your app, we recommend testing it thoroughly to ensure a good customer experience. Below are some test cases that might be useful:
- Does your app handle error cases for OAuth (e.g., the customer declines to give your app access)?
- If an access token is revoked on a platform, does your app gracefully handle access errors when calling APIs on that platform?
- If a customer uninstalls your app while in the App Directory, do you listen for the Unlink webhook and perform appropriate actions to clean up or delete the customer’s data?
- If you change the permissions scope of your app, does your app handle existing access tokens with reduced scopes appropriately?
InternationalizationIf your app is intended to work with accounts and customers in different countries:
- Does your App handle international data formats appropriately (e.g., address, phone, currency, etc.)?
- Is your App localized and translated for international customers?
5 – Submit your AppOnce you’ve fully developed and tested your app, you will need to gather some required information before submitting it to the App Directory. Specifically, you will need to provide values for the following fields on the “App Settings” page:
- App logo
- App name
- Short tagline
- Detailed description
- App Installation/Launch URL
- Customer support email
- Testing instructions
Top: Private app cannot be submitted because required information is missing
Bottom: Private app is eligible to be submitted
Bottom: Private app is eligible to be submitted
App in Submitted status
App developers who submit an app should expect to be contacted via email or phone from the Yext App Directory Review Team, so please ensure that your Contact Email and Contact Phone are correct before submitting. We will contact you to:
- inform you that your app has been approved and will be live on the App Directory;
- ask clarifying questions about your app’s purpose/functionality or resolve any testing issues that we find; or
- inform you that your app will be rejected, with accompanying reasons. We will give you an opportunity to resolve any concerns and resubmit if applicable.
App in Published status
back to top
QuotasWe will attribute your app’s API usage by customers to your Developer Account. When your app is submitted to the App Directory and approved, we will increase your API quota substantially to support it.
You may contact us at any time in the future to increase this quota if your app requires it. We do not expect to charge app developers for increased quota usage.
At our discretion, we may review your API usage to ensure that resources are being used appropriately.
back to top