Skip to main content

Access referral data

You can always access your

referral
Referral

A positive outcome of a customer's interaction with an offer. For example, the customer opts in to subscribing to an email list, downloading a mobile app, or being directed to a website.
data through Rokt in any way that makes the most sense for you and your business. Options for this include:

  1. Via API.
  2. Via SFTP.
  3. Via Email.
  4. Via Mailchimp.
  5. Manually.

Metadata

The following table contains a list of accessible data attributes (if available and requested by an advertiser), once customers opt in to a campaign for both of Rokt’s campaign types. Remember, advertisers do not have access to any partner data in any circumstance.

note

The list of attributes available may vary based on the partner site where the offer was displayed.

AttributeData formatDescriptionExample value
ZIP/postal codeIntegerThe customer's ZIP or postal code10010
CountryTextThe customer's countryAustralia
GenderTextThe customer's genderMale
AgeIntegerThe customer's age25
Date/timeDate/TimeThe date and time that the customer opted in to the offer43765.07083
StateTextThe customer's stateCA
SuburbTextThe customer's citySeattle
Bid priceDecimalThe amount the client was charged for the referral2.50
Birth dateDate/TimeThe customer's birth date33569
Ad responseTextThe positive response text that the customer clicked on to opt in to the offerYes, please
Ad textTextThe offer text the customer was presentedReceive a call today to hear about our great value.
Ad text (HTML)TextThe offer text in HTML format<p>Receive a call today to hear about our great value.<p>
Audience IDIntegerRokt internal identifier for the audience that the customer was part of
Length and format of this ID is subject to change.
2581697744617019994
Audience nameTextThe name of the audience that the customer belongs toM/F: 25+
BrowserTextThe customer's browserChrome Mobile
Browser versionIntegerThe customer's browser version (major release)52
Browser version (full)DecimalThe customer's browser version (including major and minor release information)52.109
Campaign IDIntegerRokt internal identifier for the offer that the customer opted in to.
Length and format of this ID is subject to change.
1112223334445556667
Campaign nameTextThe name of the offer that the customer opted in toBrand name, Rokt, Hybrid, 2019
Country codeTextThe customer's country (in ISO two-digit format)AU
Coupon codeTextThe coupon code issued to the customer (only applicable if campaign contained coupons)ROKT1234
Creative IDIntegerRokt internal identifier for the creative that customer opted in to.
Length and format of this ID is subject to change.
2.26E+18
Date/time (UTC)Date/TimeThe date and time that the customer opted in to the offer (UTC timezone)43765.2375
DeviceTextThe device platform of the customer when they opted in to the offerMobile
Device manufacturerTextThe manufacturer of the device the customer used they opted in to the offer.
Only applicable where Device is Mobile.
Samsung
EnvironmentTextThe environment the partner's widget was shown onPurchase
ExperienceTextThe experience the partner's widget was shown onOverlay
PlacementTextThe placement of the offer the customer opted in toPrime
Referral typeTextThe referral type of the offer the customer opted in toEmail
Rokt identifierTextRokt internal identifier for a specific referral.
Length and format of this ID is subject to change.
aa169abb-6552-3638-82b1-224b389fce5b

Referral export templates and custom fields

note

This option is only avaliable for use alongside the email and SFTP refferal export option.

You can create and manage templates for referral exports using the following instructions:

Create a template

  1. Go to the Campaigns > Customer Data page from the left navigation menu, and ensure you are on the Referrals tab.

  2. From the Template drop down menu, select Create custom template.

Template Creation

  1. Enter a name for your custom template.

Template Creation

  1. Select the required fields for your template.

Template Creation

  1. Reorder your fields in your template as desired.

Template Creation

  1. Click Save.

Template Creation

  1. Select your new custom template from the template dropdown.

Template Creation

Edit a template

  1. Select the custom template you want to edit.

    Template Editing

  2. Click Edit existing template.

    Template Editing

  3. Add or remove fields to your existing custom template.

    Template Editing

  4. Reorder your fields in your template in the desired order.

    Template Editing

  5. Click Save.

    Template Editing

  6. Select your new custom template from the template dropdown.

    Template Editing

