Users can be created, updated with audience attributes, and optionally deactivated by routinely uploading a file containing user data via SFTP. Brand Super Admins may subscribe to email confirmations when a file is processed via SFTP. This confirmation email includes information on updates to user access, and a link to a report on any errors.

To update the mailing list for these notifications, please contact Support.

User Sync Actions

Users may be created, updated, blocked or unblocked via User Sync.

User sync processes user records by comparing a newly uploaded CSV file (referred to as the Latest File) against a previously synced CSV file (the Previous File) and existing user statuses in Studio.

• In Previous File & In Latest File → Update
  The user exists in both files: update their profile data based on any changes.

• In Latest File & Not in Previous File → Create / Update / Unblock

  A new user has been added or re-added: the sync will either create a new profile, update an existing one, or unblock the user if they were blocked.

• In Previous File & Not in Latest File → Block

  A user that was previously active but is now removed from the latest file: their account will be blocked.

• Not in Latest File & Not in Previous File → Do Nothing

  Users that are not managed by the user sync file: accounts will not be updated.

Be aware that manually blocking or activating users in Studio may be result in the following:

• If a manually blocked user is re-listed in the latest file, they will be unblocked.

• If a manually activated user is in the latest file, they are updated.

• If users are not in the latest file, the sync does nothing, preserving their current manual status.

It is best practice to always manage user's active status through user sync.

Errors

Errors preventing the entire file from being processed will be shown in the body of the confirmation email (limited to the top 15).

If any records could not be processed due to an error, details on the error(s) (limited to the top 100) will be included in:

• A hyperlinked report. To access this report, ensure you are first signed in to Creator Studio as a Brand Super Admin.
• An attached spreadsheet.

Universal Identifier or Email may be used as the Unique ID for users. If Universal Identifier (usually an employee ID) is used, then the email address for a user may be updated via the SFTP file. However, if Email is used as the Unique ID, then a user's email address cannot be changed. Updating a user's Unique ID will result in a duplicate user being created, or an error will prevent the record from being processed.

User Sync Validation Errors

The following validation errors may occur while validating individual user records.

Identity Validation Errors

One or both of email or identifier must be specified.

Occurs when both of the following fields are blank:

• Email Address
• Universal Identifier

At least one unique identifier must be provided for each user.

Solution: Update the record to ensure data is included for the Universal Identifier and/or Email.

two different users found

Occurs when:

• A user is found using the email address
• A different user is found using the alternate identifier

This indicates the uploaded data references two separate existing users.

Solution: Ensure that correct data is being uploaded. If the uploaded data is correct, then forget at least one of the two accounts.

• Forgetting the user that has the Email in the file will result in your next upload updating the Email address of the user with the correct Universal Identifier.
• Forgetting both users will result in your next upload creating a new account for the uploaded user.

cannot assign additional identifiers to email users

Occurs when:

• A user is matched by email only
• A federated identifier is being assigned
• The user already has a federated identifier associated with their account

This validation prevents assigning additional identifiers to users.

Solution: Find the existing user that the email address belongs to. If searching by email returns no users, please refer to: Identifying Non-Searchable Email Users.

If the existing user has a new Universal Identifier, this must first be updated in Studio. Once updated in Studio, the next uploaded file can process without the error if both Universal Identifier and Email are aligned between file data and Firstup profile. Alternatively, forget the user with the old [Universal Identifier]. This will free up their Email Address to be used by a new account, which will be created when the next SFTP upload is processed.

Universal Identifier and Membership Errors

Federated identifier has already been taken within this brand

Occurs when the provided federated identifier (A.K.A. Universal Identifier) already exists for another user within the same brand.

Federated identifiers must be unique within a brand.

Solution: Find the existing user that the identifier belongs to and forget the user so that a new user can be created with their identifier. If you have more than one program, it's recommended that you check all programs to forget them everywhere.

alternate_identifier is required

Occurs when the feature flag:

• UserSync.Job.ValidateFederatedIdentifierPresence

is enabled and the alternate_identifier field is blank.

is enabled and the alternate_identifier field is blank.

Email Validation Errors

Email address has already been taken

Occurs when the email address already exists for another user and duplicate emails are not permitted.

Solution: Find the existing user that the email address belongs to. If searching by email returns no users, please refer to: Identifying Non-Searchable Email Users.
Either:

1. If the Email belongs to a new employee, forget the user with the old Universal Identifier. This will free up their Email to be used by a new account, which will be created when the next SFTP upload is processed.
2. If the Email belongs to the same employee but their Universal Identifier has changed, update the user's Universal Identifier in Studio. Their account should then sync the next time a file is processed.

Identifying Non-Searchable Email Users

When a user's email address is updated, their old email address is not deleted. Although no longer used as the primary email address for campaign delivery, email address history is stored for each user meaning an email address can still be considered "taken" after it has been updated to a new email address.

Audience builder can be used to do a more advanced email search using the "Email" filter. This will search all emails for a user, not just their primary email.

This audience can then be previewed without saving to identify the user.

Email address is invalid

Occurs when the provided email address is not formatted as a valid email address.

Example:

• user@domain.com

Solution: Ensure a valid Email address is used for all records.

SFTP Upload File Validation Errors

The following errors may occur before user records are processed.

File Format and Encoding Errors

The uploaded file has an unsupported MIME type.

Occurs when the uploaded file format is not supported.

Solution: Ensure the upload command includes the full target filename (e.g., /uploads/filename.csv) or upload to the root folder so that the file extension is preserved. (e.g., filename.csv :.).

The uploaded file is not properly encoded as {encoding}.

Occurs when the uploaded file encoding does not match the expected encoding.

