Link Search Menu Expand Document


Onboarding Direct Audiences



Last updated on October 19, 2020



Marketers can onboard their own 1P audiences, customize them with 3P segment data, and distribute them in OpenX Exchange through the OA Direct Audience process.

Direct Audience Process

The OpenAudience™ direct audience process is as follows:

  1. File is uploaded into GCS or S3 bucket.
  2. OpenAudience™ kicks off an ETL to match identifier data from the uploaded file.
  3. Once the matching process is complete, additional OA or other 3rd Party aggregated segment data can be appended.
  4. Resulting audience is sent through to Exchange for activation.

File Guidelines

Before uploading your data files, follow these guidelines for file content and format.

Protecting Users and Observing Privacy Laws

Make sure that your data does not include:

  • users outside of the United States
  • users under the age of 13 or any users from properties directed to children (as defined by the Children’s Online Privacy Protection Act)
  • users under the age of 16 located in California

Hashing is required for all data fields that identify a specific individual.


A hash function protects user privacy by making fields unreadable and irreversible while still allowing matching to occur. Prior to hashing a field, normalize it using the general rules below.

  • Make all letters lower case.
  • Trim and remove all spaces.
  • For Mobile Advertiser Device Identifier (IDFA/GAID) only:
    • Make all letters lower case and do not remove hyphens.
  • For Email Hashing:
    • OpenX supports unsalted SHA-256 (preferred), MD5 and SHA1 hash.

Data Format Requirements

Data format requirements are as follows.


• Must include a header row
• All fields are required

FieldColumn HeaderField Guidelines
User IDuser_id/cookie ID/MAID/HEMWe accept the below for Direct Audiences:
• OX Cookies
• Hashed emails (HEMs)
• Partner User IDs

Partner User IDs should only be used if there is an active sync between unique ID match keys between Open Audience and the Partner and/or the Partner’s preferred onboarding platform.
Segment/Audience IDsegment_id1...NUnique ID of the segment/audience that corresponds to the identifier given. An ID can have multiple segment/audience IDs, but each segment ID has to sit in a separate column.

Data Format Example

A data format example.


Column Delimiter, New Lines, and Encoding

  • OpenX accepts files with a comma, tab, or pipe delimiter. Use the .csv extension in the file name.
  • Indicate new lines with LF (Unix) or CR+LF (Windows). OpenX does not accept any other line endings, such as Carriage Return (CR).


    To avoid issues with exporting from earlier versions of Excel for Mac, use the Windows CSM format when available.

  • OpenX supports UTF-8 and UTF-16 encoding. Files without a byte-order mark (BOM) are assumed to be UTF-8

File Format Requirements

  • Folder name will be /partnername inside the root of the bucket (for example, gs://your-oa-bucket-name/test_partner).
  • Under the /partnername folder, create a date folder in the YYYYMMDD format to indicate drops for that day. (for example, gs://your-oa-bucket-name/test_partner/20200710).
  • Segment name will be contained within a taxonomy file called partnername_MMDDYYYY.txt, which should include:
    • Segment ID (unique segment/audience IDs included in the file dump)
    • Name (desired display name of the segment)
  • The actual files will be in the date directory mentioned above (for example, /test_partner/20200710/anytext_0.csv).
  • Files should be .csv files broken into 1GB chunks.

Uploading Your Data Files

You can upload data files to GCS or S3 buckets.

Uploading Files to a GCS Bucket

To upload your files to a GCS bucket:

  1. OpenX provides you with your own GCS bucket, a secure, private location for your files.
  2. OpenX will ask for gmail address(es) of users that will have access to drop files to the GCS bucket.
  3. Load files into the GCS bucket, split into 1GB increments.
  4. If possible, include an empty file indicating that the upload is complete.
  5. Alert your OpenX contact that the file has been loaded to your GCS Bucket.

Uploading Files to an S3 Bucket

To upload your files to an S3 bucket:

  1. OpenX is also able to pick up files from your S3 bucket and transfer them to GCS.
    • The S3 bucket is scanned daily for any file changes and downloads new files.
  2. Please generate and provide OpenX with the following items:
    • S3 Bucket Location (for example, s3://client/)
    • Access key ID
    • Secret access key:
      • The AMS IAM user must have the following permissions:
        • List the Amazon S3 bucket
        • Get the location of the bucket
        • Read the objects in the bucket
      • Additional Documentation

Safe Data Handling

Your data files always remain in your own GCS bucket, separate from all other partners’ data and only accessible to entrusted members of your organization who have your GCS bucket account credentials. OpenX will generate an OpenX ID unique to your organization for each recognized user. You are responsible for maintaining the security and confidentiality of your GCS bucket account credentials. If you believe credentials have been compromised, please notify OpenX immediately.