Note: If you're just joining us and are new to coding, be sure to work through Parts One and Two of this tutorial.

Okay, now that we did all the nitty gritty setup, it's time to start coding. If you don't have a Zendesk Support account to test in, I recommend making one now. Let's go through a series of the most requested calls and learn how to make them ourselves. In doing so, we’ll also populate our test account with fake data to play with later.

  • Create a new folder on your desktop called zendesk. We'll save all of our work in this folder.
  • Open a new web page and navigate to your zendesk testing account. Mine is catzomg.zendesk.com, so when I paste code snippets, you may see that or just 'subdomain'.
  • Open up your browser's terminal. Right click and select Inspect Element, then console.

Next, we'll go through each of the following calls to populate our test account with data so we can work with it later:

  • Create 20 users
  • Create 20 tickets
  • Create 20 groups
  • Show all tickets
  • Show all users

You can find all the API documentation by clicking the API Reference link in the top bar of this page.

Creating test users

All documentation for dealing with users can be found here. Have it open in another tab for reference. To create users, we want to make a POST request to /api/v2/users/users.json. Why? Because we’re CREATING data, and if you recall from the earlier chart (that I’m also posting here), we use POST to create data.

What you want to do Method to use
Create POST
Retrieve GET
Update PUT
Delete DELETE

Because we want to create 20 test users in our account, we can write a JavaSript script to do that. Yes, you could use a cURL statement to create a user, but do you want to retype it 20 times? Programming is about doing as much as you can with the smallest effort.

  1. Paste the following script into your browser's terminal:

    for(x=0; x<20; x++) {  var name = "User #" + x;  var email = "User" + x + "@testuser.com";  $.ajax({    url: '/api/v2/users.json',    contentType:'application/json',    type: 'POST',    data: JSON.stringify({user:{name: name, email:email}})  });}
  2. Hit Enter (no changes needed).

  3. If you get POST https://subdomain.zendesk.com/api/v2/users.json 404 (Not Found), it means you're not currently signed in to your account. Go do that now and retry.

  4. If successful, you'll see this (click the triangle next to Object to expand:

    If you ever want to know what your request just did, take a look at the responseText in the console. As you can see, a user was created and all of their information is presented to me, including the fields I didn't bother to supply info for. You'll soon learn just how much you have control over.

  5. Save each script in Sublime Text as {scriptFunction}.js. This one would be createManyUsers.js.

Creating test tickets

The API reference documentation for tickets can be found at Tickets. Have it open in another tab for reference.

To create tickets, we want to make a POST request to /api/v2/tickets.json. And once again, let's run a script that creates 20 different tickets.

  1. Paste the following script into your browser's terminal:

    for(x=0; x<20; x++) {  var title = "Ticket #" + x;  var subject = "Test ticket #" + x;  var body = "This is test ticket #" + x;  $.ajax({    url: '/api/v2/tickets.json',    contentType:'application/json',    type: 'POST',    data: JSON.stringify({"ticket": {"subject": subject , "comment": { "body": body }}})  });}
  2. Save this script in Sublime as createManyTickets.js.

Creating test groups

The API reference documentation for groups can be found at Groups. Have it open in another tab for reference.

To create groups, we want to make a POST request to /api/v2/groups.json. Let's run a script that creates 20 different groups.

  1. Paste the following script into your browser's terminal:

    for(x=0; x<20; x++) {  var name = "Group " + x;  $.ajax({    url: '/api/v2/groups.json',    contentType:'application/json',    type: 'POST',    data: JSON.stringify({group:{name: name}})  });}
  2. Save this script in Sublime as createManyGroups.js.

By now you're probably seeing a pattern in how we're creating all this test data. We start by figuring out how many objects we need, 20 in these cases, and create a for loop.

What are loops?

Loops are handy if you want to run the same code over and over again, each time with a different value. JavaScript supports different kinds of loops:

  • for - loops through a block of code a number of times
  • for/in - loops through the properties of an object
  • while - loops through a block of code while a specified condition is true
  • do/while - also loops through a block of code while a specified condition is true

