Link Search Menu Expand Document


Onboarding Direct Audiences





Through the OA Direct Audience process, marketers can onboard their own 1P audiences, customize them with 3P segment data, and activate them in deals on the OpenX Exchange.

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
  • users under the age of 18 located in California

Hashing is required for personally identifiable information (PII).


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

Audience Files

  • Audience files should be shared to a dedicated folder indicated by /partnername/audience inside the root of the bucket (for example, gs://your-oa-bucket-name/partnername/audience).
  • Under the /partnername/audience folder, create a date folder in the YYYYMMDD format to indicate drops for that day (for example, gs://your-oa-bucket-name/partnername/audience/20200710).
  • The actual files will be in the date directory mentioned above (for example, partnername/audience/20200710/anytexthere_0.csv).
  • If sending audience files using multiple id types, deliver the files to dedicated folders per ID type, or indicate the ID type in the file name.
    • Folder per ID type:
      • gs://your-oa-bucket-name/partnername/audience/cookie/20200710)
      • gs://your-oa-bucket-name/partnername/audience/MAID/20200710)
      • gs://your-oa-bucket-name/partnername/audience/HEM/20200710)
      • gs://your-oa-bucket-name/partnername/audience/user/20200710)
    • File name per ID type:
      • gs://your-oa-bucket-name/partnername/audience/20200710/anytexthere_maid_0
      • gs://your-oa-bucket-name/partnername/audience/20200710/anytexthere_cookie_0
      • gs://your-oa-bucket-name/partnername/audience/20200710/anytexthere_hem_0
      • gs://your-oa-bucket-name/partnername/audience/20200710/anytexthere_user_0
  • All file deliveries must adhere to the folder and file naming conventions first established to avoid delays in processing.

Taxonomy Files

  • To indicate the display friendly name to show in the OpenAudience™ UI for a given segment, a separate taxonomy file should be shared alongside audience files.
  • Taxonomy files should be delivered to dated dedicated folder (for example, gs://your-oa-bucket-name/partnername/taxonomy/YYYYMMDD).
  • Segment name will be contained within a taxonomy file called partnername_taxonomy_YYYYMMDD.txt, which should include:
    • Segment ID (unique segment/audience IDs included in the file dump)
    • Name (desired display name of the segment)

Segment Files

  • Segment files should be .csv files broken into 1GB chunks (hard limit of 4GB per file split).
  • Gzip file compression is supported with the same 4GB limit.

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. 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.