Review CSV
Overview
If you don’t want to connect directly to a review datasource like Apple App Store, Google Play, a retailer, or a similar site, you can export the data into a CSV and upload it into Artifact. This document provides guidance on common review sources and how the CSV should be formatted: both the required fields and the optional metadata fields. It also goes over the optional, supplemental CSV you can upload for person metadata. Following this guide will help you have an easy and seamless upload process.
Sample review CSV
Each of these fields will be covered in more depth below, but here is what a review CSV could look like. This example includes the required fields (interaction_id column - version column) and two review metadata fields (style and retailer).
Review CSV Guidelines
Required Columns
The review CSV you upload to Artifact must contain the following columns of data for Artifact to be able to synthesize the data and link customers together across interactions.
We will reference this Amazon review to demonstrate what each of the required and optional metadata fields would be.
interaction_id: This is an id that is inclusive of all of the back and forth between a customer and a company. For reviews, this is often just the single review. The column is required and the value can’t be null, an empty string, or contain any spaces. If your data doesn’t have a unique ID for every complete interaction, you’ll need to create one.
Example from the Amazon review: 6482495
*Since an id isn't provided in the Amazon review, an interaction_id was made up
verbatim_id: This is an id for each response within the interaction. For reviews the verbatim_id and the interaction_id could be the same. However, if a customer leaves a review and then the company responds, there would be one interaction_id (that’s inclusive of both the customer review and the company’s response) and two verbatim_ids (one for the customer review and one for the company response). This column is required and the values must be unique. Values can’t be null, an empty string, or contain a space. The pairing of the interaction_id and the verbatim_id should be unique.
Example from the Amazon review: 6482495
*Since there is only one verbatim in this interaction, the verbatim_id can be the same as the interaction_id
text: This is the text from the review – what the customer said. The column is required and the field can’t be null or an empty string.
Example from the Amazon review: I didn’t realize it would be light blue which is exactly what I was wanting but didn’t want to wait weeks for! At first I was sad I didn’t go with a bigger size but the 30 oz is actually perfect and easy to carry around. It mostly sits on my desk but I do take it in the car and to the park sometimes and a bigger one would not be practical. Came semi quickly with a short delay and price was right.
created_at: This is the timestamp of the review. The column is required and the field can’t be null. The format should follow the ISO 8601 standard, as follows: 1990-01-15T00:34:60.026490+09:30.
Example from the Amazon review: 2023-04-28T00:00:00.000000+00:00
*Since the time wasn't specified, I set it as midnight.
updated_at: This is the last time the review was updated. If it hasn’t been updated, then this would be the same as the created_at date. The column is required and the field can’t be null. The format should follow the ISO 8601 standard, as follows: 1990-01-15T00:34:60.026490+09:30.
Example from the Amazon review: 2023-04-28T00:00:00.000000+00:00
*The review was never updated so the date is the same as the created_at value
person_id: This is the ID of the person who gave the review. This column is required and the field can’t be null or an empty string. If your data does not include a person_id, you’ll need to create a unique ID for each person.
Example from the Amazon review: 10159A
*None is provided in the screen shot, so one has been created for this example.
person_full_name: This is the person’s name or username if you don’t know their full name. The column is required, but the fields can be left empty. If left empty, when looking at verbatims in the app, it will be attributed to “unknown.”
Example from the Amazon review: Axl
person_email: This is the reviewer’s email address. This column is required, but can be left empty. If possible, please provide as it helps us to identify a user across all datasources.
Example from the Amazon review: [null]
affiliation: This describes if the review was from a customer (EXTERNAL), from someone within the company (INTERNAL), or from an automation bot (AUTOMATION). This column is required and the field needs to contain either EXTERNAL, INTERNAL, or AUTOMATION. The value can’t be null or an empty string.
Example from the Amazon review: External
rating: This is the associated rating that was given with the review. This column is required, but the value can be null. This should be an integer.
Example from the Amazon review: 5
interaction_title: This is the review title, if provided. This column must be present, but can be null or an empty string.
Example from the Amazon review: Love the color and size
version: This is the product or app version being reviewed. The column is required, but the value can be null or an empty string.
Example from the Amazon review: [null]
Optional review metadata columns
If there is additional information about the reviews (but not the customer) that you want to filter by in Artifact, you can add columns with this information. For example, if I wanted to filter by the style and color fields from the Amazon reviews, I would include these columns and values:
style | color |
30oz | Fog |
Or if I was combining reviews from multiple retailers into one CSV, I could add a column that could look like this:
retailer |
Amazon |
Walmart |
Target |
When going through the CSV upload process, these columns will be left as unmapped.
Optional person metadata CSV
If there is additional information about the customer that you want to filter by in Artifact, this should NOT be added to the review CSV. Instead, once the review CSV has been uploaded, there will be a prompt to add a person metadata CSV. Think of this like a separate customer table in the same datasource.
The person metadata CSV should be formatted as follows:
Person metadata CSV required fields
person_id: This should be the same person_id that is used in the review CSV. The column is required and the value can’t be null, an empty string, or contain any spaces.
person_email: This is the email of the person. The column is required, but the value can be null or an empty string. Please note that this helps us conduct identify resolution across the different data sources so if possible, please provide it.
created_at: This is when the person was first seen or created within the review data. The column is required and the field can’t be null. The format should follow the ISO 8601 standard, as follows: 1990-01-15T00:34:60.026490+09:30.
updated_at: This is the timestamp for the last time the person was updated. The column is required and the field can’t be null. The format should follow the ISO 8601 standard, as follows: 1990-01-15T00:34:60.026490+09:30. If no updates have happened, then the value would be the same as the created_at field.
Optional metadata fields
After the required columns, any metadata that you want to filter on can be added. Some examples of person metadata that you would want to filter on include customer_state, customer_country, role, segment, or last_seen.
Important considerations for the review CSV
The number of interactions in the CSV will be subtracted from your monthly amount.
Person data doesn’t affect your monthly interactions.
Don’t upload interaction data older than your look back period.