Admin's guide to the Zendesk API

What is the Zendesk API?

An API, or Application Programming Interface, is a tool for software applications. If you think of a restaurant, the waiter carries dishes from the kitchen to your table. The API works in a similar way: It takes data from one point to another. In the API, the dish is called a resource, and the waiter that carries it to you is called an endpoint. Think of a specific dish you might request at the restaurant. Some endpoints bring you back a collection of items like a sampler platter. An example of this in the API would be the List Users endpoint. It returns a list of all users in your Zendesk Support account. Some endpoints like the Show User endpoint are more focused and just return a single thing.

You can also use the API to make changes to things in Zendesk. Imagine telling a waiter how you'd like your steak cooked. The chef will actually change the steak to suit you. The API is a powerful resource that many of our customers use to bulk-import resources, create apps, pull data to external sources, and more.

Most of the reference documentation for the Zendesk API is available in the API reference section of the Zendesk Developer Portal. The reference documentation describes all the available endpoints. You can also use the Zendesk developer guide to get started. While the documentation is comprehensive, we'll be going over how to decode and use them in this article.

Why use the API?

Now that you know what the API is, you may be wondering, "Why should I care?" In a nutshell, you can use the API to add functionality that's not available in the UI (either natively or at your plan level) at a much faster pace than attempting to do it all by hand.

For accounts currently on the Essential or Team plans, using the API allows you to have a direct method for exporting your data without needing to upgrade to Professional, (which allows for automated data exports). Similarly, you may use the API to get ticket data for reporting purposes. The API can return all information related to a ticket, so you may use the API output to pass data into a third party reporting application.

The ability to quickly update many records is another benefit of using the API. For example, while you're only able to create a single organization at a time in the agent interface, you could create up to 100 organizations at a time with the API. In the same vein, the restrictions on how many items you can update at a time is higher with the API. The interface allows for 60 tickets to be edited at once, while the API allows up to 100 tickets.

Other common tasks include:

• Creating tickets
• Migrating ticket data into Zendesk from another system
• Editing users in bulk
• Searching records
• And many more!

Now that we've outlined why you'd want to use the API, let's look at how to make an API request.

Format

The Zendesk API returns data in a lightweight format called JSON. See Working with JSON in the Zendesk Help Center. You can view the formatted data in a web browser by installing a JSON viewer extension for Chrome or Firefox.

JSON looks like this:

{
  "posts": [
    {
      "id": 35467,
      "title": "How do I open the safe"
    },
    {
      "id": 35468,
      "title": "How do I reset the combination?"
    },
  ]
}

A typical endpoint looks like this:

subdomain.zendesk.com/api/v2/users/me.json

Endpoints can perform the following actions:

• GET - Retrieve items 
• POST - Create items that didn't exist before
• PUT - Update existing items
• DELETE - Remove items

In a browser, you can only make GET requests. You can perform the other actions using tools like cURL or Postman.

cURL

The reference documentation uses cURL in all the endpoint examples. cURL is a command-line tool that lets you try API commands without a browser. For more information, see Installing and Using cURL in the Zendesk Help Center. You can use cURL for any of the 4 types of calls. It comes pre-installed on a Mac, but you'll need to install it in Windows. For instructions, see Installing cURL in the Zendesk Help Center.

Status of your requests

For every API request you make, you receive a response that lets you know if it worked or not. If not, the response will provide clues as to why the request didn't work. These responses are called status codes. Some of the basic ones are as follows:

• 200 - The request was successful
• 400 - Request was unsuccessful
• 409 - Merge or constraint error, try the call again
• 422 - Un-processible Entity
• 429 - Rate limit has been exceeded
• 500 - Warning or temporary state, contact support if it persists

See Response Format in the API docs for more details about the status codes.

Practice

Now that we've walked through the basics of an API, let's actually use it to search through our tickets.

Let's say I'm a user on the Team level plan and I've been using tags to track when tickets are escalated to different levels of support. The tags I add are escalation_one and escalation_two.

Now, I want to generate a report of every ticket in my system that has ever hit both escalations. I tried to make a view to return these tickets, but this did not meet my needs because archived tickets were not shown. What do I do now?

Answer: Use the API to get the tickets!

To do so, you'll want to check out the Search API endpoint. This endpoint does not filter out archived tickets, so you can use it to return a list of all tickets that include these two tags. Similarly, the Search API is a simple GET call, so you can use it directly in your browser if you're signed in to Zendesk Support on another tab in the browser. The format of the Search endpoint is as follows:

subdomain.zendesk.com/api/v2/search.json?query={search_string}

Important: Make sure to replace "subdomain" with your account subdomain.

The search API is very flexible and the query can use anything outlined in the Zendesk Search reference. In our example, since we're simply looking for tags, the only parameter we'll use in our search string is "tags". To search for multiple tags, simply add a comma between the tags after the "tags" parameter. Your call should now look like:

https://subdomain.zendesk.com/api/v2/search.json?query=tags:escalation_one,escalation_two

To authenticate the request, make sure you're an agent or an administrator, and that you're signed in to Zendesk Support on another tab in your browser.

Running this call in your browser will return a list of tickets with both of these tags. You can then save the JSON output for future use.

Congratulations! You've made it to the end! The API is a powerful tool with plenty of uses. From here you can start delving further into the reference documentation and the Zendesk developer documentation.