Drive measurable advertising performance with PubMatic's AI-powered, agentic platform — built for buyers, publishers, and commerce media across CTV and mobile.
A typical PubMatic destination uses two syncs together: a Taxonomy registration sync to declare your segments to PubMatic, and an Audience data sync that uploads the users in each segment. Taxonomy must be registered before the audience data is uploaded.
Supported syncing
| Sync type | Description | Supported sync modes | API reference |
|---|---|---|---|
| Audience data | Upload user records mapped to a registered PubMatic segment as a gzipped TSV file. | Replace, Incremental | Data file format |
| Taxonomy registration | Register segment definitions with PubMatic so that user data referencing those segments can be ingested. | Replace | Taxonomy file format |
For more information about sync modes, refer to the sync modes docs.
Connect to PubMatic
To connect PubMatic to Hightouch you need an SFTP account and a Data Partner ID (DPID), both provided by your PubMatic Account Manager during onboarding. The onboarding email includes the SFTP hostname, username, password, DPID, and the absolute paths to upload to.
-
Go to the Destinations overview page and select Add destination.
-
Select PubMatic from the destination catalog.
-
Enter the following credentials, then select Continue:
- SFTP Host: the regional PubMatic SFTP hostname from your onboarding email. Pick the region closest to your user base for fastest ingestion.
- SFTP Port: defaults to
22. - Username and Password: your PubMatic SFTP credentials.
- Data Partner ID (DPID): your PubMatic-assigned data partner ID.
- Data File Path: the absolute path where audience data files should land. PubMatic provides this in your onboarding email and it typically looks like
/home/<username>/Reports/, where<username>matches your SFTP username. - Taxonomy File Path: the absolute path where taxonomy files should land, typically
/home/<username>/taxonomy/. This must be different from the data file path — PubMatic separates the two file types by folder.
Contact your PubMatic Account Manager before sending your first taxonomy file. PubMatic typically reviews the initial taxonomy submission to confirm segment IDs, naming, and pricing before activating the data feed.
Sync configuration
Sync audience data
Audience data syncs upload the users belonging to a registered PubMatic segment. Each sync run uploads a gzipped TSV file to your Data File Path.
The segment referenced in this sync must be registered with PubMatic before the audience data can be ingested. Run the corresponding Taxonomy registration sync first and allow 3–4 hours for PubMatic to process newly registered segments before scheduling your Audience data sync.
Sync configuration
| Field | Description |
|---|---|
| Segment ID | The PubMatic segment ID that this sync targets. Must already exist in PubMatic's taxonomy. |
| User ID Type | The type of user identifier in your mapped User ID column. Choose one of Cookie, MAID (IDFA/AAID), UID 1.0 by TTD, ID5, RampID by LiveRamp, Shared ID, Panorama ID by Lotame, Intent IQ, or IP Address. If your identifier isn't listed, enter a custom identity-partner ID assigned to you by PubMatic. |
Sync mode
Choose how data is sent to PubMatic on each run:
- Replace (send all records): sends all records from your query result. PubMatic overwrites the existing membership of the segment with the contents of this file.
- Incremental (add/remove only): sends only the records that have been added to or removed from your query result since the last sync. Hightouch uploads separate
addsegandremovesegfiles so PubMatic can apply the membership changes incrementally.
Field mapping
Map source columns to PubMatic fields:
| Destination field | Required | Notes |
|---|---|---|
| User ID | Yes | The user identifier. Must match the User ID Type selected above. |
| IP Address | Conditional | Provide either IP Address or Country (or both) for geo information. |
| Country | Conditional | Provide either Country or IP Address (or both) for geo information. |
Each row Hightouch uploads contains your DPID, the mapped User ID, the segment ID, IP address (if provided), country (if provided), and the selected User ID Type. Files are named to include your DPID, a timestamp, and a content checksum so PubMatic can deduplicate uploads.
Sync taxonomy registration
Taxonomy syncs register segment definitions with PubMatic. Each segment must be registered before any Audience data sync that references it can be ingested.
Schedule taxonomy syncs to run at least 3–4 hours before the Audience data sync that references the same segments. PubMatic needs time to process newly registered segments before they can receive user data.
Field mapping
Map source columns to PubMatic taxonomy fields:
| Destination field | Required | Notes |
|---|---|---|
| Segment Name | Yes | Human-readable name of the segment. |
| Segment ID | Yes | Unique segment identifier. Used as the segid value in Audience data syncs. |
| Segment Status | Yes | Either NEW (active segment) or EMPTY (deactivate segment). Rows with any other value are rejected. |
| Creation Date (YYYYMMDDHHMM) | Yes | Creation timestamp in PubMatic's expected format. |
| Description | No | Free-text description of the segment. |
| Price (CPM in USD) | No | Per-row CPM. PubMatic requires a price on every row — if you don't map this column, Hightouch falls back to the Default Price configured below. |
Default values
PubMatic requires a price value on every row. Use Default Price (CPM in USD) to set the CPM that Hightouch applies when Price is missing or unmapped on a row.
Tips and troubleshooting
Validate your setup
After your first sync completes, verify the upload in PubMatic:
- Check that the file landed in the configured path (Data File Path for audience data syncs, Taxonomy File Path for taxonomy syncs) using your SFTP client. Hightouch uploads files with a
.UPLOADINGsuffix and renames them once the transfer completes — only fully renamed files should appear. - Ask your PubMatic Account Manager to confirm that PubMatic ingested the file. Audience data files reference segments by their
segid, so any segment that hasn't been registered through a Taxonomy sync (or hasn't yet been processed by PubMatic) is silently dropped on PubMatic's side.
Common errors
To date, our customers haven't experienced any errors while using this destination. If you run into any issues, please don't hesitate to . We're here to help.
Live debugger
Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.
Sync alerts
Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.