Custom fields

To create a custom field for referral exports, you need to:

  1. From the left navigation menu, go to Campaigns > Customer Data, and ensure you are on the Referrals tab.

  2. Click Customize fields.

  3. Click New custom field.

  4. Select a field to transform and enter a name for your custom field.

  5. Select a condition: equals or contains.

  6. Enter the value you want to map and the new field name.

  7. Select how the custom field should be handled if empty.

  8. Select the default value in case no match is found.

  9. Click Save.

Via API

Our data management platform provides the ability for you securely access referral data for your campaigns. One of the popular options is integrating directly with your CRM via API.

An API is the most efficient way for Rokt to deliver referral data to you. This is because it works in real-time, meaning that as soon as a referral is generated for your campaign, Rokt can communicate the lead to you. There are a few technical pieces required to get this completed, which are outlined below.

Requirements

To begin the API setup, Rokt requires a few pieces of information.

The following details should be sent to your account manager:

  1. Full API documentation on how to create subscribers in your system.
  2. Technical contact details to help troubleshoot setup queries.
  3. Endpoints for any relevant environments (production, testing, staging, etc.).
  4. Method (e.g., GET, POST, PUT)
  5. Authentication (if any)
  6. Request body encoding (e.g., JSON, XML, URL Encoded)
  7. Required API parameters (Learn about what attributes Rokt can share).
  8. Expected API responses to help Rokt accurately categorize leads delivered successfully versus those that were rejected.

API documentation

API documentation can encompass some or all of the points listed as requirements such as:

  • Endpoint
  • Method
  • Body

This should detail exactly how Rokt can deliver leads to your system.

The API documentation as well as a technical contact should be sufficient to start the API setup process.

For a good example of API documentation, check out the Mailchimp API documentation.

Technical contact details

Provide the relevant contact (either yourself or someone else on your team) who's best suited to address any questions about the API setup process.

The technical contact should be able to help with:

  • Verifying that test leads have been recorded successfully in your system
  • Explaining why we're receiving a response status of 403

For example:

John Smith

Technical Support

john.smith@company.com

Endpoint

This is the location where Rokt should deliver data. If you have a staging or testing endpoint, this will help the Rokt team during the setup and testing process so that no test leads are delivered to your live CRM.

For example: https://us9.api.mailchimp.com/3.0/lists/abcdefghij/members

Method

This is the HTTP request type that Rokt uses to deliver data to your list. The majority of the time, this is a POST request.

Rokt supports the following submit methods:

  • GET
  • POST
  • PUT

Authentication

Provide any authentication details necessary for Rokt to call your API. This could come in many forms, such as:

  • User name and password combination
  • An API key
  • Client ID and secret

API parameters

Provide a list of parameters for Rokt to include through in each API request. If possible, specify any:

  • Required attributes (attributes that must be sent in order for the request to succeed)
  • Optional attributes
  • Parameter names for each attribute (whether to use firstname, FirstName, or first-name, for example)

Common attributes include:

  • Email
  • First name
  • Last name
  • Source
  • Country

For reference, Rokt can share any of these attributes.

Rokt supports the following body encoding:

  • JSON
  • URL encoded
  • Plain text
  • XML

Expected API responses

By providing a list of possible API responses, Rokt can set up response handling logic to quickly identify leads that were delivered successfully, versus those that failed to deliver or were labelled as duplicates.

The response handling could be created based on the status code we receive or the response body, depending on how your API is set up.

Example status codes:

  • 201 (lead created successfully)
  • 400 (unauthorized)
  • 500 (server error)

Example response body values:

  • "successfully delivered"
  • {"status": "duplicate"}
  • {"success": false}
caution

Work with your Rokt account manager to complete the API setup process described below.

Setting up the API connection

  1. Log into One Platform, and click on your account on the Home page.

  2. Go to the Integrations > Connections page in the left navigation menu.

  3. Click Add connection.

  4. Under Referrals, click API.

    Referral Export via API

  5. Give your connection a name.

    Referral Export via API

  6. Enter the endpoint for your connection.

    Referral Export via API

  7. Enter all the required information under Authorization, Headers, and Body.

    Referral Export via API

  8. Enter all your Response handling rules.

    Referral Export via API

