Zendesk

Configuration

Zendesk source connector integrates with the Zendesk API to extract and synchronize data.

Connects to your Zendesk instance to sync tickets, comments, users, orgs, and attachments.

Explore the Zendesk connector implementation

Authentication

This connector uses OAuth 2.0 with custom credentials. You need to provide your OAuth application’s Client ID and Client Secret, then complete the OAuth consent flow.

OAuth Setup Required

Create an OAuth application in your provider’s developer console
Enter your Client ID and Client Secret when configuring the connection
Complete the OAuth consent flow

Configuration Options

The following configuration options are available for this connector:

Configuration Parameters

Zendesk configuration schema.

subdomain

strRequired

Your Zendesk subdomain only (e.g., ‘mycompany’ NOT ‘mycompany.zendesk.com’)

exclude_closed_tickets

Optional[bool]

Skip closed tickets during sync (recommended for faster syncing)

Data Models

The following data models are available for this connector:

ZendeskTicketEntity

Schema for Zendesk ticket entities.

Reference: https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/

Field	Type	Description
ticket_id	int	Unique identifier of the ticket
subject	str	The subject of the ticket
description	Optional[str]	The description of the ticket (first comment)
requester_id	Optional[int]	ID of the user who requested the ticket
requester_name	Optional[str]	Name of the user who requested the ticket
requester_email	Optional[str]	Email of the user who requested the ticket
assignee_id	Optional[int]	ID of the user assigned to the ticket
assignee_name	Optional[str]	Name of the user assigned to the ticket
assignee_email	Optional[str]	Email of the user assigned to the ticket
status	str	Current status of the ticket
priority	Optional[str]	Priority level of the ticket
tags	List[str]	Tags associated with the ticket
custom_fields	List[Dict[str, Any]]	Custom field values for the ticket
organization_id	Optional[int]	ID of the organization associated with the ticket
organization_name	Optional[str]	Name of the organization associated with the ticket
group_id	Optional[int]	ID of the group the ticket belongs to
group_name	Optional[str]	Name of the group the ticket belongs to
ticket_type	Optional[str]	Type of the ticket (question, incident, problem, task)
url	Optional[str]	URL to view the ticket in Zendesk

ZendeskCommentEntity

Schema for Zendesk comment entities.

Reference: https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-comments/

Field	Type	Description
comment_id	int	Unique identifier of the comment
ticket_id	int	ID of the ticket this comment belongs to
ticket_subject	str	Subject of the ticket this comment belongs to
author_id	int	ID of the user who wrote the comment
author_name	str	Name of the user who wrote the comment
author_email	Optional[str]	Email of the user who wrote the comment
body	str	The content of the comment
html_body	Optional[str]	HTML formatted content of the comment
public	bool	Whether the comment is public or internal
attachments	List[Dict[str, Any]]	Attachments associated with this comment

ZendeskUserEntity

Schema for Zendesk user entities.

Reference: https://developer.zendesk.com/api-reference/ticketing/users/users/

Field	Type	Description
user_id	int	Unique identifier of the user
email	str	Email address of the user
role	str	Role of the user (end-user, agent, admin)
active	bool	Whether the user account is active
last_login_at	Optional[Any]	When the user last logged in
organization_id	Optional[int]	ID of the organization the user belongs to
organization_name	Optional[str]	Name of the organization the user belongs to
phone	Optional[str]	Phone number of the user
time_zone	Optional[str]	Time zone of the user
locale	Optional[str]	Locale of the user
custom_fields	List[Dict[str, Any]]	Custom field values for the user
tags	List[str]	Tags associated with the user
user_fields	Dict[str, Any]	User-specific custom fields

ZendeskOrganizationEntity

Schema for Zendesk organization entities.

Reference: https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/

Field	Type	Description
organization_id	int	Unique identifier of the organization
domain_names	List[str]	Domain names associated with the organization
details	Optional[str]	Details about the organization
notes	Optional[str]	Notes about the organization
tags	List[str]	Tags associated with the organization
custom_fields	List[Dict[str, Any]]	Custom field values for the organization
organization_fields	Dict[str, Any]	Organization-specific custom fields

