Connecting external knowledge sources to your Zendesk account

All Suites

Team, Growth, Professional, Enterprise, or Enterprise Plus

Support with

Knowledge Professional or Enterprise

Summary: ◀▼

You can connect external knowledge sources to your account so agents and admins can search and use content from other systems across knowledge experiences. Use dedicated connectors when available, or the universal connector for REST API sources. You can sync up to 50 sources, manage connections later, and map API fields like title, body, URL, and locale for searchable external content.

The ability to connect external content to your Zendesk account is available for all plans. However, the storage limits for external data vary by plan. See Managing data storage in your Zendesk account.

You can connect an external knowledge source to your Zendesk account to make the content available wherever external content is used. Each knowledge connector has a connector-specific authentication page that you configure prior to connecting. Once connected, you can use the Connection page to manage the connection. Any updates or additions made to those elements will be ingested into Zendesk during the next sync.

Zendesk provides dedicated knowledge connectors for supported external knowledge sources. If a dedicated connector isn't available, the universal connector provides another way to ingest knowledge from a source with a compatible REST API.

You can connect up to 50 external content sources to your Zendesk account and make the content available wherever external content is used.

This article contains the following topics:

Connecting external content using a dedicated knowledge connector
Connecting external content using the universal knowledge connector
Knowledge connector authentication reference

About connecting external content to Zendesk for use across knowledge experiences

Connecting external content using a dedicated knowledge connector

You can use a dedicated knowledge connector to connect an external knowledge source to your Zendesk account and make the content available wherever external content is used. When you connect external knowledge sources to Zendesk, you’ll see them listed as an external search source in Knowledge admin.

You must be a Knowledge admin to set up and manage external content connections.

To connect external content using a dedicated knowledge connector

In Knowledge admin, click Manage articles () in the sidebar.
Click External content > Connections.
Under the Available sources section, click Connect for the dedicated knowledge source you want to connect.
Note: To use the universal connector, see the Connecting external content using the universal knowledge connector.
Review messaging and click Continue to begin configuring the connection.
Enter the required authentication information to give Zendesk permission to access content from the knowledge source.
Authentication details vary by connector. See Knowledge connector authentication reference for information specific to the connector you are configuring.
Click Sync.
The knowledge connector is added to the Connections page and begins syncing. To manage existing connections, see Managing external knowledge connections.

Connecting external content using the universal knowledge connector

You can use a universal knowledge connector to connect an external knowledge source to Zendesk when a dedicated knowledge connector isn't available for that source. The universal connector retrieves content through the source's REST API and makes that content available in Zendesk as external knowledge.

When you configure a universal connector, you provide the information Zendesk needs to access the source API, including its API endpoint and credentials. Zendesk makes a request to the source to validate the connection and retrieve a sample response. The fields returned in the response are then available for you to map to the corresponding external content fields in Zendesk. If the source returns records across multiple pages, you can also configure how Zendesk retrieves subsequent pages.

The universal connector is intended for API-accessible wikis and knowledge bases that meet the following API requirements:

Interface: REST API
Request method: GET
Response format: JSON
Authentication: API key
Record retrieval: Content and required metadata must be available in each retrieved record
Pagination: Configurable pagination
Synchronization: Full refresh every 24 hours

You must be a Knowledge admin to configure the universal connector. You should also be familiar with the API for the knowledge source you're connecting.

To connect external content using the universal knowledge connector

In Knowledge admin, click Manage articles () in the sidebar.
Click External content > Connections.
Under the Available sources section, click Universal Connector.
Review messaging about syncing knowledge with an API and click Continue to begin configuring the connection.
Note: The universal connector uses the permissions associated with the API credentials used to configure the connection. Source-specific permissions for individual users or records aren't preserved or enforced in Zendesk.
Enter the required authentication information to give Zendesk permission to access content from the knowledge source. See Universal Connector in the Knowledge connector authentication reference table below.
Click Sync.
The knowledge connector is added to the Connections page and begins syncing. To manage existing connections, see Managing external knowledge connections.

Knowledge connector authentication reference

The following table lists the authentication fields required for each connector. When logging into the system you're connecting to, log in with a user account that has the correct permissions for content you want to sync to Zendesk.

