Skip to main content

​
What this is

A Flat File source brings data into Zeotap CDP: you upload CSV or JSON files to the storage location provisioned for the source, and Zeotap ingests the records so you can map their fields to your Catalogue. This page collects the practices that keep that ingestion clean — how to shape the files, how to keep successive uploads consistent with the source definition, and what to validate before the source goes live. For the opposite direction — sending an audience out of Zeotap CDP to an external platform — see Destinations. These recommendations apply to every Flat File source. For a Zeotap Google Cloud Storage source the upload methods are the Zeotap CDP interface, the Google Cloud Console, gsutil, or a third-party client such as Cyberduck.

​
Prerequisites

Before these practices apply, you need:
  • A Flat File source created in Zeotap CDP, with its file format, delimiter and region already chosen — see Create a Zeotap Google Cloud Storage Source.
  • Access to the upload path for that source, listed under Path Details on the source’s Implementation Details tab.
  • A sample data file containing real data, which you will use for the validation checks below.

​
Prepare the data in your files

​
Include at least one user ID per source

Each file must carry at least one user ID. This can be your own first-party user ID — it must be the same ID you send in the Web JS or app SDKs — and preferably a digital identifier such as a MAID alongside it, so the records can be used for user matching.

​
Include country data in every record

Records must be tied to a country before data collections can be created, so always attach the country as a field in your files. If you do not, the country has to be hardcoded later. Use alpha ISO 3 country codes when sending country information. See Configure the Country Enricher for how the value is interpreted during mapping.

​
Map countries to the correct region

Upload each file to the region that matches the country of its records — Spanish data must not be uploaded to the US bucket, for example. If your data covers users in several countries, split the files by country first, then upload each file to the appropriate region bucket. This keeps the data privacy and compliance boundaries intact. The full country-to-region mapping is listed in Region of Storage, and the regions available for upload are listed under Upload Specifications on Create a Zeotap Google Cloud Storage Source.

​
Start with the fields that matter

There is no restriction on the schema, but we recommend checking the Zeotap Catalogue first and start with only the fields that are relevant to the source. Create new sources for newer data points you want to capture. If you start sending new fields for an existing source, map those new fields before the data can be ingested.

​
Keep every upload consistent

​
Use the same file format and delimiter for every file

When you upload several files under one source, all of them must use the file format and delimiter defined when the source was created. If the source was created as a CSV file with the semicolon (;) delimiter, every subsequent upload to that source must use the same format. Failure to do this results in data corruption. CSV files must not contain double quotation marks ("), and their fields must be separated by a comma (,) only. Download the sample file for a worked example.

​
Keep column-name casing identical

When you upload several files under one source, always name the same attribute the same way, with the same casing. Consistent casing is what allows the column to map correctly at the collection level; a change in casing is treated as a new column.

​
Upload to the exact path

If you are not uploading from the Zeotap CDP interface but through another method — the Google Cloud Console, gsutil, or Cyberduck — the files must land on exactly the path listed under Path Details for the source. Files uploaded elsewhere can affect the processing of that data, and in turn the reporting and segment creation built on it.

​
Validate before you go live

Run the three checks below — on the file, against the Catalogue, and on the mapping — using a sample file before you rme.

​
Validate the file

Take a sample data file with actual data and check that:
  • The encoding type is one of the supported file formats.
  • The file format matches the option selected on the source.
  • The delimiter matches the option selected on the source.
  • No fields are repeated.
  • Every column has a header. After ingestion, confirm this on the Preview Data tab — a column shown as _CX had no header in the file.

​
Validate against the Catalogue

After the source is created, push a sample data file with actual data. The values passed for each field must be in line with the Catalogue definition. Check that:
  • The data type of each value matches the Catalogue field.
  • The attribute type matches the Catalogue field.
  • Each date field’s timestamp format is one of the acceptable formats.
  • The country value is ISO 2, ISO 3, or hardcoded — see Configure the Country Enricher.
  • Field-name casing is consistent across the source Catalogues.

​
Validate the mapping

Before you save the mapping, check that:
  • Each field is mapped to the correct Zeotap field — see Map the Catalogue for Customer Data.
  • Enrichers are applied wherever required, and match the incoming value.
  • The timestamp format is selected from the list of supported formats. Once selected, the system continues to expect that same format for the rest of the source’s lifetime — see Configure the Timestamp Enricher.

​
Troubleshooting

​
Next steps

Last modified on October 6, 2026