Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Use this guide to integrate audience segments audiences with PubMatic. Data owners can create audience segments 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:

  1. Audience Source creation
  2. Segment Audience registration
  3. Data transfer



source creation

Registering audience segments audiences requires an Audience Source/data partner ID (DPID); see, Create and Edit an Audience Source.


Audience registration

titleRegister segments audiences ONLY ONCE before data transfer
Register only the new segments new audiences you send.

Data providers must register new segmentsaudiences with source segment audience IDs before sending data to PubMatic. PubMatic ignores unrecognized segment audience IDs to avoid processing mistakenly sent data.

There are two ways to register segmentsaudiences:

  1. Register audience segments audiences with the Segment Audience Registration APIs; see, Register an Audience segment.

  2. Bulk-register segments audiences in PubMatic at, Publisher Account > Audience > Audience Segments Audiences > Bulk Upload SegmentsAudiences:

You can bulk-register segments by uploading a correctly formatted CSV file. Download the CSV template from PubMatic:Image Removed-register audiences by uploading a correctly formatted CSV file. To download the CSV template from PubMatic:

  1. Click the Bulk Upload Audiences drop-down (circled in red above), then choose the Bulk Upload Audiences menu item.
  2. 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.
  3. 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.
  4. When the Upload Audiences dialog displays the name of your template file, click Upload Audiences to send it to PubMatic and close the dialog.

Data transfer

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.












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:

  •     0 = UID represents a PubMatic cookie ID. Note: when using uidtype=0, you must first perform the UID sync step below.
  •     1 = UID represents a device ID.
  •     A different identity partner ID registered with PubMatic.
titleuidtype is now required for all new integrations

Contact your PubMatic account manager to learn more about UID Type assignment and other identity partners supported by PubMatic.


string array



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 audiences list.

DO NOT send segid in a request that also includes the addseg or remseg parameters.

Omitting segid removes the entire list of the user's audience segmentsaudiences; see, Remove a user from audiences.


string array



Use addseg to send:

  • A complete list of comma-separated segment audience IDs to replace the user's current segmentsaudiences.
  • A list of new segments audiences to append to the user’s current segmentsaudiences.

You can include addseg and remseg in the same request, but DO NOT send segid along with these parameters.





Use remseg to send:

  • A complete list of comma-separated segment audience IDs to replace the user's current segmentsaudiences
  • A list of segments audiences to remove from the user’s current segmentsaudiences.

You can include remseg and addseg in the same request, but DO NOT send segid along with these parameters.





Last known IP address of the user; optional when you send country in the request. Omit this parameter from the request if the user's last IP address is unknown.





Two-letter code for the user's country; for example,  US, IN, CA; optional when you send the last known ip in the request. Exclude this parameter from the request if the user's country is unknown. If both country and ip are omitted, country defaults to US.


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:

Code Block

Sample: standard call with


audience IDs

In this request:

  • 89 is the data partner's PubMatic-assigned ID (DPID).
  • The user belongs to three audience segments audiences with IDs 123_B, 98901, and 4532.
  • uidtype=0 means the user ID represents a cookie ID.


    If your user IDs represent PubMatic cookie IDs, you must first use UID sync .

Code Block,98901,4532&country=US&uidtype=0

Sample: appending/removing



This request for the same data partner (dpid=89) and user (userid=B8CB98E6-0FF0-4C2B-A161-4F89155C28F):

  • adds segment audience ID 3242 to the user's existing list.

  • removes segment audience ID 123_B from the list.

  • sets the user's country to US.

  • specifies using the UID value as a device ID.


  1. A user visits the website using a browser, which upon loading, executes the PubMatic pixel.
  2. The PubMatic pixel invokes the data partner's pixel or URL to request the audience segment 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.
  3. 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 audiences to which the visitor belongs.

    title Data partner must also

    Provide the segment audience ID-to-segment audience name mapping to PubMatic only once at the start of the integration.


In this request, which updates the entire audience segments audiences 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: US.

  • the user's DMP source audience segment IDs: 123_B, 98901, and 4532.

  • uidtype=0 specifies that the user ID should be handled as a cookie ID (use UID sync when passing uidtype=0).

