Skip to main content
Home/Bulk Upload/CSV Field Reference

CSV Field Reference

This page provides detailed information about each column in the bulk upload CSV template.

1. Base Fields​

  • External treatment ID

    • Type: String
    • Required: No
    • Description: External identifier for integration with other systems
    • Notes:
      • Only available if enabled in your project settings
      • Must be unique within your project if provided

  • Tags

    • Type: String
    • Required: No
    • Description: Tags for organizing and categorizing treatments
    • Format: Use semicolons (;) to separate multiple tags
    • Formatting Rules
      • Use semicolons (;) to separate tags
      • Do not include spaces after semicolons
      • Do not leave empty values between semicolons
      • Tags are case-sensitive
    note

    All tags must already exist in your project before using them in bulk upload. Create tags in the console first if needed.

  • Treatment type*

    • Type: String
    • Required: Yes
    • Description: The treatment type for this treatment
    • Example: POPUP_BANNER, PUSH_NOTIFICATION
    • Notes:
      • The Treatment Type should already exist
      • All treatments in a CSV must have the same Treatment type

  • Target action

    • Type: String
    • Format:
      • Basic Event
        • For events without specific property requirements.
        • Syntax: EventName
        • Example: purchase
      • Event with Properties
        • For events that require specific property values.
        • Syntax: EventName (PropertyName1: PropertyValue1 ; PropertyName2: PropertyValue2)
        • Single Property Example: purchase (product_type: premium)
        • Multiple Properties Example: level_end (level_number: 5 ; result: success ; difficulty: hard)
    • Important Notes
      • Event name must exist in your project
      • Property names must exactly match the event's property definitions
      • Property values must exactly match existing values for that property
      • All specified properties must exist for the event

  • Name*

    • Type: String
    • Required: Yes
    • Description: The treatment name displayed in the console

  • Description*

    • Type: String
    • Required: Yes
    • Description: Detailed description of the treatment's purpose

  • Surfaces*

    • Type: String (semicolon-separated)
    • Required: Yes
    • Description: Surfaces to include for this treatment
    • Format: Use semicolons (;) to separate multiple surfaces
    • Notes
      • Only surfaces associated with the treatment type can be specified
      • At least one surface must be specified
      • Surface names must exactly match existing surfaces

  • MEG

    • Type: String
    • Required: No
    • Description: Mutual Exclusion Group name
    • Example: holiday_promotions
note

The Mutual Exclusion Group (MEG) must already exist in your project before using it in bulk upload. Create the MEG in the console first if needed.

2. Launch Schedule​

  • Start timestamp*

    • Type: Timestamp (UTC)
    • Required: Yes
    • Description: When the treatment becomes active
    • Format: MM/dd/yyyy hh:mm a
    • Example: 06/01/2024 12:00 AM
    • Notes:
      • Must be in UTC timezone
      • Use 12-hour format with AM/PM
      • Month and day should be zero-padded (e.g., 01 not 1)

  • End timestamp

    • Type: Timestamp (UTC)
    • Required: No
    • Description: When the treatment expires
    • Format: MM/dd/yyyy hh:mm a
    • Example: 12/31/2024 11:59 PM
    • Notes:
      • Must be in UTC timezone
      • Use 12-hour format with AM/PM
      • If not provided, treatment runs indefinitely

3. Content Fields​

Content fields vary based on your treatment type. They fall into two categories:

  • Language-Agnostic Fields

    Fields that apply to all languages.

    • Column Name: field_name
    • Example: image_url, deep_link

  • Language-Specific Fields

    Fields that have different content for each language.

    • Column Name: field_name_languagecode
    • Examples:
      • title_en, title_ja
      • body_en, body_ja
      • cta_text_en, cta_text_ja

    Notes:

    • Each field has a maximum character limit (varies by treatment type and field)
    • Exceeding the character limit will cause validation errors

4. Qualification Criteria​

