Skip to main content
Log in
Cust Docs

Amazon S3

Sync CSV exports from an S3 bucket into customer records, metrics, and product events.

Each S3 sync reads one folder on a schedule. Cust assumes an IAM role you create to read the selected bucket and root folder. Admins and Owners manage the connection in Settings → Integrations → Amazon S3.

Prepare the files

Place UTF-8 .csv or .csv.gz files in a subfolder, such as cust/accounts/ or cust/usage/. The first row must contain unique, non-empty column names. Column names are trimmed and treated as lowercase. Blank cells are read as empty values.

Choose columns for the destination you want to import. For example, a company export needs a stable External ID; a metric-values export needs the record External ID, metric slug, value, and measurement date.

Connect the bucket

  1. Open Amazon S3 and start the connection wizard.
  2. Enter the Bucket name and an optional Root folder, such as cust/. Each sync will select a folder beneath it.
  3. In Role, use the console steps or generated CloudShell script to create the IAM role.
  4. Use the generated trust policy, including Cust's AWS principal and the External ID shown for your workspace.
  5. Add the generated read policy, which grants s3:ListBucket and s3:GetObject for the selected bucket and root folder. If files use a KMS key, also allow kms:Decrypt on that key.
  6. Paste the role's full Role ARN, then click Connect.

Create a folder sync

Click New sync, choose the destination, and select a Folder relative to the root. With root cust/, enter accounts/ to read cust/accounts/. You can type a nested path such as usage/daily/ even when it is not listed.

Click Run preview to read sample rows from the newest non-empty file. If that file contains only a header, the preview has no sample rows. Match the identity columns, select the fields or metrics, and choose a schedule using Data syncs.

Refresh and troubleshooting

Each run reads matching CSV files under the selected folder, including its subfolders. Files are processed in modification-time order. New or changed files are read again; unchanged files already processed are skipped.

Use stable row identifiers when replacing files so corrections update the same records. S3 syncs do not use a per-row change-tracking timestamp, and removing a source file does not delete records already imported into Cust.

Check the sync's last-run error if a file cannot be read. Interrupted downloads are retried on a later run. For a malformed CSV, fix and replace the file so its changed version is read again. Check the IAM role, bucket policy, root folder, and KMS permissions for access failures.