# Preparing Your Files ### 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ubiquity.co.nz/documentation/data-and-integrations/connectors/preparing-your-files.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.