CSV upload

Use Import users to add or update customer profiles from a CSV file in the JustAI app. Each row adds or updates one person, matched by email address. Every other column becomes an attribute on that person. When you finish, the people in your file appear in Users with their attributes.

When to use CSV upload

CSV upload suits a one-time list, a small audience for a pilot, or a few test customers before you connect a full data source. Each file holds up to 50,000 people.

Use another source when:

Your profiles change every day. Connect a CDP or the Direct API. If you need a customer-specific file import, confirm availability and procedure with your JustAI team first.
You need events. CSV upload imports profiles only. Send events with the Track API.
You need numbers, booleans, or null values. CSV upload stores every value as text and skips blank cells. Use the Identify API.

Before you begin

The environment you want to import into, selected in JustAI. The account menu at the bottom of the left sidebar shows your organization and environment, for example Acme / Production. The import adds people to that environment only.
Prepare a CSV file with a header row and a column of email addresses.
Add a user_id column with your customer IDs if you also send data through the Identify or Track API, a CDP, or file imports.

Prepare your file

email,user_id,first_name,plan
ada@example.com,user-1234,Ada,pro
grace@example.com,user-5678,Grace,free

Column	Required	What it does
Email	Yes	Identifies each person. The header can be any name. You choose the column during the import.
`user_id`	Recommended	Links each person to your user ID, so later Identify and Track calls with that `userId` reach the same person. See Link people to your user ID.
Any other column	No	Becomes an attribute. The header becomes the attribute name.

To start from a template, select Download a sample on the Import users page. The sample has email, first_name, and plan columns. If you also send data from other sources, add a user_id column to it.

Follow these rules for the file:

One row per person. A repeated email address is rejected as a duplicate. It isn’t merged.
Up to 50,000 rows and 20 MB. Split a larger list into several files.
Headers become attribute names in lowercase snake_case. First Name becomes first_name. A blank header becomes column_ followed by the column number. A header that starts with a digit gets a c_ prefix. A repeated header gets _2 added.
Every value is stored as text. A plan_level of 3 is stored as the text "3", not the number 3.
Quote values that contain commas. Wrap them in double quotes, for example "Lovelace, Ada".
Email addresses are trimmed and lowercased. Ada@Example.com and ada@example.com are the same person.

Link people to your user ID

By default, JustAI identifies people by user ID. A person imported without a user ID is known only by email address. A later Identify call with that person’s user ID then creates a second person.

To prevent that, add a column named user_id or User ID. During the import, each person in the file gets that value as their user ID. A header of userId doesn’t count, because it becomes the attribute userid.

JustAI skips the link, and keeps the value only as a user_id attribute, in two cases:

The person already has a user ID.
Another person already holds that user ID.

How the import updates people

A new email address creates a new person.
An email address that already exists updates that person. Each non-blank cell sets that attribute and replaces its current value.
A blank cell is skipped. It never clears a value the person already has.
Attributes that aren’t in the file keep their values.
The import doesn’t record consent or subscription choices. A column such as subscribed becomes an ordinary text attribute. To record consent decisions, use the Identify API. See Identity and consent.
Imported changes don’t start journeys whose entry is A profile attribute changes. Use the Identify API for changes that must start a journey.

Import a file

In JustAI, select Users.

The All users tab opens.
Select Import users.

The Import users page opens. It shows the steps Choose a file, Map columns, Check the rows, and Confirm.
Drag your CSV onto Drop a CSV here, or select Choose a file.

The Map columns step opens and shows the file name and its number of columns.
Under Which column holds the email address?, check the selected column. JustAI preselects a column named email, or a column whose name contains “email”. If no column is selected, choose one.

Everything else becomes an attribute lists the other columns.
Select Check the rows.

JustAI checks every row. The heading shows the result, for example All 120 rows are usable or 118 of 120 rows are usable. The line below it shows how many people are new and how many already exist, for example 95 new · 23 updated.
Review any rejected rows. The table lists each one with its Row, Column, and Reason. Then choose an action:
- If every row is usable, select Confirm import.
- If some rows are rejected, select Import valid rows only to import the rest. To fix the file first, select Start over.
- If the heading reads No rows can be imported, fix the file and select Upload a different file.
Wait for the import to finish.

The page shows Imported just now and a summary such as 95 added · 23 updated. If rows were rejected, the summary also counts them as skipped.
Select View users.

The All users list opens.

Fix validation messages

JustAI rejects a whole file for these problems:

Message	Fix
That file is not a CSV. Choose a .csv file and try again.	Export the list as a `.csv` file.
That CSV is too large. Split it into smaller files and try again.	Keep each file under 20 MB.
That file could not be read as a CSV. It needs a header row and at least one column.	Add a header row. Check that the file isn’t empty.
That file has 72,000 rows. Split it into files of 50,000 rows or fewer.	Split the list into files of 50,000 rows or fewer.

JustAI rejects a single row, and lists it in the Reason column, for these problems:

Reason	Fix
Email is blank	Add the email address, or remove the row.
`"ada@example" is not a valid email address`	Correct the address.
Duplicate of row 14	Keep one row per email address. Combine the two rows.
Row has fewer columns than the header	The row ends before the email column. Add the missing values.
Row has 6 values but the header has 5 columns	A value contains an unquoted comma. Wrap that value in double quotes.

The Row number counts the header as row 1, so it matches the row number in your spreadsheet. A row with fewer values than the header is accepted when its email cell is present. The missing cells are skipped.

Check your work

On Users, search for an email address or user ID from your file.

The person appears in the list.
Open the person.

Under Attributes, Email shows the address, and the other attributes show the values from your file. If your file had a user_id column, User ID shows that value.

If User ID doesn’t show the value from your file, the person already had a user ID, or another person holds that value. JustAI keeps your value only as the user_id attribute.

The Profiles API reads profiles by user ID. You can read people you imported with a linked user ID through the API. Find everyone else in Users.

To remove a person you imported by mistake, open them in Users and select Delete user.

Other places that import a CSV

Two other uploads add or update people in the same way, with the same limits:

A fixed-list segment: Users > Segments > New segment, then Choose users and Upload CSV.
A blast, a one-time send from Blasts: Upload a CSV when you choose who receives it.

Unlike Import users, these uploads reject the whole file when any row has a problem. Fix the rows with problems and upload the file again.

Next steps

Send customer profilesKeep profiles up to date with the Identify API.

Identity and consentChoose the user ID and email that connect every source.

Choose a data sourceCompare the ongoing ways to send profiles and events.