SFTP Data Transfer for Audiences

Use the following information to transfer audience data to PubMatic over SFTP.

Data transfer parameters

ParameterTypeRequiredDescription
dpidinteger

PubMatic data partner ID (DPID) assigned to the data partner at time of integration.
useridintegerThe PubMatic user ID passed to the data partner by PubMatic .
segidinteger array

Use segid to send the complete list of source 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.

Omitting the segid parameter removes the entire list of the user's audiences. See Remove a user from audiences.
uidtypeinteger

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.
Note that uidtype 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.
iptext
Last known IP address of the user. Exclude this parameter from the request if the user's last IP address is unknown, and it is optional when you send  country  in the request.
countrytext
Two-letter code for the user's country; for example,  US IN CA . Exclude this parameter from the request if the user's country is unknown, and it is optional when you send the last known  ip  in the request.

SFTP bulk audience data transfer

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:

[DPID] [TAB] [USERID] [TAB] [SEGID] [TAB] [IP] [TAB] [COUNTRY] [TAB] [UIDTYPE] [CR]

The [SEGID] 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.

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

  <DPID>_<TIMESTAMP>_<MD5SUM>.tsv.gz
  • 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:

  <DPID>_<TIMESTAMP>_<MD5SUM>_<WORKERID>.tsv.gz

While 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

103 5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D 4666 74.125.236.123 0


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

Bulk 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 audience for a given user id, but FTP requires the DMP to send all the user's audience IDs, which overrides the existing audience stored with PubMatic.
  3. FTP allows only one new line entry for each 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

PubMatic 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=" http://partner.com/xxxx?id=UID" 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 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.

    EXAMPLES:

    http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D&uidtype=[Identity_Partner_ID]

    OR

    To send a list of audiences to remove using the remseg parameter: 

    http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D&remseg=123_B,3242&uidtype=[Identity_Partner_ID]
  2. When sharing data via a bulk file, do not pass any 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 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.

IDCodeMessage
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.
6StatusBadRequestFollowing audiences are unregistered: [list of audiences].
7StatusBadRequestsegId audiences are unregistered so dropping request.
8StatusBadRequestaddSegs audiences are unregistered so dropping request.
9StatusBadRequestremSegs 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.
19StatusOKSuccess.

⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents