Ctrlk
Login to UbiQuity
linkedin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Preparing Your Files

What your files need to look like before you place them in your configured storage location.

Overview

Import Connectors process files automatically, so your files must follow a consistent structure from the start. Most import failures are caused by formatting changes, missing required fields, or structural differences between the sample file used during setup and the files placed in storage. Getting this right upfront avoids the majority of issues.

Supported file formats

Connectors support flat files in CSV format only.

Your file must:

  • Be a CSV file

  • Contain a single header row

  • Use a consistent delimiter

  • Match the structure of the sample file uploaded during Connector setup

Header and column structure

Header row

The first row of your file must contain column names. These names are used for field mapping and must remain consistent across all future files. Do not rename header fields after the Connector is activated unless you update the mapping configuration first.

Column consistency

Once a Connector is active, treat the file structure as fixed. Do not:

  • Add new columns without updating the mapping

  • Remove mapped columns

  • Rename columns

  • Change the delimiter

If structural changes are required, update the Connector configuration before uploading the file.

Required fields and data validity

Before uploading a file, confirm:

  • All required fields are present and contain valid values

  • Data types match expected formats

  • Date formats are consistent throughout the file

  • Boolean values use a consistent representation

Invalid or missing required data may cause rows to fail during import. See Field Mapping for detailed validation behaviour.

File naming and pattern matching

Your file name must match the file pattern configured in your Connector. Patterns support wildcards.

For example, if your file pattern is contacts-*.csv, valid file names include:

  • contacts-2026-02-01.csv

  • contacts-weekly.csv

Files that do not match the pattern will not be processed.

Upload timing

Import Connectors scan configured storage locations every five minutes. To avoid errors:

  • Ensure files are fully uploaded before the next scan cycle

  • Do not modify a file while it is being processed

  • Avoid uploading partial or temporary files that match the file pattern

For large files, confirm the upload completes before the next scan window.

Handling duplicates

If deduplication is configured, duplicate rows will be removed based on the unique identifier defined in your Connector. If deduplication is not configured, duplicate rows will be imported as provided.

Be clear on your deduplication strategy before activating the Connector.

Combined Contact and Transactional imports

If your Connector imports to both the Contact and Transactional databases:

  • Ensure the file structure supports both record types

  • Confirm which fields apply to Contact records and which apply to Transactional records

Incorrect structuring may result in skipped or failed rows.

Common mistakes to avoid

Most file-related failures come down to the same recurring issues:

  • Renaming columns after the Connector is activated

  • Changing the delimiter or file encoding

  • Uploading incomplete files

  • Using inconsistent date or boolean formats

  • Forgetting to create required fields in UbiQuity before uploading

Last updated

Was this helpful?