From 100 Requests to 1: Introducing Our New Bulk and Batch APIs

Each day, millions of customer profiles are created on the Zendesk platform. Businesses have a need to regularly supplement these customer records with new information from other systems to provide their support teams with the freshest context about a customer.

We're very excited to announce that we now provide a set of new APIs for bulk and batch editing resources like users, organizations, organization memberships, and tickets. This will make it easier and more efficient to import, update and retrieve many resources through our API. This post will give a brief overview of what we've done and also some examples.

Brand New APIs

Until now, it was often necessary to make an API call to Zendesk for each object being synchronized. This was slow, and high volume API consumers with a need to update hundreds of thousands of users often reached our API rate limit. With these new API endpoints, 100 API calls or more can often be replaced with a single API call.

All of the following APls (except for show_many) will create an asynchronous background job to do the work, and return a job ID. You can then use the Job Statuses API to check for completion of the job later.

new_adds

Use External IDs

We know that businesses often use external ID as a reference to users/organizations in Zendesk based on their internal unique identifier for their customers. It's often easier to use this ID to manipulate records in Zendesk instead of the ID assigned by Zendesk.

We've updated our APIs to handle actions on resource identified by external_id. Now, when updating or deleting many users/organizations, there is no need to try and get the Zendesk assigned IDs first. Simply pass in external_ids, and it works!

Use curl with proper resources and external_ids.

curl https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json?external_ids=external_1,external_2 \  
-H "Content-Type: application/json" -X PUT\  
-v -u {email_address}:{password} \  
-d '{"organization": {"notes": "Something interesting"\}\}'

It returns a Job Status with id and enqueues the job first.

{
  "job_status":{
     "id":"7ba76910ca9f0132378a6cf4bbcdedd1",
     "url":"https://{subdomain}.zendesk.com/api/v2/job_statuses/7ba76910ca9f0132378a6cf4bbcdedd1.json",
     "total":null,
     "progress":null,
     "status":"queued",
     "message":null,
     "results":null
  }
}

Searching for users by External ID

To find a Zendesk user by external_id, developers have used this endpoint in the past:

GET /api/v2/search.json?external_id={external_id}

This was needed to get the Zendesk user ID associated with a particular user, in order to make further API calls regarding that user, or even just to determine whether that user already existed in Zendesk.

Now, you can use the Show Many Users endpoint to retrieve many users at once by external_id:

GET /api/v2/users/show_many.json?external_ids={external_ids}

Batch Update Individual Resources

Instead of updating resources all by the same request body, we've made our APIs more flexible. You can now update multiple users or organizations in a single API request, with each record identified by either an id or an external_id.

Use curl with two different updates for organizations identified by id = 1, and external_id = 2.

https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json \  
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password} \  
-d '{"organizations": [{"id": "1", "notes": "Something interesting"}, {"external_id": "2", "notes": "Something even more interesting"}]}'

It returns a Job Status with id and enqueues the job first as well.

{
  "job_status":{
     "id":" 2d318d60ca9f013245670242ac110044",
     "url": "https://{subdomain}.zendesk.com/api/v2/job_statuses/2d318d60ca9f013245670242ac110044.json",
     "total":null,
     "progress":null,
     "status":"queued",
     "message":null,
     "results":null
   }
}

Checking Status of Multiple Jobs

The Job Status API now has the ability to Show Many Job Statuses in a single request:

GET /api/v2/job_statuses/show_many.json?ids={ids}

This enables you to check on the status of multiple background jobs in a single API call, instead of querying them one by one. In your integration with Zendesk, you can add all background job IDs you are tracking to a list, and then query the job status for all of them periodically in a single call.

Limit for a Single API Call

While the goal of these new APIs is to enable you to import and update thousands or even millions of objects in Zendesk, it's important to chunk your data up into reasonable sizes for each request. Generally, the limit is 100 items per request. Passing in more items will result in a 400 Bad Request error.

Need more details and examples? Please look at our REST API documentation for Users, Tickets, Organizations, and Organization Memberships.

Have fun :){{}}