Dart at the centre of a dartboard in a spotlight

Manage Remarketing Lists via API

Remarketing lists are a valuable tool in any PPC manager’s toolkit. In general, they allow you reach out specifically to potential customers that already had one or more touch points with your website.

In this post, I will shed some light on how to manage remarketing lists via API, as it can be quite tedious to do this manually. In addition, the generally elaborate AdWords API documentation is a bit sparse on this topic. If you want more information on RLSA in general, there’s some useful information to be found in the google AdWords help.

I will use the programming language Ruby for code examples. However, the basic concepts are the same for other languages like Java or Python. This post will show you how to:

  • retrieve all ad groups for a given AdWords campaign id
  • get remarketing lists and their bid modifiers for those ad groups
  • change the bid modifiers for the lists
  • add remarketing lists to ad groups

The methodology also applies, if you want to add remarketing lists directly on the campaign level.


In order to work with the AdWords API, you need to have an AdWords account (a test account is sufficient) as well as an AdWords developer token. You should also have a working OAuth2 Token. The AdWords examples section shows how to get this token, so I won’t explain it here.

Whenever you see an AdWords service like ad_group_service in the examples, it has been created like this:


How To Do It

Remarketing lists are modeled as criteria in google land. You can add, modify and remove them for an ad group via the AdGroupCriterionService.

Before we work with the lists themselves, we have to get the corresponding ad groups for our campaign. You will need a campaign id, which you can find in the AdWords interface, as seen below.

AdWords interface

You will also need at least one list ID. You can find it at the detail page of a specific audience in the AdWords interface:

AdWords interface2

Getting Ad Groups for Campaign

First, we have to get the ad groups for a given campaign ID via the AdGroupService.

Getting all ad groups for a campaign_id works like this:


(click on the picture to get the code as pdf)

Get Existing Remarketing Lists For Ad Groups

When you have the ad groups, you can retrieve all existing remarketing lists for those ad groups:


The resulting entries are an array of list criteria with the following form:


This will return all connected remarketing lists. We want only those, that match our list. Fortunately, we have a list ID! So we can filter the entries.

With the gathered information, we can separate our ad groups into two: Those that already have the list and those that don’t. We want to update the bid modifier for the first ones (if necessary) and add the list to the latters.

In both cases, we need to call the AdGroupCriterionService again:

Add/ Update Bid Modifier:

Hint The bid modifier is a floating point number. The value 1 indicates, that the bid should not be modified. You can think of 1 as being 100%. That means, when you want to do the equivalent of adding a bid modifier of 20% via the AdWords UI, the correct value is 1.2, not 0.2.

In order to update an existing bid modifier, you have to perform


Hint: As the mutate methods takes an array of operations, you can and should perform more than one operation a time.

Adding new remarketing lists with bid modifiers works as following:


Hint Please note the difference in the user list criterion definition: when adding, the list id goes by user_list_id. When updating the bid modifier, it’s just supposed to be id.

As mentioned previously, you don’t have to manage remarketing lists on an ad group level. You can also do it on a campaign level. The code examples should more or less work directly by replacing AdGroupCriterionService by CampaignCriterionService.

I hope you find this little tutorial helpful. Let me know how it goes!

[shareaholic app="share_buttons" id="19406647"]


Udo Gröbner

Developer at the crealytics innovation hub. Interested in new technologies, pragmatic solutions and stuff that works.

    Find more about me on:
  • googleplus
  • linkedin