Testing your API connection

  1. Once your API connection is set up (endpoint, authorization, headers, body, and response handling), click Settings.

    Referral Export via API

  2. Edit the testing settings according to your test criteria.

    Referral Export via API

  3. Click Save.

  4. Click Test.

    Referral Export via API

  5. Check your test result.

  6. Repeat tests until you've achieved your desired outcome.

Linking campaigns to your API connection

  1. Go to the Real-time referral page.

  2. Expand the connection that you want to link a campaign to.

    Referral Export via API

  3. Click Show unlinked.

    Referral Export via API

  4. Find the campaign that you want to link to your connection and click Link.

    Referral Export via API

  5. The campaign is now linked to your connection.

    Referral Export via API

Unlinking campaigns from your API connection

  1. Go to the Real-time Referral page.

  2. Expand the connection that you want to link a campaign to.

    Referral Export via API

  3. Find the campaign that you want to unlink from your connection and click Unlink.

    Referral Export via API

  4. Click Show unlinked.

    Referral Export via API

  5. Confirm that your campaign is now unlinked from your connection.

    Referral Export via API

Via SFTP

Secure File Transfer Protocol (FTP) connections allow you to automate your referral deliveries and require little effort to set up. All you need are your SFTP credentials, and you’re ready to go!

Once you set up an SFTP connection, you can routinely receive an email with a .csv file containing all of your new referrals and associated metadata.

You can either use your own SFTP connection, or Rokt's connection.

Rokt's FTP connection

Before you begin

Make sure you have access to the Rokt SFTP. If you don't, reach out to your account manager to have access provisioned.

You should also have the following information ready before setting up your connection to the Rokt SFTP:

  1. Delivery frequency—how often and at what times referrals should be uploaded to the SFTP server.
  2. Required parameters—the most common being email, first name, last name, source, and state. Learn more about the metadata Rokt can provide.

Establishing a connection from a host computer (e.g., your laptop) to a secure FTP server requires third-party client software. This tutorial suggests the popular and free client FileZilla which is available for Windows, Mac, and Linux operating systems.

  1. In your browser, navigate to https://filezilla-project.org/ and click Download FileZilla Client.
  2. Install FileZilla on your computer. If you already have FileZilla installed, ensure you are running the latest version.
  3. Reach out to your Rokt Account Manager to request access to the Rokt SFTP. Once you've been granted access, you should receive an email from Rokt with the subject "You've been granted access to Rokt's SFTP server."
  4. Download the attached file and unzip the encrypted file using the password provided in a second email "Email for password for file with instructions."
  5. The encrypted file you have just unzipped contains a .pem file which is your key file to access Rokt's SFTP folder.
note

The following steps are the same for Windows, Mac, and Linux operating systems and are based on the latest version of FileZilla.

  1. Open FileZilla and navigate to File > Site Manager

Rokt SFTP Setup

  1. On the left, click New Site and fill in the following:
  • Protocol: SFTP – SSH File Transfer Protocol

  • Host: ftp.rokt.com

  • Port: 22

  • Key file: Browse to your local key file (.pem) and select it from your local drive (see image below).

    Rokt SFTP Setup

  1. Click Connect. You should be connected and able see your accessible folders to upload files.

File path and requirements

Referral files are placed in the following file path:

File pathPurpose
/downloadsDownload the referral data provided by Rokt
note

Referral files are automatically deleted from this folder after 14 days.

Using your own SFTP connection

Establishing the connection

  1. Log in to One Platform, then click on your account on the Home page.

  2. Go to the Integrations > Connections page from the left navigation menu.

  3. Click Add connection.

  4. Under Referrals, select FTP.

  5. Select the Campaign and Template for this connection, then give your connection a name.

    Referral Export Via Client SFTP

  6. Enter Directory and file name.

    Referral Export Via Client SFTP

  7. Enter your FTP server host details and port.

    Referral Export Via Client SFTP

  8. Select your desired FTP method.

    Referral Export Via Client SFTP

  9. Enter your Username and Password, or enter your username and upload your key file if using SFTP.

    Referral Export Via Client SFTP

  10. Select your schedule and click Save.

