How to perform pain-free bulk updates

4 easy steps for updating your Intercom users in bulk

5 min readNov 24, 2016

Last week we talked about how to handle rate limiting when using the Intercom API. This time, I want to talk about making bulk updates.

I’ll take you through the steps you can follow to make bulk updates to your users via the API. I’m using a recent example to demonstrate, but the same steps will apply to any update you want to make to a large number of users.

Step 1: Retrieving a large number of users

The example I’m using is a recent bulk update we wanted to make on our internal test app for a webinar we ran about custom attributes.

The goal of our example is to check if a user had uploaded an avatar and, depending on whether they have or not, set a boolean custom attribute to ‘true’ or ‘false’ respectively. But you can use these steps to make any attribute changes — for example, updating a ‘subscription’ attribute to reflect a new price or name, or updating another field or company attribute based on an email address.

The first step is to retrieve the list of current users so we can see which of those have up0loaded an avatar. In a previous post we showed some examples of how to use the scroll API to retrieve a large number of users, which we’ll use here.

The first scroll request will be empty to signify a new request and you will not have any scroll parameters. In subsequent requests you’ll need to provide the scroll parameter returned so it can match your request with the remaining users to be retrieved.

As an example, the layout might look something like this (we will talk about errors and other things later):

Step 2: Do the check and save the update

The next thing we need to do is check whether a user has an avatar uploaded, and then set a custom boolean attribute depending on whether that’s true or false.

For our purposes we can check whether there is an avatar URL. If there is, we’ll assume the user has an avatar and if not, they haven’t uploaded one yet.

As an example this might look something like the below (note that we don’t send the entire user object back to Intercom. Just grab the ID to identify the user and the specific attribute you want to update. This makes it more efficient):

Step 3: Do the bulk update and store the ID

Once we have the new user data we’ll want to perform the bulk update and store the resultant bulk ID so we can check the status of our bulk jobs. One way we can do this is using an in-memory data store such as Redis.

Obviously you can use any method you like and either output the IDs to the screen or write them to disk. If you are going to use Redis, you’ll need to have it installed and a server running locally in the context of this example. There is more info on how to do this with Ruby here.

Let’s use the the Redis SADD command, which adds an element to a set, to create a set of bulk IDs and choose a key which groups them by time — we’re using a minute, but you can choose your own time or key for this:

Step 4: Putting it all together and handling errors

Now, we just need to put all this together in a simple script that we can run to perform our updates.

In last week’s post we went through some options for how to handle throttling when using the Intercom API. Let’s use the replies gem we showed there and also check for some scroll-specific errors as well, namely when the scroll parameter already exists and when the parameter cannot be found.

Once you perform a scroll request, the results will be available for one minute before they expire so you can use the returned parameter to retrieve the next page of data and the process starts again.

If you don’t use a scroll parameter, it will assume you want to make a new scroll request and — if the minute window has not elapsed — you’ll receive a ‘scroll already exists’ error. If the minute has elapsed and you use the previous scroll parameter, you’ll receive a ‘scroll parameter not found’ error, since it has timed out.

How you handle these errors is up to you, but in this example I simply wait 60 seconds before making another request, and have set max retries to three to limit the number of time this will occur:

Next Steps

This is just one method of bulk updating your users in Intercom, but in most cases the steps will be similar.

Next time, we’ll build on this example further to explore how you can check the status of your bulk jobs to understand when they have been processed and whether there are any errors.

Thoughts? Questions? Leave us a comment!