Qualification criteria determine which users are eligible to receive the treatment. Each qualification criterion is defined by four columns.

  • Column Pattern

    For each qualification criterion number N (where N = 1, 2, 3, ...):

    ColumnDescription
    Qualification field NThe data field to evaluate
    Qualification condition NThe comparison condition
    Qualification value NThe value to compare against
    Apply qualification N if attribute not availableBehavior when data is missing (User Attributes only)

  • Qualification field N

    • Description: The data field to check for eligibility. Can be one of two types:
    • Types:
      • Regular Data Field (by ID)
        • Use the numeric data field ID from your project
        • Example: 12345
      • Self Referencing Treatment Interaction
        • What it is: A special data field that tracks how users have interacted with the treatment you're currently creating
        • Format: InteractionType_(THIS_TREATMENT)_TimeWindow
        • Note: (THIS_TREATMENT) is a placeholder that automatically refers to the treatment being created
        • Example: Limit how often a treatment is shown to users
          • In CSV, enter: Sent_(THIS_TREATMENT)_last_1d with condition is less than and value 2
          • In console, displays as: auxia_treatment_sent treatment_id:12345 last_1d<2 (where 12345 is the treatment ID)
        • Supported Interaction Types:
          • Sent - Treatment was sent to user
          • Viewed - User viewed the treatment
          • Clicked - User clicked on the treatment
          • Snoozed - User snoozed the treatment
          • Dismissed - User dismissed the treatment
          • Cta_completed - User completed the call-to-action
          • Swipe - User swiped on the treatment
        • Supported Time Windows:
          Time WindowReturnsDescription
          first_timestampTIMESTAMPWhen interaction first occurred
          latest_timestampTIMESTAMPWhen interaction most recently occurred
          last_1dINTEGERCount in last 1 day
          last_7dINTEGERCount in last 7 days
          last_14dINTEGERCount in last 14 days
          last_28dINTEGERCount in last 28 days
          last_56dINTEGERCount in last 56 days
          days_since_firstINTEGERDays since first occurrence
          days_since_lastINTEGERDays since last occurrence

  • Qualification condition N

    • Description: The comparison operator to use. Valid conditions depend on the data field type.
    • Conditions by Type:

      • For INTEGER and DOUBLE:

        • is - Equals
        • is not - Not equals
        • is greater than - Greater than
        • is at least - Greater than or equal to
        • is less than - Less than
        • is at most - Less than or equal to
        • is any of - Matches any value in a list
        • is not any of - Does not match any value in a list
        note

        The between condition is not supported. Instead, use two separate qualification criteria: one with is at least for the minimum value and another with is at most for the maximum value.

      • For STRING:

        • is - Exactly equals
        • is not - Not equals
        • contains - Contains substring
        • does not contain - Does not contain substring
        • is any of - Matches any value in a list
        • is not any of - Does not match any value in a list

      • For BOOLEAN:

        • is - Equals (true or false)

      • For TIMESTAMP_SECONDS:

        • at or before - At or before timestamp
        • at or after - At or after timestamp
        • is older than - Is before current time minus a duration
        • > current time minus - Is after current time minus a duration
        • has happened - Checks if the event has occurred (value: true) or not occurred (value: false)

      • For INTEGER_LIST, DOUBLE_LIST, STRING_LIST:

        • contains - List contains value
        • does not contain - List does not contain value
        • contains any of - List contains any value in specified list
        • does not contain any of - List does not contain any value in specified list

  • Qualification value N

    • Description: The value to compare against. Format depends on the condition and data field type.

  • Apply qualification N if attribute not available

    • Type: String (Boolean)
    • Required: No (only applicable for User Attribute data fields)
    • Description: Controls what happens when a User Attribute data field has missing or unavailable data
    • Valid Values:
      • TRUE - If the attribute is missing, treat the qualification as satisfied
      • FALSE - If the attribute is missing, treat the qualification as not satisfied
      • Empty - Default behavior
    • Important Notes:
      • This field only applies to User Attribute data fields (data fields based on user properties)
      • Cannot be set for Self Referencing Treatment Interaction fields or Event-based fields
      • If you try to set this value for non-User Attribute fields, validation will fail
    • Example Scenario: If you're targeting users with country = US, but some users don't have a country value:
      • Set to FALSE: Users without a country value won't receive the treatment even if other criteria are satisfied
      • Set to TRUE: Users without a country value will be treated given that other criteria are satisfied

Next Step: Once your CSV is filled out, proceed to Upload and Validate for validation rules, error troubleshooting, and to upload your file.