Referral Export Via Client SFTP 11. Your connection has been created.

Disabling your FTP connection

  1. Go to the Connections tab and select Scheduled from the leftmost drop-down menu.

    Referral Export Via Client SFTP

  2. Under Actions, click the pause icon.

    Referral Export Via Client SFTP

  3. Your connection is disabled.

    Referral Export Via Client SFTP

  4. You can reverse these steps to enable your connection.

Via email

Rokt can schedule delivery of referral files (in .csv format) to you via email. While this method is less secure and requires manual processing to download the files from your email account, it can be a useful way to get started getting referral data from One Platform. You can always switch to an SFTP or an API solution in the future.

Before you begin

An email delivery setup only requires the following pieces of information:

  1. Email address (or a list of multiple email addresses) where the referrals should be delivered.
  2. Delivery frequency—which specifies how often and at what times you want to receive referral emails.
  3. Required parameters—the most common being email, first name, last name, source, and state. Learn more about the attributes Rokt can provide.

Setting up an email connection

  1. Navigate to your account in One Platform.

  2. Go to Integrations > Connections in the left navigation.

  3. Click Add connection.

  4. Under Referrals, click Email.

  5. Select the campaign and template for this connection.

Referral Export via Email

  1. Give your connection a name and click Next.

Referral Export via Email

  1. Enter the destination email addresses and click Next.

Referral Export via Email

  1. Select your desired schedule and click Save to create your email connection.

Referral Export via Email

  1. Your email connection has been created for the linked campaign.

Referral Export via Email

Disabling an email connection

  1. From the left navigation menu, go to the Integrations > Connections page and select Scheduled from the drop-down menu.

    Referral Export via Email

  2. Click the pause icon.

Referral Export via Email 3. Your email connection is disabled.

Referral Export via Email

  1. You can reverse these steps to enable your connection.

Via Mailchimp

You can integrate Rokt with Mailchimp, an email service provider and marketing automation platform specializing in ecommerce businesses. This keeps your Mailchimp CRM data as current as possible (Rokt posts new referrals every five minutes) so you can focus more energy on strategizing for your campaigns and less on managing them.

note

A more complex API setup is available under the API option on the Connections page. You will still be required to set up a referral delivery task in addition to the API configuration. Find the instructions here. There is a separate setup for importing custom audience lists via Mailchimp which you can find here.

Retrieving API keys from Mailchimp

  1. Log in to your Mailchimp account. Click on your name in the top right corner. From the drop-down menu, choose Profile.

    Referral Export via Mailchimp

  2. Go to the Extras drop-down menu and choose API keys.

    Referral Export via Mailchimp

  3. You can either use an API key you have already created, or create a new one by clicking Create a key.

    Referral Export via Mailchimp

    • Take note of the API key Mailchimp has generated for you.
  4. Reach out to your Rokt account manager to complete the setup.

Manually

Your data is always accessible on the Rokt platform. This is useful if you want to look at all of your referrals over a certain timeframe, or if you need to do some ad-hoc troubleshooting.

If something goes wrong with an existing connection, such as an API failure or an email that got deleted, don’t worry! You can always log in to the Rokt platform and download the referral data for your campaigns.

Getting set up to access your referral data within the Rokt platform is simple and straightforward:

  1. Let your account manager know you would like access, and they will send an invitation to your email address.
  2. Log in to the platform and click on your account on the Home page.
  3. Go to Campaigns > Customer Data in the left navigation menu.
  4. On the Referrals tab, select any filters such as the time range, campaigns, or data attributes that you’d like to view.
  5. Download the data by clicking Export. You can also select Export Via Email if you don’t want to wait for the referral file to download. Rokt will send a .csv file to your email upon completion.

Referral Export Manually

note

A maximum of 100,000 records can be downloaded at once.

Was this article helpful?