User Property Upload (CSV Import)

You can upload a CSV file to create or update the properties (custom properties) of multiple users at once.

Based on userId, existing users have their properties updated, and users that do not exist are newly created (upsert). This is useful when you want to apply a large volume of user properties in bulk without individual entry. (Event data is not supported; only user properties are supported.)

CSV File Format

The CSV file you upload must follow the format below.

• The first row is the header.

  • Each column name in the header is used as the key of the property to update.

• The first column must be userId (the identifier).

  • All remaining columns are treated as User Property keys.

• You must include at least one property column other than userId.

• Column names (Property Keys) cannot be duplicated.

  • All Property Keys are case-sensitive.

• All values are stored as strings (String).

  • Properties have no concept of type, so no type specification or casting is applied.

  • To handle dates, we recommend entering them in a form that allows string/number comparison, such as 20260708.

• Array and object formats are not supported.

  • A value must always be a single string.

• All properties are applied as an overwrite ($set).

  • Empty values are ignored and do not overwrite existing values.

• The encoding is UTF-8, and it follows the RFC 4180 rules (handling of commas, quotes, and line breaks).

You can download the sample template (userId, <key1>, <key2> ...) within the Dashboard and fill it out according to the format.

When Some Rows Fail

The overall upload proceeds, but individual rows that fall under the following are not applied and are counted as failures.

• The userId value is empty or blank

• There is not a single property value to apply (all values are empty)

• The property application processing failed

When the Entire Upload Fails

In the following cases, the file is not processed and the entire request fails. Please modify the file according to the guidance message and upload it again.

Situation	Guidance
The first column is not userId (including empty files)	Set the first column to userId and upload again.
Column names are duplicated	Modify the column names so they don't overlap and upload again.
There are no property columns	Add at least one property column other than userId.
The number of records exceeds 1 million	You can upload up to 1 million records. Please check the count.
The file size exceeds 100MB	Reduce the file size to 100MB or less and upload again.

Limitations

• You can upload up to 1 million records at once.

• File sizes up to 100MB are supported.