Skip to content

Export to S3 ​

A scheduled export of your workspace's feedback — tickets, reviews, surveys, chats — delivered as Parquet files to an AWS S3 bucket, so it can be loaded into your own warehouse alongside everything else you already have.

The export is set up with us rather than from the platform. Tell your Zefi contact which fields you want and which delivery option suits you, and we will take it from there.

FormatParquet, one row per record
DeliveryAn S3 bucket — yours, or one we host for you
ModeIncremental: new and changed records only
ScheduleDaily suggested, hourly at most

How it works ​

Only what changed ​

Each run contains the records that are new or changed since the last successful run, and nothing else. Load the files in order and you always end with the current state.

The first run covers only the last hour. History is not backfilled automatically — if you need it, a full backfill can be agreed separately.

A record can appear more than once ​

A record is a single ticket, review, survey answer, chat and so on. When it changes — a CSAT answer arrives, or its topics are re-classified — it is sent again in a later file.

Keep the latest row per Source ID. Appending every file without de-duplicating will count changed records more than once.

A failed run loses nothing ​

The next run picks up from where the last successful one stopped, so a failure delays data rather than dropping it.

Schedule ​

Hourly is the most frequent option, but we suggest daily: fewer, larger files and a simpler load job, and you still receive every change.

File naming ​

text
zefi_export/zefi_export_<YYYYMMDDTHHMMSS>.parquet

The timestamp is when the file was written, in UTC. If nothing changed since the last run, no file is written — an hour or a day without a file is not an error.

The column order is fixed ​

New columns are only ever added at the end, so positional loads such as Redshift COPY keep working when the export grows.

Names, not IDs ​

Topics, subtopics and segments are exported as their names, exactly as you see them in the platform. Renaming a topic in Zefi changes the value in rows exported after the rename.

Fields ​

Choose the fields you need. Each one is named after the standard filter it matches in the platform, so the export shows the same thing the platform does. We send you the exact column names when the export is set up.

Array fields (STRING[]) can hold more than one value per record.

Always included ​

FieldTypeWhat it holds
Source IDSTRINGThe record's ID in the original system, e.g. the Zendesk ticket ID. The key to de-duplicate on.
Source URLSTRINGLink to the record in the original system, when there is one.
ContentSTRINGThe feedback text. If translation is enabled for your workspace, this is the English translation.

When and where ​

FieldTypeWhat it holds
CreatedTIMESTAMPWhen the record was created in the original system.
UpdatedTIMESTAMPWhen the record was last updated in the original system.
SourceSTRINGWhere the feedback comes from: zendesk, appstore, playstore, trustpilot, typeform, zefi (Zefi surveys), …
Interaction TypesSTRING[]review, chat, ticket, message, comment, survey, interview, email, note, meeting, call, page
Survey CampaignsSTRINGThe survey campaign the answer belongs to. Survey records only.
Original LanguageSTRINGLanguage detected in the original text, e.g. ita, spa, eng.

Who ​

FieldTypeWhat it holds
CustomersSTRINGThe customer or company the feedback is from.
AgentsSTRINGThe agent or account manager who handled the record, e.g. the Zendesk assignee.
SegmentsSTRING[]The segments configured in Zefi that the record belongs to.

What it is about ​

Assigned by Zefi's classification.

FieldTypeWhat it holds
TopicsSTRING[]Main topics from your Zefi taxonomy found in the feedback.
SubtopicsSTRING[]The more detailed subtopics under those topics.
Signal GroupsSTRING[]The third taxonomy level, below subtopic. Only filled for workspaces on a three-level taxonomy.
CategoriesSTRING[]Type of feedback: issue, request, doubt, praise, distrust, churn.
UrgencySTRINGnone, low, medium, high, critical

Scores ​

FieldTypeWhat it holds
SentimentINTEGER 1–5Sentiment inferred from the text. Not a score the customer gave.
Initial SentimentINTEGER 1–5Sentiment at the start of the conversation (tickets and chats), to compare with the final Sentiment.
User RatingINTEGER 1–5The star rating the user gave, e.g. on an app store or Trustpilot review.
CSATINTEGER 1–5Satisfaction score the customer gave in a survey.
NPSINTEGER 0–10NPS the customer gave in a survey.

What the values mean:

ScaleValues
Sentiment, Initial Sentiment1 Critic · 2 Unhappy · 3 Passive · 4 Satisfied · 5 Enthusiast
CSAT1 Bad · 2 Dissatisfied · 3 Neutral · 4 Satisfied · 5 Good
NPS0–6 Detractor · 7–8 Passive · 9–10 Promoter

Score fields are empty when they do not apply — CSAT and NPS, for instance, are only filled for survey answers. If you would rather have readable labels, we can add a label column next to any score.

Setting up delivery ​

There are two ways to receive the files. Choose one. Either way, access uses short-lived AWS credentials and nothing is ever public.

You read from our bucketWe write to your bucket
Who owns the bucketZefiYou
What you send usYour AWS account IDA role ARN, bucket, region and prefix
Retention365 days, managed by usYours to set
Effort on your sideGrant read access to your usersCreate a role and a lifecycle rule

Option A: you read from our bucket ​

We create a dedicated bucket for your workspace and give your AWS account read access to it through its bucket policy.

What we need from you: your 12-digit AWS account ID.

The bucket policy grants your account:

PermissionOn
s3:ListBucket, s3:ListBucketVersionsThe bucket, limited to zefi_export/*
s3:GetObject, s3:GetObjectVersionThe objects in the bucket

On our side the bucket has public access blocked, requires HTTPS, and has versioning and access logging on. Files are kept for 365 days.

On your side: the policy trusts your whole account, so you choose which of your IAM users or roles get access. Give them s3:ListBucket and s3:GetObject on the bucket and its objects — we send you the bucket name when it is ready:

text
arn:aws:s3:::<bucket-name>
arn:aws:s3:::<bucket-name>/*

Option B: we write to your bucket ​

The files go to a bucket in your own AWS account, so storage, retention and cost stay under your control. We reach it by assuming a role you create, and that role trusts exactly one role of ours.

  1. We send you the ARN of our role. It is created for your workspace.

  2. You create an IAM role in your account whose trust policy allows our role to assume it:

    json
    {
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Principal": { "AWS": "<zefi-role-arn>" },
        "Action": "sts:AssumeRole"
      }]
    }

    Give it a permissions policy limited to the export prefix:

    Permission
    s3:PutObjectRequired
    s3:GetObjectRequired — used to check the file after upload
    s3:ListBucket, s3:GetBucketLocationRecommended
    s3:DeleteObjectNot needed — Zefi never deletes your files

    If the bucket uses SSE-KMS, also add the role to the key policy with kms:GenerateDataKey and kms:Encrypt.

  3. Send us the role ARN, the bucket name, the bucket region and the prefix to write under.

  4. Add lifecycle rules to your bucket. Zefi cannot delete files, so retention is yours:

    • delete export files older than the number of days you want to keep
    • abort incomplete multipart uploads after 1 day

Changing an export ​

Adding fields, changing the schedule or moving to the other delivery option is a request to your Zefi contact, not something to configure yourself. New fields arrive as new columns at the end of the file, so existing loads keep working.

Zefi API v1