Flat Files (CE+NCE) - Zeotap docs

What this is

Flat Files are batch data uploads — CSV or JSON files containing customer entity (CE) or non-customer entity (NCE) records — that you send to Zeotap CDP for ingestion. Each record must carry at least one identifier so Zeotap can attach it to a profile: your first-party user ID (identical to the one your Web JS or App SDKs emit), preferably paired with a digital identifier such as MAID. Zeotap supports two transfer channels for Flat Files — a managed Google Cloud Storage bucket and SFTP (a Zeotap-hosted push endpoint or a customer-hosted pull location). This page is the entry point: pick the channel that fits your infrastructure and follow the linked setup guide.

Prerequisites

Before you send your first file, confirm you have:

At least one identifier per record — your first-party user ID (identical to the one sent by your Web JS or App SDKs), preferably paired with a digital identifier such as MAID for match quality.
A country field on every record — Zeotap requires country to build data collections. Alpha ISO 3 country codes are the recommended format; without a country field the value has to be hardcoded on the source later.
A consistent file format and delimiter across every file in a source — the format is fixed at source creation, and every subsequent file uploaded to that source must match it.
A defined mapping to the Zeotap Catalogue — CE data uses the CE catalogue mapping; NCE data uses the NCE catalogue mapping (both linked in Next steps).

Choose a transfer channel

Zeotap supports two Flat File transfer channels. Each is a distinct Source type in the CDP; register one source per channel per data feed.

Zeotap Google Cloud Storage

Zeotap provisions a Google Cloud Storage bucket for your tenant. You upload files to the bucket path assigned to your source using the GCloud Console, gsutil, or a third-party client such as Cyberduck. Zeotap picks up files from the configured path and ingests them.

Uploads outside the Sources UI must land at the exact path assigned to the source. A file placed at the wrong path is not ingested, and the source’s reporting and downstream segmentation will not reflect the data.

Full setup: Zeotap Google Cloud Storage.

SFTP (Secure File Transfer Protocol)

SFTP comes in two variants:

SFTP (Push) — Zeotap hosts the SFTP endpoint; you push files to it. Setup: SFTP (Push) Source.
SFTP (Pull) — you host the SFTP endpoint; Zeotap pulls files on a schedule. Setup: SFTP (Pull) Source.

Both routes are documented under SFTP (Secure File Transfer Protocol).

Prepare the file layout

A minimal CE file has a header row, at least one identifier column, a country column, and any additional attributes you want to ingest. Attribute names and their casing must stay identical across every file uploaded to the same source — a differing case is treated as a new attribute. CSV files must use a comma delimiter and must not wrap values in double quotes:

user_id,maid,email_sha256,country,event_timestamp
u_10012,a1b2c3d4-e5f6-7890-abcd-1234567890ab,3f79bb7b435b05321651daefd374cdc681dc06faa65e374e38337b88ca046dea,USA,2024-01-15T10:30:00Z
u_10013,,f0e9d8c7-b6a5-4321-9876-abcdef012345,DEU,2024-01-15T10:31:15Z

Start with only the Catalogue fields relevant to this source. When you need to capture new data points, either add the fields and update the source’s mapping, or create a new source for them.

Upload files that belong to the correct region for the country of the records — for example, do not upload Spanish records to a US regional bucket. If a single feed spans multiple countries, split it by country before upload and route each split to the appropriate regional bucket.

Verify the source is ingesting

A Flat File source moves through the following statuses as it comes online:

Created — the source exists in the CDP but no data has arrived yet.
Integrated — data has started flowing into the source; Catalogue mapping is not applied yet.
Mapped — at least one data collection is built on top of the source, meaning Catalogue mapping is applied and the data is available for downstream use.

You know the setup worked when the source reaches Mapped status and the record count on the source listing reflects the records from your uploaded files.

Troubleshooting

Ingestion issues with Flat Files fall into a small set of causes, each with a concrete fix. The table below maps the observable condition to what it means and where to check.

Error condition	What it means	Where to look
File format or delimiter differs from the source definition	Data corruption on ingest — the source parses using the format fixed at creation	Source’s configured format; see the Best Practices link below
A field in the file is not mapped to a Catalogue attribute	The unmapped field’s data is not ingested	Source’s mapping configuration
Country field missing from records	Records cannot form a data collection until country is hardcoded on the source	Source’s Catalogue mapping and enricher configuration
Timestamp format differs from the format registered at mapping time	Ingestion fails — the source expects the format chosen at mapping time throughout its lifetime	Source’s timestamp attribute mapping
Attribute name or casing differs across files	The differing column is treated as a new attribute and is not merged with earlier data	Source’s Catalogue mapping

Symptom — your file uploaded but records did not appear

Confirm the file matches the source’s declared format and delimiter (CSV with a comma delimiter and no quoted-string wrappers, or the JSON structure you defined at creation).
Confirm every record carries at least one identifier — your first-party user ID or MAID.
Confirm the country field is present on every record and formatted as ISO 3.
Confirm every field in the file is mapped to a Catalogue attribute for this source; add mappings for any new fields.
Confirm the file was placed at the exact path assigned to the source (relevant when you upload outside the Sources UI).
If the checks above pass and records still do not appear, contact your Zeotap customer success representative and include the source name, the file name, the upload timestamp, and a sample of the file.

Symptom — ingestion started failing after a working period

Compare the failing file’s schema against the last successful file — attribute names with identical casing must appear in both.
Compare the failing file’s timestamp format against the format registered at mapping time; if the format changed, restore the original format or create a new source for the new format.
Confirm the file was uploaded to the exact path the source expects.
If the schemas match and the path is correct, contact your Zeotap customer success representative with the source name, the file name, and the upload timestamp.

​What this is

​Prerequisites

​Choose a transfer channel

​Zeotap Google Cloud Storage

​SFTP (Secure File Transfer Protocol)

​Prepare the file layout

​Verify the source is ingesting

​Troubleshooting

​Symptom — your file uploaded but records did not appear

​Symptom — ingestion started failing after a working period

​Next steps

What this is

Prerequisites

Choose a transfer channel

Zeotap Google Cloud Storage

SFTP (Secure File Transfer Protocol)

Prepare the file layout

Verify the source is ingesting

Troubleshooting

Symptom — your file uploaded but records did not appear

Symptom — ingestion started failing after a working period

Next steps