ZendeskAttachmentEntity

Schema for Zendesk attachment entities.

Reference: https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/

Field	Type	Description
attachment_id	int	Unique identifier of the attachment
ticket_id	Optional[int]	ID of the ticket this attachment belongs to
comment_id	Optional[int]	ID of the comment this attachment belongs to
ticket_subject	Optional[str]	Subject of the ticket this attachment belongs to
content_type	str	MIME type of the attachment
file_name	str	Original filename of the attachment
thumbnails	List[Dict[str, Any]]	Thumbnail information for the attachment

Setting Up Your Zendesk OAuth Application

Zendesk requires you to create your own OAuth application (BYOC - Bring Your Own Credentials) to connect with Airweave. Follow these steps to set up your OAuth client:

Step 1: Create OAuth Client in Zendesk

Log into your Zendesk Admin Center
Navigate to Apps and integrations → APIs → OAuth clients
Click Add OAuth client on the right side

Step 2: Configure OAuth Client

Fill out the OAuth client form with the following details:

Name

stringRequired

Example: Airweave

This name will be shown to users during the authorization flow.

Description

string

Example: Airweave connector for syncing Zendesk data

Optional description visible during authorization.

Company

string

Example: Your Company Name

Helps users understand who they’re granting access to.

Identifier

stringRequired

Example: airweave

This becomes your Client ID. You can use the auto-generated value or customize it.

Type client

enumRequired

Must be: Confidential

Important: Select “Confidential”, not “Public”. Public clients will not work with Airweave.

Redirect URLs

stringRequired

Enter your Airweave callback URL. Use the appropriate URL for your environment:

Production: https://api.airweave.ai/source-connections/callback
Local: http://localhost:8001/source-connections/callback

The redirect URL must match exactly (including protocol and trailing slashes). For localhost, http:// is required.

Step 3: Save and Generate Secret

Click Save
After saving, a Secret field will appear with your client secret
Copy the entire secret immediately - it will only be shown once in full
Click Save again to finalize

Security Note: The client secret will only be displayed fully once. After clicking Save, you’ll only see the first 9 characters. Store it securely!

Step 4: Activate the OAuth Client

Find your OAuth client in the OAuth clients list
Change the Status from Inactive to Active
Save the changes

The OAuth client must be in “Active” status to accept authorization requests. If it’s inactive, you’ll receive an “Invalid Authorization Request” error.

Step 5: Configure in Airweave

When creating a Zendesk connection in Airweave, you’ll need to provide:

Subdomain: Your Zendesk subdomain only (e.g., mycompany NOT mycompany.zendesk.com)
Client ID: The identifier you set in Step 2
Client Secret: The secret you copied in Step 3

Example Configuration

1 {
2   "config": {
3     "subdomain": "mycompany"
4   },
5   "authentication": {
6     "client_id": "airweave",
7     "client_secret": "your-secret-here"
8   }
9 }

Troubleshooting

Invalid Authorization Request Error

Cause: Your OAuth client is inactive or misconfigured.

Solution:

Verify the OAuth client status is “Active”
Ensure the client type is set to “Confidential”
Check that the redirect URL exactly matches your Airweave callback URL

Client Secret Not Working

Cause: Incomplete secret copied or secret regenerated.

Solution:

Make sure you copied the entire secret (it may extend past the visible text box)
If needed, click the “Regenerate” button to generate a new secret
Copy the new secret immediately and update it in Airweave

Redirect URI Mismatch

Cause: The redirect URL in your OAuth client doesn’t match Airweave’s callback URL.

Solution:

Verify the redirect URL is exactly: https://api.airweave.ai/source-connections/callback
Check for trailing slashes, protocol (http/https), and exact domain match
For local development, ensure you’re using http:// not https://

Required Scopes

Airweave requires the following Zendesk OAuth scopes:

read - Read access to tickets, users, organizations, and comments
write - Write access for updating ticket data (optional, for future features)

These scopes are automatically included in the authorization request.