Skip to content
Last updated

Third Party Attribution File Spec

How to send your attributed conversions to Infillion, so they drive optimization and appear in your campaign's standard conversion, revenue, CPA and ROI metrics.

Applies to

Campaigns whose Measurement settings use Custom or 3rd Party Attribution.

Campaign Setup

  1. In the campaign's Measurement settings, choose Custom or 3rd Party Attribution. The campaign then reports and optimizes on the conversions you send. Infillion stops calculating Last Touch attribution for it.
  2. Select the campaign's Merit Pixels (up to 10). Every merit_pixel_id in your files must be one of them. Conversions for any other pixel are not counted toward the campaign.
  3. Set the post-view and post-click windows. With 3rd Party Attribution these windows don't attribute anything: they are acceptance filters (see How Conversions Appear in Reporting).
  4. Depending on which partner you are working with for 3rd Party Attribution, you may be required to add the [BID_ATTR.bid_id] macro to every creative's impression and click tracking URLs and to set up the Log Level Data Service.
Locked settings

Weight Preset, Value, Post-View Discount Rate and Repeat Merit Events are locked on these campaigns. Your attribution partner decides how much credit each conversion gets.

Delivering Files

Upload files to the Amazon S3 bucket inf-third-party-conversions. Put each file directly inside your organization's folder:

s3://inf-third-party-conversions/organization_id=<your organization ID>/Conversions_20261007_060000_Part1.csv

Getting Access

To get access to upload third party conversions, open a Support ticket. Once access is in place, you write to your folder with temporary credentials obtained through an AWS role, the same way as for the Log Level Data Service (see Obtaining Temporary Credentials).

Folder and Delivery

  • The folder name must be exactly organization_id= followed by your numeric organization ID. Files in subfolders are not processed.
  • Files are picked up once an hour. You can deliver as often as you like, and as many files as you need.

File Names

Conversions_YYYYMMDD_HHMMSS_PartN.<csv|tsv|json|parquet>[.gz]
  • YYYYMMDD_HHMMSS must be a real date and time. Use the time you created the export, in UTC.
  • PartN numbers start at 1. Split a large export into Part1, Part2 and so on.
  • Files whose names don't follow this pattern are ignored without notice. They aren't processed or reported anywhere.
Each file name is processed once

Re-uploading a file with the same name has no effect. To correct data, send the rows again in a new file (see Corrections and Duplicates).

SFTP and FTP are not supported.

File Formats

FormatColumnsCompression
CSV (.csv)
TSV (.tsv)
A header row is required. The first 9 columns must be the fields below, in that exact order and with those exact lower-case names. Extra columns after them are ignored.None, or gzip with a .gz suffix
JSON (.json)One JSON object per line (JSON Lines), not a single array. Fields are matched by name. Extra fields are ignored.None, or gzip with a .gz suffix
Parquet (.parquet)Fields are matched by name, and their types are checked (see Fields). Extra fields are ignored.Internal only: Snappy, Zstandard or gzip. Don't add .gz
  • Maximum file size: 5 GiB, after compression. Split larger exports into parts.
  • Text timestamps (CSV, TSV, JSON) use YYYY-MM-DD HH:MM:SS, in UTC. Example: 2026-10-07 14:32:10.
  • Leave an optional value empty (CSV/TSV) or set it to null (JSON).
Every field must be present

"Optional" applies to a field's value, never to the field itself. All 9 fields must be in every file, even when you never fill some of them, for example click_timestamp in a feed with only VIEW rows or revenue_credit without revenue. A file missing any of them is rejected as a whole. In CSV/TSV, keep the column and leave it empty. In JSON, include the key with null. In Parquet, keep the column, with its type from the table below, and write nulls.

Fields

Each row gives one impression credit for one conversion. If your partner splits credit for a single conversion across several impressions, send one row for each impression, using the same transaction_id on every row. For example, an order credited 0.6 to one impression and 0.4 to another is two rows.

