How do I upload an ID List?

Review how to upload an ID list to your account via UI or S3 bucket.


A user list is a customer-defined sequence of identifiers that can be leveraged to filter data. Currently, user lists can contain either Hashed Emails or Mobile Advertiser Identifiers. This document outlines the process needed to create, modify, and delete user lists in your account. 

Creating a User List

UI Upload

In your Narrative Account, navigate to the Admin link and select Lists.

Lists in Narrative are categorized in three buckets - Users, Locations, and Unified Resource Identifiers (also known as app or bundle IDs). 

At this time, only User Lists of Hashed Emails or MAIDs are supported through the UI upload. For Location & URI lists, please continue to send via S3. More instructions here.

To being an upload, select New List + and then choose the type of list you want to upload.

Formatting for MAIDs

There are two accepted formats for uploading a list of MAIDs. 

  • Single column file

If using a single column file, please use UPPERCASE for IDFA and lowercase for ADID. Our system will automatically differentiate between the two based on the upper or lower case format.

  • Two column file

If using a two column file, column 1 should contain the ID type (either "adid" or "idfa") to differentiate between the two types of IDs. The second column will contain the actual ID string. If using the second column, the upper & lower casing is not required. If an ID does not have a type defined in column 1, our system will revert to the upper/lower case format to define the type. 

Formatting for Hashed Emails

Hashed Emails can be uploaded via a single column file. Our system will automatically identify the hash type (sha1_email , sha256_email, md5_email) based on the length of the ID. 

A 2 column list is also accepted and should follow the same Column 1 (ID Type) & Column 2 (ID string). HEMs are NOT case sensitive.

Completing the Upload

After selecting the file, complete the upload by adding a Name, Description, and any tags for better organization.

Review your list and begin uploading the data into your account. Lists will take a few minutes to complete. 

S3 Upload

You need an active account to send list files to Narrative. If you do not have an account, please contact your Narrative partner success representative.

Narrative leverages AWS S3 as it's ingestion point for customer lists. Data is stored in separate buckets for each partner with the typical naming convention being:


You can receive your bucket and the appropriate credentials from your Partner Success representative.

Lists are pushed to a folder within your bucket called:


Once pushed to that location Narrative will pick up the file(s) and process the lists. The appropriate file format is discussed below.

Example Push Location: 


List Processing & Success File

List processing starts after a file has been uploaded successfully. When complete, we will write a success file to your S3 directory. Success file characteristics include:

  • Name: <original_filename>.success
  • Location: Check the submitted subdirectory of your lists_incoming folder.


    7981.csv was imported. 171252246 lines were read.  171252246 were successful with 0 errors.

    Naming Conventions

    By default, Narrative will use the name of the file pushed to S3 as the name of the list in the Narrative Data Streaming Platform UI.

    Updating a User List

    When a list is created, a unique Narrative specific list identifier is generated. This identifier is available via the Narrative UI. To update a list, future file drops should use the naming convention:


    The naming convention will tell Narrative to update that list.

    Deleting a User List

    A list can be deleted via the Narrative UI or by updating a list with an empty file.

    File Specification

    File Format

    ID List File Format