Importing Second-party Data

In this article

A guide intended for publishers and marketers who want to upload second-party data into Permutive. This is typically user cohort membership data that comes from an advertising partner or an advertising partner’s DMP. It could also be the publisher's first-party data on their subscribers or other identifiable users.

This type of data import can be used as a one-off data dump or a periodic import.


In order to use Permutive data imports, you’ll first need access to a Google Cloud Storage bucket for data uploads. 

Permutive supports one GCS per customer, but each project/data source (we refer to them as data providers) is broken down into subfolders.

Please contact Permutive support with the following information and our team will provide you with a bucket and relevant access:

1. Users to have access to the bucket. There are a couple of options depending on your intended upload method:

  • Manual file upload: we will grant Google workspace group email addresses access to the GCS bucket so that you can upload files via the Google Cloud Platform Console or command-line tool. The account has to be recognised as associated with an active Google Account or Google Apps account. Using group email accounts allows you to manage user access, meaning if you want to add/remove users you do not need to reach out to us. If you do not have a group email address please let us know.
  • Programmatic file upload: you will need to create a service account within your GCP project, which will be used to perform uploads to Permutive. In this case, please let us know the email address of your service account so that we can grant access.

Note: You can also provide both types of users to have access to the same bucket.

2. The name of the project/data source (this could be a partner's name or an internal project name if it's your data) - it is quite arbitrary and will form a part of your bucket's path. Please use just letters, numbers and an underscore (ie. partner_analytics, subscriber_data

3. Name of the user id alias to be used in matching. If the data comes from an advertising partner then this will most likely be an AppNexus ID. When you are using your own data, users have to be identified via our identity framework, see User Matching below.


Sending data into Permutive

Data should be uploaded to your Permutive GCS bucket in the format described in this document. The Permutive platform will detect new uploads made to this bucket and immediately ingest new data into the platform.

User Matching Taxonomy File Format Data File Format

Any data item included in your upload must have a user ID associated with it. In order for Permutive to tie imported data with a user landing on your site, the same user ID must be available on-site. This could be a user ID picked up by one of our existing cookie syncs, or it could be your own internal user ID that you are using with permutive.identify. The ID must be a string containing up to 100 characters.

Permutive treats these external user IDs as aliases, and each alias has an alias type associated with it. We typically rely on other third-party IDs such as the AppNexus ID to match Permutive users with second and third-party data that are sent into the platform. This alias has type Appnexus. If Permutive is not already picking up AppNexus IDs for your users, or if you’d like to send a different third-party ID in your data imports, please discuss this with our support team.


Below, we've used a sample scenario where you have data collected on subscribers. This will only apply to visitors who have logged in. We assume that when a user logs in you will have an opportunity to execute code and will have some form of internal ID for that user (in variable).  You could then use this code to associate the login ID with that visitor:


We would be able to use the subscriber_id as a user ID alias in the audience data.

Please do refer to our Identity Framework Guide for more details.

Note: Ensure that the value passed as an id is never empty as these would cause ingestion errors and could make different users on the platform collapse into one.


Warning: It is important to ensure that the CPM is listed as '0' when importing second-party cohorts. There is no additional charge to import second-party data. However, if there is any number larger than zero listed for the CPM, you will be charged for that amount as part of third-party billing.

Data Upload

All data should be uploaded under a 2p subdirectory in your bucket:


You will need a data provider ID for each second-party data partner you import data from. Please liaise with our support team to ensure your second-party data IDs are set up prior to beginning data uploads and to ensure you know the alias type for your uploads.

The exact URL will be provided after bucket and data provider creation.

For efficiency, data files should be uploaded in compressed format. Please gzip compress your files prior to upload. Post compression, file names should end with a .gz extension.


To ensure seamless data ingestion, we impose some system limits for each file upload. If you think you will need to exceed these limits, please let us know.



User IDs per file


Total daily data volume

40 GB


Please be advised that the turnaround time for setting up your GCS bucket will be between 2-3 weeks.


Creating Cohorts with Second-party Data

Once our support team has confirmed the cohorts are available:

1. Navigate to the 'Audience' > 'Custom Cohorts' tab in the Permutive dashboard

2. Select '+ Add Cohort'

4. Set up any first-party rules

5. Choose '+OR/+AND' and then 'Second party'


6. Search for and select the relevant second-party cohort

7. Save the cohort


If you have any questions, please contact customer support by emailing or chat to the Customer Operations Team via the LiveChat icon in the bottom right corner of your screen.


Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request