How Do I Import Users into Piano via SFTP?

What You Can Import

Typical migration packages include the following CSV files:

Imports are validated before processing. If validation fails, Piano generates rejection reports indicating which rows were rejected and why. For a comprehensive overview of the full migration process including subscriptions and payments, see Migration of Existing Users and Subscriptions.

SFTP Delivery Basics

Use SFTP for Sensitive Data

Always transfer migration files using SFTP. Do not share passwords, tokens, or user data through email or support tickets.

Folder Placement and Naming

• Upload files to the folder agreed upon for your application and environment (commonly structured as aid_appName/production for production imports).

• Follow the naming convention required for your migration type. A common pattern is AID_IMPORTTYPE.csv (e.g., _users.csv).

For details on SFTP access and folder structure, see the Migration of Existing Users and Subscriptions guide.

Encoding and Delimiter Requirements

All CSV files must meet the following requirements:

• UTF-8 encoded (prefer UTF-8 without BOM where possible)

• Comma-separated (,), not semicolon-separated

• No extra rows above the header row

• No trailing commas that create unintended empty columns

User File Format Requirements

Required Headers

Use the expected headers exactly (case-sensitive):

user_id,email,first_name,last_name,password,social_accounts,create_date

Common header issues that cause validation failures:

• Wrong casing (e.g., PASSWORD instead of password)

• Wrong header name (e.g., created_at instead of create_date)

• Singular/plural mismatches (e.g., social_account instead of social_accounts)

Core Field Rules

user_id

• Must be unique per user.

• Must match the user_id used in related files such as custom_fields.csv and custom_terms.csv.

• UID mismatches can occur if a user already exists in Piano and the UID in your file does not match what is already stored.

email

• Must be a valid email format (watch for spaces, incomplete domains, or concatenated emails).

• Deduplicate emails before importing to reduce "already exists" or skip errors.

• Ensure each user_id maps to a single email. Conflicting mappings can be rejected.

first_name / last_name

• Do not use \N as a placeholder; leave blank if unknown.

• If values contain commas, enclose them in double quotes per standard CSV rules.

create_date

• Must be formatted as: MM/dd/yyyy HH:mm (no seconds).

• Example: 09/02/2022 17:47

• The column must be present even if values are blank. If blank, Piano may populate it with the import date (behavior depends on the import pipeline).

Password Import Rules

Supported Password String Format

Passwords must be formatted as:

:<ALG>:<ROUNDS>:<SALT>:<HASH>

Or, if no salt is used:

:<ALG>:<ROUNDS>::<HASH>

For the full list of supported hashing algorithms, see Migration of Existing Users and Subscriptions.

Users Without Passwords

If users should be imported without an existing password, use the standard placeholder for passwordless/unknown-password accounts:

:UNKNOWN:::0

Social Accounts Formatting

The social_accounts field in users.csv requires careful formatting:

• Leave the field blank if the user has no social accounts (do not use "").

• Use the correct provider identifiers (e.g., GOOGLE, not deprecated values like googleplus).

• If multiple social accounts exist, separate entries with semicolons (;), not colons.

• Some import flows expect social identifiers in uppercase.

Because implementations vary by migration tooling, social formatting errors are a common source of rejections. Check the rejection report for the exact expected pattern for your tenant.

Importing Custom Fields

Custom fields can be included in your import file. For detailed instructions on formatting, naming conventions, field types, and size limits, see Importing Custom Fields.

Key Points

• All custom fields must exist in the Piano Dashboard before import (navigate to Manage → Custom fields). Imports will fail if the field IDs referenced in the CSV do not exist.

• Custom field columns in the import file must match the field ID (not the localized display label).

• Some import types have strict schemas. For example, a consents.csv file is expected to contain only specific columns. Extra columns will trigger validation errors such as "Too many columns". Ensure each file matches its template exactly.

Validation, Reports, and Re-Import Workflow

1. Upload CSV files to the correct SFTP folder.

2. Validation is run (often managed by Piano for migration imports).

3. Review the output in the SFTP Reports folder, which commonly includes:

   • _imported.csv — accepted rows

   • _rejected.csv — rejected rows with error context

4. Fix rejected rows and re-upload corrected files (often as a "delta" file containing only the corrected rows).

If you encounter intermittent processing issues, re-running the import for only the failed rows is often sufficient.

Production Import Considerations

Production migrations typically have stricter operational constraints than sandbox or UAT environments:

• Scheduling: Production imports are usually scheduled in advance (often weeks ahead for large migrations).

• Volume limits: Large migrations may have daily row limits across all files. Confirm your tenant's limits with Piano Support.

• One-shot nature: Some production migrations are executed as a single scheduled run. If data fails validation, a new slot may be required.

• Delta import: Plan a smaller follow-up import to capture late changes or fixes after the main cutover.

Also ensure the following production prerequisites are met before importing:

• User management and provider configuration is enabled for production.

• Any referenced terms exist in the production environment (term IDs differ between sandbox and production).

• Payment tokens (if applicable) belong to the correct environment and provider account.

For the full list of production migration prerequisites, see Migration of Existing Users and Subscriptions.

Common Rejection Reasons and Fixes

Pre-Flight Checklist

Before uploading your files, confirm the following:

• CSV is UTF-8 encoded (prefer UTF-8 without BOM).

• Delimiter is comma (,).

• Headers match the template exactly (spelling and case).

• No extra columns, no trailing commas, and consistent column count across all rows.

• create_date column is present and formatted correctly (or left blank).

• Passwords are correctly formatted or set to :UNKNOWN:::0.

• Social accounts use correct provider identifiers and semicolon (;) separators.

• Custom fields exist in the Piano Dashboard and column headers use field IDs.

• Emails and user IDs have been reviewed and deduplicated.

• Production prerequisites are confirmed (provider configuration, term IDs, payment tokens).

If you need help interpreting a specific _rejected.csv report, provide the error lines (without sensitive values) and the file type to Piano Support. Most issues can be resolved by adjusting headers, formats, or field prerequisites. For the complete migration reference, see Migration of Existing Users and Subscriptions.

Last updated: June 26, 2026