> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/integrations-and-data-ingestion/how-to-integrate-with/zendesk.md). # Zendesk ### Overview This integration imports Support Tickets from your Zendesk account into Birdie. Below are key details about what we need to set up the integration and how tickets and data are imported. ### Requirements For Birdie to authenticate with the Zendesk API and import data, you'll need to generate an OAuth access token. The token is used to authenticate API requests. Provide the Birdie team with the following: * Subdomain of your Zendesk account (ex.: subdomain.zendesk.com) * OAuth access token If identification of agents and customers is necessary, Birdie can request additional access to the Sunshine Conversations API. ### Setup in Zendesk {% hint style="warning" %} Zendesk is deprecating API token authentication for the Support API. Starting July 28, 2026, unused API tokens will begin to be automatically deactivated. By April 30, 2027, all API tokens will stop working. OAuth is now the required authentication method. We recommend migrating your integrations to OAuth before the final deadline to avoid service disruption. Read the announcement: [Zendesk Support API token authentication removal announcement](https://support.zendesk.com/hc/en-us/articles/10851263566234-Announcing-the-removal-of-API-tokens-as-an-authentication-method-for-API-requests) {% endhint %} #### Managing OAuth tokens {% hint style="warning" %} Ensure you have administrator access to the Zendesk account used to manage OAuth tokens. {% endhint %} {% stepper %} {% step %} ### Create OAuth Client Use your preferred method (e.g., curl or Postman) to make a POST request to create the OAuth client: ``` curl https://{domain}.zendesk.com/api/v2/oauth/clients.json -X POST -u {user_email}/{user_password} -H "Content-Type: application/json" -d ' { "client": { "name": "Test Client", "identifier": "test_client", "kind": "confidential" } }' ``` {% hint style="info" %} Replace **{domain}**, **{user\_email}** and **{user\_password}** with your Zendesk account information. Customize the name and identifier fields as you wish. {% endhint %} The response should look like this: ``` { "client": { "url": "https://{domain}.zendesk.com/api/v2/oauth/clients/{client_id}.json", "id": {client_id}, "user_id": {user_id}, "name": "Test Client", "identifier": "test_client", "company": null, "description": null, "redirect_uri": [], "secret": {secret}, "created_at": "2006-01-02T15:04:05Z", "updated_at": "2006-01-02T15:04:05Z", "global": false, "logo_url": null, "kind": "confidential" } }// Some code ``` {% hint style="info" %} Save the **client\_id** from this response securely, as it will be required in the next step. {% endhint %} {% endstep %} {% step %} ### Generate OAuth Token Use the **client\_id** from the previous step to request an OAuth token by making a POST request: ``` curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json -X POST -u {user_email}/{user_password} -H "Content-Type: application/json" -d ' { "token": { "client_id": {client_id}, "scopes": [ "read" ] } }' ``` {% hint style="info" %} Replace **{domain}**, **{user\_email}**, and **{user\_password}** with your information and **client\_id** with the identifier obtained when creating the client. {% endhint %} The response should look like this: ``` { "token": { "url": "https://{domain}.zendesk.com/api/v2/oauth/tokens/{token_id}.json", "id": {token_id}, "user_id": {user_id}, "client_id": {client_id}, "token": {token}, "refresh_token": null, "created_at": "2006-01-02T15:04:05Z", "expires_at": null, "used_at": null, "scopes": [ "read" ], "full_token": "{full_token}" } } ``` Save the full\_token securely; this will be used to authenticate API requests.\ \ Share it with the Birdie team [using a secure way](/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration.md). {% endstep %} {% endstepper %} #### Sunshine Conversations API The Zendesk Sunshine Conversations API (Sunshine) provides more robust access and improved data presentation. For Birdie to use this API, an administrator must provide or create credentials within the Zendesk account. {% stepper %} {% step %} ### Create Sunshine Conversations credentials 1. In Admin Center, click Apps and integrations in the sidebar, then select APIs > Conversations API. 2. Click the Create API key button in the top-right corner. 3. Enter a name for your API key and click Next. 4. The App ID, Key ID, and Secret Key will be displayed. The Secret Key is shown only once — copy it and store it securely. 5. Click Next again to go back to the Zendesk API page. 6. If you view the credentials again, the secret key will be displayed in a truncated version. {% endstep %} {% endstepper %} ### Share Connection Details with Birdie To configure the integration, securely provide Birdie with the following information. **For OAuth Token authentication:** ```json { "connection_details": { "subdomain": "your-company", "auth": { "method": "oauth", "api_token": "your-oauth-full-token" } } } ``` | Section | Field | Required | Description | | ------------------------- | ----------- | -------- | -------------------------------------------------------- | | `connection_details` | `subdomain` | Yes | Your Zendesk subdomain (the part before `.zendesk.com`). | | `connection_details.auth` | `method` | Yes | Authentication method, currently only `oauth`. | | `connection_details.auth` | `api_token` | Yes | OAuth full token. | If you want Birdie to use the Sunshine Conversations API, also share the **App ID**, **Key ID**, and **Secret Key** captured in the Sunshine Conversations setup above. [Share credentials securely](https://ask.birdie.ai/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration) with the Birdie team. Never send credentials via email or unencrypted channels. ### Data in scope #### Removal of private comments By default, Birdie only imports tickets with at least one public comment from Zendesk. Public comments are visible to both the end user and the company's agents. Private comments are ignored by default, but the integration can be configured to import private tickets/comments as well. Note: If your team needs to include private or internal tickets in Birdie, this behavior can be configured — contact Birdie to modify the import settings accordingly. #### Ticket import process and update frequency Birdie imports Zendesk tickets by checking the updated\_at field, ensuring the latest modifications are reflected in Birdie. This captures only recent changes without re-importing old data. Birdie also supports imports through Zendesk's Incremental API for cases when ticket content may be updated but the updated\_at field isn't. Note that the Incremental API method does not allow pre-filtering through custom query filters. #### Additional entities for enhanced segmentation Birdie supports importing additional entities associated with tickets to improve segmentation. These imports are disabled by default but can be enabled as needed. * Groups — captures team or department details associated with each ticket (see Zendesk's [Groups documentation](https://developer.zendesk.com/api-reference/ticketing/groups/groups/)). * Users — includes: * Agent: agent identifiers, roles, or other agent-specific data. * Author: detailed info about the ticket requester (e.g., name, contact details). (See Zendesk's [Users documentation](https://developer.zendesk.com/api-reference/ticketing/users/users/)). * Organization — captures company-specific fields, allowing tickets to be linked to specific organizations (See Zendesk's [Organizations documentation](https://developer.zendesk.com/api-reference/ticketing/organizations/organizations)). #### Custom fields If your Zendesk setup includes custom fields for tickets, these fields can be mapped directly into Birdie, preserving your unique data structure. Zendesk custom fields support a variety of data types and allow you to store additional data within tickets beyond standard fields (see Zendesk’s [Ticket Fields documentation](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/)). Once imported, Zendesk custom fields appear as Birdie custom fields, maintaining consistency across both platforms and enabling enhanced segmentation, filtering, and custom workflows in Birdie. ### References * [Creating and using OAuth access tokens with the API](https://developer.zendesk.com/documentation/api-basics/authentication/creating-and-using-oauth-tokens-with-the-api/#creating-an-access-token) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ask.birdie.ai/integrations-and-data-ingestion/how-to-integrate-with/zendesk.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.