Solution: Ensure all characters are valid in the configured encoding language (most commonly UTF-8). A regex search [^\x00-\xFF] can be used in a text editor to identify non-UTF-8 characters in a CSV file and remove or replace them.

Failed to decrypt uploaded file. Please ensure that the correct encryption key and format is used.

Occurs when the system cannot decrypt an encrypted upload file.

Common causes include:

• Incorrect encryption key
• Unsupported encryption format
• Corrupted encrypted file

CSV and File Structure Errors

The uploaded file contains malformed CSV data: {error}

Occurs when the uploaded file contains invalid CSV formatting.

Examples include:

• Unclosed quotation marks
• Invalid delimiters
• Corrupted CSV structure

Solution: Convert to the correct format based on file setup.

There is no content that can be processed in the uploaded file.

Occurs when the file contains no valid data rows after processing.

Examples include:

• Empty files
• Files containing only headers
• Files containing only comments or blank rows

Line {line_number} has incorrect number ({actual}) of columns. It should be {expected} columns.

Occurs when a row contains more or fewer columns than expected.

Solution: Ensure the correct number of columns is included. Sometime, extra columns may be present but invisible due to extra commas at the end of each row. View the CSV file in a text editor to review this.

User Record Validation Errors

The following errors occur while validating individual rows within the uploaded file.

Required Field Errors

Line {line_number} (user {employee_id}) is missing {field}, which is a required field.

Occurs when a required field is blank for a user record.

Solution: Ensure required fields are filled in for all lines. The relevant required field will be named in the error message (e.g. employee_id, email, first_name, last_name).

Email Validation Errors

Line {line_number} (user {employee_id}) does not have a valid email address (must be formatted as "user@domain.com").

Occurs when an email field contains an invalid email format.

Line {line_number} (user {employee_id}) has the same primary and secondary email address.

Occurs when the primary and secondary email fields contain the same value.

Country Validation Errors

Country must be in ISO 3166-1 alpha-2 code format.

Occurs when country fields are not formatted as valid ISO 3166-1 alpha-2 codes.

Solution: Countries should be uploaded in a standardised ISO 3166-1 alpha-2 code format. For example, "US" is a correct country code, and "United States" is not.

A list of alpha-2 codes can be found here.

Language and Locale Validation Errors

Line {line_number} (user {employee_id}) does not have a valid {field_name} (language tag format).

Occurs when locale or preferred language fields are not formatted as valid RFC 5646 language tags.

Examples:

• en-US
• fr-CA

Timezone Validation Errors

Line {line_number} (user {employee_id}) does not have a valid timezone.

Occurs when the timezone value is not recognized as a valid timezone.

Solution: Time zones should be uploaded in full TZ Database Name format, and not in their abbreviated form. For example, "America/New_York" is a correct time zone, and "ET" is not.
A list of time zones can be found here.

Alternatively, raise with support to have timezone unmapped from the standard timezone attribute. This will lift any validation, but will also result in the member experience profile attribute no longer being updated from the file.

Date Validation Errors

Line {line_number} (user {employee_id}) does not have a valid {date_field} date format.

Occurs when a date field contains an invalid or unsupported date format.

Examples of affected fields may include:

• start_date
• promotion_date
• requisition_approval_date
• date_of_birth

Solution: Different date formats are configurable. Reupload the file with dates in the correct format (e.g. yyyy-mm-dd). Contact Support if you are not sure of the correct date format.

Duplicate User Validation Errors

Duplicate Employee IDs

There is {count} employee ID that is assigned to more than one user each, in the uploaded file.

There are {count} employee IDs that are assigned to more than one user each, in the uploaded file.

Occurs when duplicate employee IDs are found within the same upload file.

{employee_id}, used {count} times. Only one employee ID can be assigned to a user. Please remove any duplicate entries.

Provides detailed information about duplicate employee IDs detected in the upload.

Solution: Ensure that all employee IDs are unique. Each ID should belong to only one user and be used only once in the file.

Configuration and Processing Errors

File group is required but was not provided

Occurs when the upload job configuration does not include a required file group.

Delta Deprovision Protection Errors

The uploaded file could block more than X% of the user base, which may not be intended.

Occurs when the uploaded file would block or deprovision more users than the configured safety threshold allows.

The validation:

• Compares users in the current upload against users from the previous successful sync
• Calculates the percentage of users that would be blocked or deprovisioned
• Compares the result against the configured blocked percentage threshold

If the calculated percentage exceeds the configured threshold, the sync job fails and a notification email may be sent.

This validation exists to help prevent accidental mass deprovisioning caused by:

• Incomplete upload files
• Incorrect filtering
• Failed upstream exports
• Misconfigured integrations

By default, a maximum of 10% of the user base (users in the previous file) can be blocked by a user sync file, to prevent accidental mass deprovisioning of users. If a higher volume of users to be deactivated is expected, contact Support to temporarily increase the maximum blocked percentage.

Notes

• Some validation errors prevent only individual users from being processed.
• Other validation errors may prevent the entire upload file from processing.
• Exact error wording may vary slightly depending on feature flag configuration and processing path.
• Validation behavior may differ between legacy and federated identity configurations.

Why is there a Total user number discrepancy in our HR file and Firstup Standard Metrics?

The number of users in the platform, and the number of users in the HR file may not match for several reasons - Users can be created outside of the user file process. For example:

• You have SSO enabled - users not in the Users Data File can be created if they have been granted access to our application on your IdP. Users are then provisioned when they authenticate through SAML unless they have been explicitly blocked in Creator Studio. They do not need to have been included in the user file - the user file is not an allowlist of users that can access the platform.
• You could also have created users through the Add User (or User Import) functionality that would not be in the user file.
• Users could have started registration through the 'Join Now' page and these registering users would be counted on the Users / Groups page but not in the total from the user file.