Use this guide to integrate audiences with PubMatic. Data owners can create audiences using:
- Cookie IDs for mobile and desktop/web.
- iOS IDFA/Android device IDs for mobile apps.
- Custom IDs from ID providers who are integrated with PubMatic; contact your PubMatic account manager for details.
Data integration requires these steps:
Audience source creation
Registering audiences requires an Audience Source/data partner ID (DPID); see, Create and Edit an Audience Source.
|Register only the new audiences you send.|
Data providers must register new audiences with source audience IDs before sending data to PubMatic. PubMatic ignores unrecognized audience IDs to avoid processing mistakenly sent data.
There are two ways to register audiences:
Register audiences with the Audience Registration APIs; see, Register an Audience.
Bulk-register audiences in PubMatic at, Publisher Account > Audience > Audiences > Bulk Upload Audiences:
You can bulk-register audiences by uploading a correctly formatted CSV file. To download the CSV template from PubMatic:
- Click the Bulk Upload Audiences drop-down (circled in red above), then choose the Bulk Upload Audiences menu item.
- In the Upload Audiences dialog click, Download Create Template, which is the one you use to create your audiences. When it's time to update your audiences, then you would use the Download Update Audiences template.
- After you've filled in the template with your audience data (note the required fields), then return to the Upload Audiences dialog and click Select File.
- When the Upload Audiences dialog displays the name of your template file, click Upload Audiences to send it to PubMatic and close the dialog.
Transfer audience data to PubMatic using one of the following methods:
- Server-to-server (S2S) data transfer
- Browser-side real-time (HTTP 302 redirect) data transfer
- Bulk audience data transfer using SFTP
PubMatic automatically removes user IDs older than 30 days. The best practice is to refresh data at least every 25 days.
The transfer options listed above require data submission using a specific set of parameters listed in the table below.
Data transfer parameters
PubMatic data partner ID (DPID) assigned to the data partner at time of integration.
The PubMatic user ID passed to the data partner by PubMatic.
A integer value that determines what the identity partner's PubMatic user ID represents:
Use segid to send the complete list of audience IDs to which the user belongs. Each subsequent request for that user with the segid parameter overwrites the user’s already existing audiences list.
DO NOT send
You can include
You can include
Last known IP address of the user; optional when you send
Two-letter code for the user's country; for example,
Server-to-server (S2S) data transfer
Server-to-server data transfer is the best practice for submitting data to PubMatic since the servers communicate directly, so data transfer is highly-efficient. Build API calls using the parameters from the data transfer parameter table and make HTTP calls to the API endpoint:
Sample: standard call with audience IDs
In this request:
89is the data partner's PubMatic-assigned ID (DPID).
- The user belongs to three audiences with IDs
uidtype=0means the user ID represents a cookie ID.
If your user IDs represent PubMatic cookie IDs, you must first use UID sync .
Sample: appending/removing audiences
This request for the same data partner (
dpid=89) and user (
adds audience ID
3242to the user's existing list.
removes audience ID
123_Bfrom the list.
sets the user's country to
specifies using the UID value as a device ID.
Browser-side real-time (HTTP 302 redirect) data transfer
Data partners who do not support server-to-server data transfer can pass data to PubMatic using browser-side real-time data transfer for each visitor as follows:
- A user visits the website using a browser, which upon loading, executes the PubMatic pixel.
- The PubMatic pixel invokes the data partner's pixel or URL to request the audience data for this visitor. To reduce the latency, this request is sent to the data partner only once in a pre-configured time interval per user; for example, once per day.
The data partner's system then redirects to the PubMatic Data Ingestion API using the HTTP 302 redirect. PubMatic shared the API URL with the data partner before the start of the integration. While redirecting to the API URL, the data partner's system must include all the IDs of the audiences to which the visitor belongs.
Info title Data partner must also
Provide the audience ID-to-audience name mapping to PubMatic only once at the start of the integration.
Browser-side sample requests
In this request, which updates the entire audiences list:
89is the data partner's PubMatic-assigned ID.
B8CB98E6-0FF0-4C2B-A161-4F89155C28Fis the PubMatic user ID (from UID sync).
the last known IP of the user:
the user's country:
the user's DMP source audience IDs:
uidtype=0specifies that the user ID should be handled as a cookie ID (use UID sync when passing
This request is also for data partner
89 and user ID
B8CB98E6-0FF0-4C2B-A161-4F89155C28F. It removes and appends values to the audiences list:
submits the user's last known IP as
sets the user's country as
3242to the user's existing list of audiences.
123_B, leaving the user's updated audiences as:
uidtype=1to specify that the user ID should be handled as a device ID.
For more information on all available parameters, see Data transfer parameters.
Bulk audience data transfer using SFTP
Use SFTP to transfer audience data to PubMatic within a tab-delimited file, where each row of the file contains the audience parameters separated by a tab character, with each row ending with a carriage-return as follows:
For more information on the other parameters, see Data transfer parameters.
File name format
File names follow the pattern:
If your organization is workload managed by a team, you can also include
PubMatic supports compression formats such as, gzip , bzip2 , and others. If you have any questions or issues uploading a compressed file, please contact your PubMatic account manager for assistance.
SFTP server details and access
Provided separately by PubMatic. Contact your PubMatic account manager with questions.
Unique identifier (UID) sync
Steps for user sync-up:
Remove a user from audiences
Use one of the following methods to remove a user from all of their audiences (DMPs and publishers can use either method):
API response codes
Once your API request has been processed by PubMatic, the system returns a response to let you know whether the request was successful or a problem occurred. When you send the request, the following happens at the HTTP layer:
A successful request also includes a