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 aresource, and the waiter that carries it to you is called anendpoint. 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 theList Users endpoint. It returns a list ofallusers in your Zendesk Support account. Some endpoints like theShow User endpointare 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 theAPI reference sectionof the Zendesk Developer Portal. The reference documentation describes all the available endpoints. You can also use theZendesk developer guideto 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. SeeWorking with JSONin the Zendesk Help Center. You can view the formatted data in a web browser by installing a JSON viewer extension forChromeorFirefox.

JSON looks like this:

{“帖子”:[{" id ": 35467年,“标题”:“我如何打开的n 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 orPostman.

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, seeInstalling and Using cURLin 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, seeInstalling cURLin 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 calledstatus 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 -警告或temporary state, contact support if it persists

SeeResponse Formatin 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 areescalation_oneandescalation_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 theSearch API endpoint. This endpointdoes notfilter 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}

重要的: Make sure to replace "subdomain" with your account subdomain.

The search API is very flexible and the query can use anything outlined in theZendesk 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 withbothof 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 thereference documentationand theZendesk developer documentation.