How to use User DB and Audiences via API

This guide is an overview for implementing User Databases or User DB via AdButler's API. For details on the endpoints themselves, check our API documentation for User DB. Further, this feature is not enabled by default. Contact support to enable it in your account.

AdButler's User DB is a great targeting option if you have access to your customers' data. A User DB is a set of attributes that are based on actual user information. Once you've uploaded and configured a user DB, you can create sets of targeting filters based on that database. A set of targeting filters is called an Audience.

Audiences look for your particular set of customers and other visitors with similar attributes, making them more likely to tailor and match ads to actual people.

It might help you to read our interface guide on User DB so you can see how User DBs and Audiences are created using AdButler's UI.

Audiences can be used on their own or with other targeting methods to make your target audience as specific as needed.

In this guide, you will learn about:

  1. Creating User DBs.
  2. Creating Audiences.
  3. Passing Audiences via GET.
  4. Passing Audiences via POST.
  5. Passing Audiences via a tracking pixel.

How to create a User DB

User DBs are based on a CSV file that contains your customers' information.

  1. Name the User DB and identify the id_field_name, which is the column in the CSV file that contains the primary identifier of your customers. The primary ID is important because it's what you will pass in your ad requests to implement Audience targeting.
Make sure to enter the correct column name. You cannot edit User DBs at the moment. If you enter the incorrect column name, you must either make a new User DB or rename the column in the CSV file accordingly.


POST { "name": "customer_data", "id_field_name": "contact_email" }

The response will contain the User DB's ID.

  1. Upload the relevant CSV file, linking it to the User DB by adding the User DB ID to your request.



  "id": "10032",
  "file": "e8aBtMMxD/customer_data.csv"

  1. Create user attributes. You do this by labeling each column in the CSV that you wish to use as a user attribute and identifying its attribute type ("number", "phone_number", "email", "text", "date_time", or "timestamp"). As with the CSV file, you must link these attributes to the User DB by adding the User DB ID to your request.



  "id": "contact_email",
  "label": "customer email",
  "type": "email"

How to create an Audience

An Audience let you filter targets by comparing the values of user attributes to your target values. Each Audience is based on a User DB, which you will reference by adding its ID in your request.

  1. Name the Audience.
  2. Identify the user attributes that will be used, then use operators and operands in each attribute to specify your target.



  "name": "Adult Males",
  "attributes": {
    "gender": {
      "operator": "=",
      "operand": "male"
    "age": {
      "operator": ">=",
      "operand": "18"

Here are the operators that can be used per attribute type:

Attribute Type
= is equal to ALL
!= is not equal to ALL
< is less than "number", "date_time", "timestamp"
<= is less than or equal to "number", "date_time", "timestamp"
> is greater than "number", "date_time", "timestamp"
>= is greater than or equal to "number", "date_time", "timestamp"

How to pass Audiences via GET

Add udb_uid to your request, with its value being the primary ID of the user whose attributes you want to use in targeting.


Query parameters should be added before ;click=CLICK_MACRO_PLACEHOLDER to make sure the request is read correctly. Everything after the ;click= parameter is read as one value. If you do not have a click tracking link, we recommend removing the ;click= parameter. Doing so will also make it easier to add or remove other parameters without affecting your ad's click-throughs.

How to pass Audiences via POST

You can also implement Audience targeting via POST:


"ID": 171230,
"size" : "300x250",
"setID": 373469,
"type" : "json",
"udb_uid" : "123456"

How to pass Audiences via a tracking pixel

Alternatively, you can manually sync users using a tracking pixel, which will add a cookie that marks future ad requests to use the same primary ID for the User DB you're going to invoke.


<img src=""/>

Where id is your AdButler ID, udb is the User DB ID, and uid is the primary ID of the user whose attributes you want to target (same as udb_uid in GET and POST requests).

Ideally, you would place the pixel on the page where users are taken after they log in so that you can retrieve their primary ID. However you decide to implement this, you don't have to include this pixel on every ad request. Having it once per page is enough.

Can't find what you're looking for?

Send us an email

Visit the blog

For more ad serving tips, industry news and AdButler insights.