SFTP Data Transfer for Audience Segments

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

Data transfer parameters

Parameter	Type	Required	Description
`dpid`	integer	✓	PubMatic data partner ID (DPID) assigned to the data partner at time of integration.
`userid`	integer	✓	The PubMatic user ID passed to the data partner by PubMatic .
`segid`	integer 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 list. DO NOT send `segid` in a request that also includes the `addseg` or `remseg` parameter. Omitting the `segid` parameter removes the entire list of the user's audience segments. See Remove a user from audiences.
`uidtype`	integer	✓	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.
`addseg`	integer array		Use `addseg` to send: A complete list of comma-separated segment IDs to replace the user's current segments. The addseg parameter with the list of new segments to append to the user’s current segments. You can include `addseg` and `remseg` in the same request, but *DO NOT* send `segid` along with these parameters.
`remseg`	integer		Use `remseg` to send: A complete list of comma-separated segment IDs to replace the user's current segments. The `remseg` parameter with the list of segments to remove from the user’s current segments. You can include `remseg` and `addseg` in the same request, but *DO NOT* send `segid` along with these parameters.
`ip`	text		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.
`country`	text		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

You can 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] [PUBID] [TAB] [SEGID] [TAB] [IP] [TAB] [COUNTRY] [TAB] [UIDTYPE] [CR]

The segid parameter can be a comma-separated list of different audience segment IDs. See Data transfer parameter reference above.

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. See Segment Registration > Sample entries below.

File name format

File names follow the pattern:

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

<TIMESTAMP> format should be Unix; for example, 1596695461984.
<MD5SUM> is an MD5 32-character hexadecimal checksum that is computed on the file content before compression.

If your organization has workload managed by a team, you can also include a <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.

Segment registration

Before sending data for specific segment IDs in the TSV file, you should have already registered the segments with PubMatic. You can either email PubMatic any new segment names and IDs you want to register, or use the PubMatic Audience Registration API to do so.

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…

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

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

The data provider must provide PubMatic with an image pixel similar to, <img src=" http://partner.com/xxxx?id=UID " width=1 height=1> .
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.
If data comes from a buyer, PubMatic fires the image pixel from step 1 across PubMatic's site.

⇧ Top

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

Products Home

Developer Home

Resources Home