The for loop

The for loop is often the tool you'll use when you want to create a loop. It has the following syntax:

for (statement 1; statement 2; statement 3) {    code block to be executed}
  • Statement 1 is executed before the loop (the code block) starts. (x = 0)
  • Statement 2 defines the condition for running the loop (the code block). (x < 20, because we only want 20 groups)
  • Statement 3 is executed each time after the loop (the code block) has been executed. (x++, which also means x = x + 1, because we want the counter of x to go up by one after each user/ticket/group creating, and stop only when it hits 20).

When you're ready to write your own loops, read more on loops here, and you can practice your heart away over here.

Show all tickets

So we actually already did this one in the example problem from Part 1, but let’s do it again now that we have newly created tickets!

The API reference documentation for tickets can be found at Tickets. Have it open in another tab for reference.

Because we want to read data, we'll use the GET method. The docs supplies us with the call to make: GET /api/v2/tickets.json.

  1. Open Sublime Text and paste this cURL statement:

    curl https://{subdomain}.zendesk.com/api/v2/tickets.json \  -v -u {email_address}:{password}
  2. Replace the generic fields with your Zendesk Support info. Remember to delete the curly braces; they're not needed to run the call.

  3. Open up your computer's terminal or command line.

    On a Mac, press Cmd + Space Bar, then type 'terminal'.

  4. Paste the edited cURL statement into the terminal and hit Enter.

Show All Users

The API reference documentation for users can be found at Users. Have it open in another tab for reference.

To show our users, we'll format our request the same way we did to show all the tickets in the example above.

We want to make a GET request to /api/v2/users.json.

  • In Sublime Text, edit this cURL statement with your information, and run it in the terminal:

    curl https://{subdomain}.zendesk.com/api/v2/users.json \-v -u {email_address}:{password}

    Your response will look like this:

Magic! We just created and added 20 users, 20 tickets, and 20 groups to our Support account. Now that we have some basic data, it’s time we start playing with it.

The next section of this tutorial will walk you through reading and manipulating data while building a Zendesk Support app!

If you want more practice with common API calls, we've added a bonus section below.

Bonus Section - The Common Calls

Now that we have a solid amount of data in our Zendesk Support account, it's time we learn what we can do with it. The easiest way to do that is to just play with it. We have a short support article here that covers the most common API calls, so we’ll work along with that, but expand it so we can really dive into the API.

Here are the most common tasks performed in Zendesk Support with the API:

Creating tickets with a custom ticket form

One of the most common tasks that our customers perform with the API is creating tickets with a custom ticket form that they use on their own website.

For an end-to-end tutorial, see Building a custom ticket form.

Creating users

Another common use for the API is creating users, which we’ve already done. But what if we want to create users with more details, custom fields, and tags? You can use the Users API to add customers to your Support product.

We'll call POST /api/v2/users.json to create a new user. Our cURL call is all follows:

curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/api/v2/users.json \  -H "Content-Type: application/json" -X POST -d '{"user": {"name": "Roger Wilco", "email": "[email protected]"}}'

What if we want to create a user and set their role? Let's edit the curl statement to reflect that. It'll look like:

curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/api/v2/users.json \  -H "Content-Type: application/json" -X POST -d '{"user": {"name": "Roger Wilco", "email": "[email protected]", "role": "end-user"}}'

Pro tip: How did we know to use “role” and “end-user”, as the ID and value? At the beginning of all of our docs, we list out what IDs and values are accepted for the API in a section called “JSON Format”.

If you're wondering how to get rid of all this test data, take a look at this support article we have on bulk deleting records.

In addition to the APIs mentioned in the common tasks above, the following APIs are also popular with developers.

Play around with these APIs and try making a call for each one! When you feel confident about you've learned, you're ready to move on to Part 4: Let's build an app!, where we'll build an app together!