Use this guide to integrate audience segments with PubMatic. Data owners can create audience segments using:
Data integration requires these steps:
Registering audience segments requires an Audience Source/data partner ID (DPID); see, Create and Edit an Audience Source.
|Register only the new segments you send.|
Data providers must register new segments with source segment IDs before sending data to PubMatic. PubMatic ignores unrecognized segment IDs to avoid processing mistakenly sent data.
There are two ways to register segments:
Register audience segments with the Segment Registration APIs; see, Register an Audience segment.
Bulk-register segments in PubMatic at, Publisher Account > Audience > Audience Segments > Bulk Upload Segments:
You can bulk-register segments by uploading a correctly formatted CSV file. Download the CSV template from PubMatic:
Transfer audience data to PubMatic using one of the following methods:
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.
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 segment IDs to which the user belongs. Each subsequent request for that user with the segid parameter overwrites the user’s already existing segments 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 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:
In this request:
89is the data partner's PubMatic-assigned ID (DPID).
uidtype=0 means the user ID represents a cookie ID.
If your user IDs represent PubMatic cookie IDs, you must first use UID sync .
This request for the same data partner (
dpid=89) and user (
adds segment ID
3242 to the user's existing list.
removes segment ID
123_B from the list.
sets the user's country to
specifies using the UID value as a device ID.
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:
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 audience segments to which the visitor belongs.
Provide the segment ID-to-segment name mapping to PubMatic only once at the start of the integration.
In this request, which updates the entire audience segments list:
89 is the data partner's PubMatic-assigned ID.
B8CB98E6-0FF0-4C2B-A161-4F89155C28F is the PubMatic user ID (from UID sync).
the last known IP of the user:
the user's country:
the user's DMP audience segment IDs:
uidtype=0 specifies 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 audience segments list:
submits the user's last known IP as
sets the user's country as
adds audience segment
3242 to the user's existing list of audience segments.
removes audience segment
123_B, leaving the user's updated audience segments as:
uidtype=1 to specify that the user ID should be handled as a device ID.
For more information on all available parameters, see Data transfer parameters.
Use SFTP to transfer audience segment data to PubMatic within a tab-delimited file, where each row of the file contains the audience segment parameters separated by a tab character, with each row ending with a carriage-return as follows:
[DPID] [TAB] [USERID] [TAB] [SEGID] [TAB] [IP] [TAB] [COUNTRY] [TAB] [UIDTYPE] [CR]
[SEGID] parameter refers to the Source Seg ID that was assigned to the segment during segment registration. You can submit multiple, comma-separated, source segment ID's.
For more information on the other parameters, see Data transfer parameters.
File names follow the pattern:
<MD5SUM>is an MD5 32-character hexadecimal checksum computed on the file content before compression.
If your organization is workload managed by a team, you can also include
<WORKERID> as part of the file name to help track and manage the team member's workload:
Suffix the file with,
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.
The tsv.gz suffix must follow the uploaded file name. Please verify that the file name is correct once upload completes.
103 5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D 4666 184.108.40.206 0
103 34E1EA68-8EDA-4254-9BD0-AB24BCC13914 4666 US 1
Provided separately by PubMatic. Contact your PubMatic account manager with questions.
To use data from other sources when using
Steps for user sync-up:
The data provider must provide PubMatic with an image pixel similar to:
<img src=" http://partner.com/xxxx?id=UID" width=1 height=1>
Use one of the following methods to remove a user from all of their audiences (DMPs and publishers can use either method):
When sharing data via a Server-to-Server (S2S) call or browser redirect mechanism, exclude the segid parameter from the S2S call to PubMatic. See Data transfer parameter reference.
To send a list of segments to remove using the remseg parameter:
When sharing data via a bulk file, do not pass any segment ID in the file for the user record. Audiences in the latest record are stored for the user ID, overwriting the user's previous audiences.
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
StatusOK: Success code from PubMatic. If an error occurs, the response includes codes from PubMatic to identify what may have gone wrong. The table below lists all PubMatic response codes for this API.
|1||Bad request: |
|2||Internal Server Error: demand partner settings not found.|
|3||Bad Request: |
|4||Internal Server Error: failed to validate |
|5||Bad request: unregistered |
|6||Following segments are unregistered: |
|10||Bad request: user |
|11||Bad request: |
|12||Bad request: multiple |
|13||Bad request: multiple |
|15||Bad request: no segments present in this request.|
|16||Bad request: no |
|17||Bad request: |
|18||Bad request. user |