#FieldTypeRequiredDescription
1auction_idBIGINT
Parquet: INT64
YesThe Infillion auction ID that identifies the impression. This is the value of the [BID_ATTR.bid_id] macro.
2merit_pixel_idINT
Parquet: INT32
YesThe Infillion Merit Pixel ID the conversion counts toward. It must be selected on the campaign.
3conversion_creditDOUBLE
Parquet: DOUBLE
YesFractional credit from 0.0 to 1.0. A credit of 0.6 adds 60% of a conversion to the campaign.
4revenue_creditDOUBLE
Parquet: DOUBLE
OptionalRevenue credited to this impression, in USD. It is converted to the campaign's reporting currency, and the Merit Pixel's own currency setting is ignored. Needed for ROI campaigns. Must not be negative.
5conversion_timestampTIMESTAMPYesWhen the conversion happened, in UTC.
6impression_timestampTIMESTAMPYesWhen the credited impression was served, in UTC. Required for CLICK rows too. This time must not be later than the click time or the conversion time.
7click_timestampTIMESTAMPCLICK onlyWhen the credited click happened, in UTC. Required when attribution_type is CLICK. Must be between the impression and the conversion.
8transaction_idSTRINGYesYour unique ID for the conversion, such as an order number. At most 255 characters.
9attribution_typeSTRINGYesCLICK or VIEW, in upper case: whether your partner credited a click or a view.
Parquet types must match exactly

auction_id is INT64, merit_pixel_id is INT32, and both credit fields are DOUBLE (FLOAT is rejected). Timestamps must be native TIMESTAMP columns: the legacy INT96 encoding is not supported, and their values are read as UTC.

Validation

Whole-File Rejection

Nothing from a file is used if any of these apply:

  • The file is larger than 5 GiB, or can't be read (corrupt, wrong compression, or .gz on a Parquet file).
  • A required column is missing. For CSV/TSV, the rejection also happens when the first 9 columns are out of order or named differently.
  • A Parquet field has the wrong type, for example an INT32 auction_id or a FLOAT credit.
Rejected files are not retried

Fix the problem and upload the data again under a new file name.

Row-Level Checks

These drop only the offending row. The rest of the file is processed. Checks run in this order, and each dropped row is counted under the first rule it fails:

  1. A required field is empty or can't be read. Examples: a credit of abc, or a timestamp in another format such as 2026-10-07T14:32:10Z.
  2. transaction_id is longer than 255 characters.
  3. conversion_credit is below 0 or above 1.
  4. revenue_credit is negative.
  5. attribution_type is not exactly CLICK or VIEW.
  6. A CLICK row has no click_timestamp.
  7. The timestamps are out of order. The impression must come first, then the click (whenever click_timestamp is set, on any row), then the conversion. Equal times are fine. A click before its impression, or a conversion before its impression or click, is invalid.
  8. The impression is more than 30 days old when the file is processed. Send conversions promptly: an impression that was recent when the conversion happened can still be too old by the time the file arrives.
  9. After matching, the conversion falls outside the post-view window (VIEW rows, measured from the impression) or the post-click window (CLICK rows, measured from the click) of the impression's campaign.

Matching to Impressions

Each row is matched to an Infillion impression by auction_id alone. An impression belongs to exactly one campaign, so it gives the conversion its campaign, strategy and advertiser. Make sure each row credits an impression from the campaign the conversion is meant for. The advertiser's Attribution Level setting (individual or household) doesn't apply here.

  • If a row's auction_id doesn't match any Infillion impression, its conversion is not included in any reporting metric. The only place it shows up is the Unmatched Auction ID Rate in the Feed Status.
  • Unmatched rows are not retried later. Send conversions once the impressions they credit are at least a few hours old.

Corrections and Duplicates

You can change a conversion you already sent for two reasons: to fix a mistake, or to restate its value. Restating is expected. For example, your attribution model may receive new information and reweight the credit it gave earlier. Both work the same way: send the conversion again in a new file with the same values for these four fields:

auction_id + merit_pixel_id + conversion_timestamp + transaction_id
  • The latest values replace the previous ones. Reports change by the difference, so nothing is counted twice.
  • Send the complete row. A correction with an empty revenue_credit sets the revenue to zero.
  • To remove a conversion, send it with conversion_credit = 0 and an empty revenue_credit.
  • Sending a row with exactly the same credit and revenue changes nothing. Re-sending data is safe, but such rows are not counted as feed activity (see Feed Status).
  • If the same conversion appears more than once in one file, only one of those rows is kept. Put each correction in a later file.
  • Corrections only change conversion_credit and revenue_credit. To change any of the four key fields, send conversion_credit = 0 for the old row and add the new row.