Connector	Authentication and connection details
Amazon S3	On the Authenticate tab, configure the following: Access Key ID and Secret Access Key: AWS IAM credentials that grant programmatic access to the Amazon S3 bucket you want to sync. AWS access keys are generated through the AWS Identity and Access Management (IAM) console. See AWS Developer Guide for more information. AWS Region: AWS region where your bucket is stored. On the Define scope tab, configure the following: Bucket Name: Name of the Amazon S3 bucket that you want to sync. The connector will sync all supported file types (.docs, .xlsx, and .md), folders, and subfolders within a bucket.
Box	Log in to Box with a user account that has the correct permissions for content you want to sync to Zendesk. Configure the following: Root folders: Root folder that you want to sync to your Zendesk account. You can only select the top level folders in the root directory; you cannot select subfolders or individual files in the root directory. When you select a root folder, the sync automatically includes all subfolders and supported file types (docx, .xlsx, .html, and .md) in that folder. When you set up a Box connection, you select parent folders that reside in the root directory of your Box knowledge base. When the connector syncs, all supported content within that parent folder (including subfolders and supported files) will sync to your Zendesk account.
Confluence	Log in to Confluence with a user account that has the correct permissions for content you want to sync to Zendesk. Configure the following: Confluence site: Confluence site that you want to connect. Spaces: Spaces that you want to connect. Only the first 20 spaces (shown in alphabetical order) appear in the drop-down menu. To select a space that doesn't appear in the menu, begin typing the name of the space in the search box, then select it once it appears. To remove a space, click X on the space tag. Connections to personal spaces in Confluence are not permitted.
Contentful	On the Authenticate tab, configure the following: Contentful Space ID: Identifier for the Contentful space that you want to connect to Zendesk. For more information about finding the Contentful Space ID see the Contentful help center. API key: (Content Delivery API - access token in Contentful) Credential that grants programmatic access to read content stored in your Contentful space. On the Add public URL tab, configure the following: *URL format (required)**: URL format for the public page that hosts your Contentful content. The URL format can be: a field containing the full URL, such as`fields.url` a URL string with one or more placeholders, such as`https://zendesk.com/{fields.slug}` Placeholders can reference entry fields (`fields.<fieldId>`) and entry metadata (`sys.<key>`), such as `sys.id`. The knowledge connector only ingests content that can be associated with a URL. If the URL cannot be constructed from the URL format because required fields are missing, the record is skipped during content syncing.
Document360	On the Authenticate tab, configure the following: Select server: Select the server region where your Document360 account is hosted (EU, US, or Private). If you select Private, you'll also be prompted to enter the subdomain for your Document360 private hosting account. API token: Enter the API token that you created in your Document360 account for this connection. On the Define scope tab, configure the following: Workspace: Select any public workspace that you want to sync. Languages: Select the language for the knowledge base that you want to sync. This connection will only sync Document360 content in the language you specify here. You must create a new connection for each language. Categories: Select the categories that you want to sync. Each category or subcategory you select will appear as a tag within the Categories field. When you select a category, you're only syncing the content that lives at the category level; you're not syncing the subcategories within that category. You must select both the categories and the subcategories that contain the content you want to sync. Each time you create a connection, you must provide a unique API token. When creating API tokens in Document360 for use with Zendesk, be sure to specify GET as the allowed HTTP method. See the Document360 documentation for more information.
Dropbox	Log in to Dropbox with a user account that has the correct permissions for content you want to sync to Zendesk (.docs, .xlsx, .html, and .md.) Select the Root folder that you want to sync to your Zendesk account. You can only select the top level folders in the root directory; you cannot select subfolders or individual files in the root directory. When you select a root folder, the sync automatically includes all subfolders and supported file types in that folder.
Freshdesk	Configure the following: Domain: Current Freshdesk domain. This is the subdomain you chose when you created your account (for example, yourcompany.freshdesk.com). API Key: Freshdesk API key that allows Zendesk to communicate directly with your Freshdesk account. Zendesk only ingests content from the default locale.
Google Drive	Sign in to Google with a user account that has the correct permissions for content you want to sync to Zendesk and allow Zendesk to access your Google Drive files. Select the drives you want to sync. The Google Drive connector supports Google Docs and Sheets. In addition, the Google Drive connector syncs contents from your shared Google Drive. Content from private Google Drives is not synced. You can enroll in the PDF Ingestion EAP to enable syncing of your PDF documents.
Guru	On the Authenticate tab, configure the following: Email: Email address used to access your Guru account. You must be a Guru admin to create a connection, and can only sync content that you have permission to access in Guru. API token: User token associated with your email address in Guru. The user token provides read and write access in Guru based on your existing account permissions. Click Manage > API Access above this field to access the page in Guru where you can generate the user token. For more information, see Leveraging Guru's API in Guru's help center. On the Define scope tab, configure the following: Collection: Guru collection that contains the published content you want to sync.
HubSpot	Log into HubSpot with a user account that has the correct permissions for content you want to sync to Zendesk. Zendesk ingests published blog posts (both internal and public) from all locales.
Jira	Select the JIRA account that you want to sync with your Zendesk account. Enter the following information: Jira site: Enter the Jira site you want to sync. This field displays all Jira sites that you have access to. Each Jira site maps to a single Jira connection. If you want to sync multiple sites, you must create a new connection for each site. Select spaces: Enter the Jira space that you want to sync. This field displays all spaces in the Jira site you selected that you have access to. Each space that you select appears as a tag in the Spaces field. You can remove spaces that you selected in error by clicking the X icon on the space tag. Synced content includes the following: Issue key Summary Description Status Priority Type Labels Comments
Notion	Select your Notion Workspace from the drop-down list in the upper right. Select the pages within your teamspace that you want to sync, then allow access to those pages. Due to limitations with Notion, you can set up only a single Notion connection in your Zendesk account. To add or remove content from this connection, see Adding or removing content from your Notion connection. For pages to be synced to your Zendesk account, they must have content within the body of the page.
Salesforce	Log into Salesforce with a user account that has the correct permissions for content you want to sync to Zendesk. Zendesk ingests the latest version of published articles (both internal and public) from all locales.
SharePoint	Log in to Microsoft with a user account that has the correct permissions for content you want to sync to Zendesk. Select your SharePoint site from the drop-down list. Supported file types are docx, .xlsx, and .md. You can enroll in the PDF Ingestion EAP to enable syncing of your PDF documents.
Zendesk	Enter information required for all connections (public and non-public): Zendesk URL: URL for your Zendesk account If you want to sync non-public content that requires user login, click Turn on, then select one of the following authentication options: OAuth 2.0 (Recommended): Review the permissions, then click Allow. Email and API token: Enter information in the following fields, then click Continue. Email: Email address associated with your Zendesk account. This information is combined with the API token to access and sync your internal content. API token: API token that you can use to sync non-public articles to your Zendesk account. If you leave this field blank, then only content visible to anonymous users will be synced. Select the Locales (optional) for articles you want to sync. Locale for articles that you want to sync. If you leave this field blank, then articles associated with all locales will be synced. If you don't specify an API token with email and locale, then each connection contains the publically available content in the all locales for that subdomain. All published articles that meet this criteria are synced to the connection. If you want to sync content from another Zendesk subdomain, you'll need to add a new connection for that subdomain.
Universal connector	Authentication To configure the connection, enter the following information. Zendesk will send a request to the configured endpoint to verify that it can reach the source and authenticate using the credentials you provided. Name: Identifier that you want to assign to the connection. API URL: API endpoint for the source content. Query parameters: Optional key-value pair appended to the end of the API URL to control the data returned in the endpoint response. You can enter up to five query parameters. To configure a query parameter, select the Query Parameters check box, then enter the Parameter and Value in the fields provided. API key: API key to identify and authenticate Zendesk when making requests to the API. This key is usually generated in your developer or API settings. Field Mappings Field mappings determine how content and metadata returned by the source API are stored as external content in Zendesk. To define how your data appears in Zendesk, configure the following mapping fields: Unique identifier: Required identifier for each item Title: Article heading Body: Content AI features use URL: Public content URL Last updated: When the content last changed Locale: Content language Pagination During synchronization, Zendesk follows the configured pagination strategy until it retrieves all available records. If your source API returns records across multiple pages, select and configure one of the following pagination strategies that corresponds to your source API: Cursor: Uses a unique identifier or token to mark the position in the dataset. When selected, configure the following values: Cursor parameter (required): The query parameter name your API expects on the next request (for example, `cursor`, `after`, or `pageToken`). Zendesk sends this parameter with the cursor value from the previous response. The first request is sent without this parameter. Cursor location in response (required): The dot-notation path to the next cursor value in the JSON response (for example, `meta.next_cursor` or `pagination.next`). Last page detection (optional): The dot-notation path to a boolean field that indicates whether more pages exist (for example, `meta.has_more`). Leave this blank if your API signals the last page by returning a null or empty cursor. Offset: Specifies the starting point in the dataset and the maximum number of records to include on each page. When selected, configure the following values: Page parameter: Parameter that Zendesk sends to request the next page (usually `page`, `offset`, or `skip`. First page value: Value expected by the API. Selecting the wrong value skips the first batch. Next link: API server provides the complete, pre-formatted URL for the next page directly inside its response. When selected, configure the following values: Next link location in response: Where the next page URL sits in the response (usually `next`, `next-page`, or inside a links object. Next link header: Zendesk looks for the `next` keyword in response headers. None: Zendesk fetches all content in one request.