Submitting Audience Data – Accepted Formats

If you’re using a file-based method of submitting Audience data to Factual, your files must conform to our standard JSON data format. Please read below for more details on how to deliver and format the data.


You upload files must be compressed with gzip and the file names must end in “.gz”. Individual records should be delimited by a newline.

JSON Format

The format of the uploaded files must be line-delimited JSON objects with two top-level fields: timestamp and payload. timestamp indicates the time of the event, and payload contains event data in a format compatible with OpenRTB 2.2.

Summary of Required Fields

The following are the minimum fields required to build Audience segments from submitted data:

  • A timestamp field, .timestamp, containing a number representing the number of milliseconds since the Unix epoch — 00:00:00 UTC on 1 January 1970.
  • A latitude field,, containing a number representing the latitude.
  • A longitude field, .payload.device.geo.lon, containing a number representing the longitude.
  • A user identifer field, which must be one of the following strings:
  • .payload.device.ext.idfa, if the ID provided is an ID for advertisers (Apple IDFA or Android Advertising ID).
  • .payload.device.dpidsha1, if the ID provided is a SHA-1 hash of a device identifier.
  •, if the ID is any other type of device identifier.
  • Factual accepts additional OpenRTB fields. See the OpenRTB 2.2 specification for more details.

Supported Extensions

Factual supports the following extension fields in the OpenRTB payload:

payload.device.geo.ext.accuracyRecommendedfloatGeo accuracy, in meters10.1
payload.device.ext.ssidRecommendedstringWIFI SSID"My Network"
payload.device.ext.bssidRecommendedstringWIFI BSSID"24:a4:d7:a2:1b:91"
payload.device.geo.ext.speedRecommendedfloatSpeed, in meters per second0.0
payload.device.geo.ext.orientationRecommendedfloatOrientation of device, in degrees clockwise from north349.1
payload.device.geo.ext.altRecommendedfloatAltitude, in meters100.5
payload.device.geo.ext.altaccuracyRecommendedfloatAltitude accuracy, in meters4.2

Example Records

The following is an example of two compliant input records. Note that each is providing additional optional fields from the OpenRTB spec (scroll to see full line).

{"timestamp": 1441736244578,"payload": {"device": {"ext": {"idfa": "ce758862-9f71-4d78-afab-37688bb2fe18"},"language": "en","os": "Android5.0.1","geo": {"lat": 37.31207387,"lon": -120.77605476,"ext": {"activity": "walking","verified_location_id": "bc060887-dc48-4a88-8b5e-793ec3893341"}}}}}
{"timestamp": 1441738238412,"payload": {"app": {"id": "51121664-868c-af0d-2229-d4995c33bebf"},"device": {"ext": {"idfa": "a70a25da-0649-498e-9374-2d237f45c108"},"language": "en","os": "Android5.1.1","geo": {"lat": 39.27172509,"lon": -86.6257966},"ip": ""}}}