How Conversions Appear in Reporting

Your conversions populate the campaign's standard metrics.

MetricComes from
ConversionsSum of conversion_credit, fractions included
RevenueSum of revenue_credit, converted from USD to the campaign's currency
CPA, ROI, AOVCalculated from the conversions and revenue above, the same way as for any campaign
  • A conversion counts only if its merit_pixel_id is one of the impression's campaign's Merit Pixels, and it falls within that campaign's post-view or post-click window (see Validation).
  • Post-view conversions are not discounted, and repeat merit event rules are not applied. Your partner's credit is used as-is.
  • Metrics are available in reports, data exports, campaign charting and the Reporting API.
  • Files are processed hourly. Data usually appears in reports within a few hours of delivery.

Examples

CSV

File organization_id=102807/Conversions_20261007_060000_Part1.csv:

auction_id,merit_pixel_id,conversion_credit,revenue_credit,conversion_timestamp,impression_timestamp,click_timestamp,transaction_id,attribution_type
7718226453901234567,847291,0.6,59.94,2026-10-07 14:32:10,2026-10-06 09:15:44,,ORD-100234,VIEW
7718226453907654321,847291,1.0,120.00,2026-10-07 16:05:00,2026-10-07 15:40:12,2026-10-07 15:41:03,ORD-100235,CLICK
7718226453905550001,847291,0.4,39.96,2026-10-07 14:32:10,2026-10-05 20:02:31,,ORD-100234,VIEW

The first and third rows split one order (ORD-100234) between two impressions: 0.6 and 0.4 of a conversion.

JSON Lines

The same first two rows, in Conversions_20261007_060000_Part1.json:

{"auction_id": 7718226453901234567, "merit_pixel_id": 847291, "conversion_credit": 0.6, "revenue_credit": 59.94, "conversion_timestamp": "2026-10-07 14:32:10", "impression_timestamp": "2026-10-06 09:15:44", "click_timestamp": null, "transaction_id": "ORD-100234", "attribution_type": "VIEW"}
{"auction_id": 7718226453907654321, "merit_pixel_id": 847291, "conversion_credit": 1.0, "revenue_credit": 120.00, "conversion_timestamp": "2026-10-07 16:05:00", "impression_timestamp": "2026-10-07 15:40:12", "click_timestamp": "2026-10-07 15:41:03", "transaction_id": "ORD-100235", "attribution_type": "CLICK"}

Correction

The next day, your partner moves more credit to the earlier impression. In a new file, Conversions_20261008_060000_Part1.csv:

auction_id,merit_pixel_id,conversion_credit,revenue_credit,conversion_timestamp,impression_timestamp,click_timestamp,transaction_id,attribution_type
7718226453901234567,847291,0.3,29.97,2026-10-07 14:32:10,2026-10-06 09:15:44,,ORD-100234,VIEW
7718226453905550001,847291,0.7,69.93,2026-10-07 14:32:10,2026-10-05 20:02:31,,ORD-100234,VIEW

Each row keeps its four key fields, so it replaces the earlier values. The order still totals 1.0 conversion and $99.90. Each impression's campaign and strategy is adjusted by the difference: −0.3 and +0.3 conversions.

Before You Send Your First File

  • The campaign uses Custom or 3rd Party Attribution, and every merit_pixel_id you send is one of its Merit Pixels.
  • You have requested access through a support ticket, and your partner's requirements are covered: the [BID_ATTR.bid_id] macro on every creative's impression and click tracking URLs, and Log Level Data Service, if they apply.
  • Files go directly into organization_id=<your ID>/ and are named Conversions_YYYYMMDD_HHMMSS_PartN.<ext>.
  • CSV/TSV files start with the exact 9-column header, in order.
  • Timestamps are UTC, in YYYY-MM-DD HH:MM:SS (or native Parquet TIMESTAMP), and in order: impression, then click, then conversion.
  • Parquet files use INT64 for auction_id and DOUBLE for credits.
  • Revenue is in USD, and corrections are sent as complete rows in new files.