Factual Developer Documenation

Welcome to the factual-devdocs developer hub. You'll find comprehensive guides and documentation to help you start working with factual-devdocs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

MI: Submitting Ad Exposure Data Directly to Factual

Factual's Measurement Intelligence solution enables you to measure the impact of your campaign by having Factual receive your campaign’s ad exposures and then tie them to post-ad-exposure store visits for attribution. At the end of your campaign, Factual delivers a detailed report analyzing your campaign's performance.

If you have ad exposure log files for your campaigns that are tied to mobile advertising IDs (Apple IDFAs or Android AAIDs), you can submit that data directly to Factual for processing. This document describes how to format and deliver your ad exposure files to Factual.

File Naming

For the filename, please include your company name, the name of the chain being measured, campaign start month, and campaign end month in the file name, separated by dashes (“-”). Use the following format: [CompanyName]-[ChainName]-[MonYYYY]-[MonYYYY].tsv

Do not include any non-alphanumeric characters (spaces, underscores, apostrophes, etc.) in the chain name or in the start or end dates. As an example, if your company name is MarketerX and your campaign is measuring visits to Amy’s Back-to-Basics Hardware from Jan to Mar 2018, the filename should be: MarketerX-AmysBacktoBasicsHardware-Jan2018-Mar2018.tsv

If you are measuring visits to more than one chain, you can simply use the name of the largest chain or the name of the category in place of a chain name (e.g., HomeImprovementStores).

File Format

Your file should be a tab-separated value (TSV) file containing the fields described in the table below. Individual records should be delimited by a newline. Individual data files should not exceed 1 GB in size — if a file will exceed 1 GB, then it should be broken into separate partial files that are each smaller than 1 GB.

You must ensure the columns in the exposure file(s) are ordered as indicated by the index numbers below.

1Device_IDString; requiredDevice ID that was exposed to the ad. ID must be the unhashed identifier for advertising (e.g., Apple’s IFA, Android’s Advertising ID).f66f31a5-461c-441a-a48e-582351763349
2Exposure_TimestampString; requiredNumber of seconds since the Unix epoch — 00:00:00 UTC on 1 January 1970.1506815998
3Campaign_IDString; requiredCampaign identifier.BrandX_Campaign123
4Placement_IDString; optionalPlacement identifier.US_App_BusinessTravelers_25to40
5Ad_IDString; optionalAd creative identifier.320x50_BrandX_ProductZ
6Ext1String; optionalOptional custom parameter (up to 5 custom parameters supported)Channel X
7Ext2String; optionalOptional custom parameter (up to 5 custom parameters supported)Publisher Y
8Ext3String; optionalOptional custom parameter (up to 5 custom parameters supported)-
9Ext4String; optionalOptional custom parameter (up to 5 custom parameters supported)-
10Ext5String; optionalOptional custom parameter (up to 5 custom parameters supported)-



Do not include headers in any file submitted directly to Factual. Please send your Factual account representative the ordered list of fields you will be using to ensure correct processing of your file. For example, if your file contains Device_ID, Exposure_Timestamp and Campaign_ID (in that exact order), but no other fields, then tell your Factual account representative prior to submitting your exposure file.

Providing Control Group Exposures to Factual

If you have set aside your own control group for Factual to conduct a conversion lift study, you must designate a placement or placements for the control group and provide the corresponding ID(s) of those control group placements to your account manager. Control group impression data must follow the same format as described above. A timestamp must be provided. Impressions can either be included in the main exposure file or in a separate file. Factual will then be able to do the conversion lift study in the course of generating the Measurement Intelligence dashboard.

If you do not set aside your own control group, but want Factual to conduct a conversion lift study, Factual will to generate a control group for a conversion lift study.


The following is an example of a compliant file. The list of fields in the example below are: Device_ID, Exposure_Timestamp, Campaign_ID, Placement_ID, Ad_ID

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx76C9    1495383384    campaignId1    placementId1    adId0
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx13H4    1495383384    campaignId1    placementId0    adId2
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx8HWE    1495383384    campaignId1    placementId2    adId1
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx42N4    1495383384    campaignId1    placementId0    adId3
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx4U26    1495383384    campaignId1    placementId3    adId2
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx433A    1495383384    campaignId1    placementId1    adId4
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx9H3N    1499610910    campaignId1    placementId1    adId4
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2T32    1499610910    campaignId1    placementId4    adId0
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx43GG    1499610910    campaignId1    placementId2    adId1

Additional Details

When setting up Factual measurement for your campaign, you will need to tell your Factual account representative what places you want to measure visits to (e.g., a nationwide retail chain, a retail chain’s locations in specific DMAs, etc.). We recommend using locations from Factual’s Global Places for your campaign. If you need to use your own custom list of places, you may do so by following this guideline.

After your campaign’s end date, you will need to deliver the exposure file as described above. Factual will then tie the matching store visits to the corresponding exposures for attribution.

The final output will be a conversions data file (spreadsheet) and/or a campaign wrap-up report (pdf) analyzing the results of your campaign in driving traffic to the store. For more details on this deliverable (timing of delivery, sample report, etc.), please contact your Factual account representative.

Updated 10 months ago

MI: Submitting Ad Exposure Data Directly to Factual

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.