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

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

Managing OAuth tokens

Ensure you have administrator access to the Zendesk account used to manage OAuth tokens.

1

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"    
    }  
}'

Replace {domain}, {user_email} and {user_password} with your Zendesk account information. Customize the name and identifier fields as you wish.

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

Save the client_id from this response securely, as it will be required in the next step.

2

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"      
        ]    
    }  
}'

Replace {domain}, {user_email}, and {user_password} with your information and client_id with the identifier obtained when creating the client.

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.

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.

1

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.

Share Connection Details with Birdie

To configure the integration, securely provide Birdie with the following information.

For OAuth Token authentication:

{
  "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 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).

• 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).

• Organization — captures company-specific fields, allowing tickets to be linked to specific organizations (See Zendesk's Organizations documentation).

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).

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