Introduction to the Zendesk API

An API, or Application Programming Interface, is a tool for software applications that acts as an intermediary and allows them to talk to one another. Each time you use an app like Zendesk, send an instant message, or check the weather on your phone, you’re using an API.

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.

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 Rest API section of the Zendesk Developer Portal, which describes all the available endpoints.

Why use the API?

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, whichlooks 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 the API console on the Zendesk Developer Portal.

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 most common 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 Codes in the API docs for more details about the status codes.