Code Block,98901,4532&uidtype=0

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 audiences list:

  • submits the user's last known IP as

  • sets the user's country as US.

  • adds audience segment 3242 to the user's existing list of audience segmentsaudiences.

  • removes audience segment 123_B, leaving the user's updated audience segments audiences as: 98901,4532,3242.

  • Sets 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.

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:

Code Block




 parameter refers to


the Source Seg ID


 that was assigned to the


audience during audience registration. You can submit multiple, comma-separated, source


audience ID's.

For more information on the other parameters,


see Data transfer parameters.

titleYou must provide either

[IP] (last known IP address) or [COUNTRY] (two-letter country code). If [IP] is unknown, add two TABs between [SEGID] and [COUNTRY] with no additional blank/space characters. If neither [IP] nor [COUNTRY] are added to the entry, PubMatic will set the [COUNTRY] to US by default.

File name format

File names follow the pattern:

  • format should be Unix; for example, 1596695461984.
  • <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:


titleWhile the transfer is in progress

Suffix the file with, * .UPLOADING, then rename it upon completion.

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.

Sample entries

Code Block
103 5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D 4666 0

Code Block
103 34E1EA68-8EDA-4254-9BD0-AB24BCC13914 4666 US 1

titleBulk transfer notes
  1. FTP lets a single user batch upload data for multiple partners, while HTTP allows data for only a single partner.
  2. HTTP lets a DMP add/remove a
  1. audience for a given user id, but FTP requires the DMP to send all the user's
  1. audience IDs, which overrides the existing
  1. audience stored with PubMatic.
  2. FTP allows only one new line entry for each
  1. audience for a given user.

SFTP server details and access

Provided separately by PubMatic. Contact your PubMatic account manager with questions.

Unique identifier (UID) sync

titlePubMatic can process data only from PubMatic user IDs

To use data from other sources when using uidtype=0, a data provider must create a user-match table between PubMatic's user IDs and their own user IDs.

Steps for user sync-up:

  1. The data provider must provide PubMatic with an image pixel similar to: 

        <img src="" width=1 height=1>

  2. If data comes from a publisher, then PubMatic incorporates the image pixel from step 1 in a PubMatic pixel. The publisher must fire the PubMatic pixel across their website to maximize coverage across their users. Firing the pixel also lets the data provider create the match-table.
  3. If data comes from a buyer, PubMatic fires the image pixel from step 1 across PubMatic's site.

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):

  1. When sharing data via


  1. Server-to-Server (S2S) call


  1.  or browser redirect mechanism, exclude the segid parameter from the S2S call to PubMatic.


  1. See Data transfer parameter reference.


    Code Block[Identity_Partner_ID]


    To send a list of


  1. audiences to remove using the remseg parameter: 

    Code Block,3242&uidtype=[Identity_Partner_ID]

  2. When sharing data via a bulk file, do not pass any


  1. audience 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.

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:

  • Returns HTTP response code 200 (Ok) when the request successfully completes.
  • Returns HTTP response code 400/500 if issues occur while processing the data. 

A successful request also includes


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.

1StatusBadRequestBad request: uidType passed multiple times.
2StatusInternalServerErrorInternal Server Error: demand partner settings not found.
3StatusBadRequestBad Request: uidtype parameter not passed.
4StatusInternalServerErrorInternal Server Error: failed to validate uidType.
5StatusBadRequestBad request: unregistered uidType.


audiences are unregistered: [list of




audiences are unregistered so dropping request.


audiences are unregistered so dropping request.


audiences are unregistered so dropping request.
10StatusBadRequestBad request: user guid not passed.
11StatusBadRequestBad request: userId passed multiple times.
12StatusBadRequestBad request: multiple countryCodes present in request.
13StatusBadRequestBad request: multiple IPs present in request.
14StatusBadRequestInvalid request.
15StatusBadRequestBad request: no


audiences present in this request.
16StatusBadRequestBad request: no segId


audiences to process for third party provider.
17StatusBadRequestBad request: userID size is greater than 384 bytes
18StatusBadRequestBad request. user guid format invalid.