Theme
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.
| Format | Parquet, one row per record |
| Delivery | An S3 bucket — yours, or one we host for you |
| Mode | Incremental: new and changed records only |
| Schedule | Daily 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>.parquetThe 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
| Field | Type | What it holds |
|---|---|---|
| Source ID | STRING | The record's ID in the original system, e.g. the Zendesk ticket ID. The key to de-duplicate on. |
| Source URL | STRING | Link to the record in the original system, when there is one. |
| Content | STRING | The feedback text. If translation is enabled for your workspace, this is the English translation. |
When and where
| Field | Type | What it holds |
|---|---|---|
| Created | TIMESTAMP | When the record was created in the original system. |
| Updated | TIMESTAMP | When the record was last updated in the original system. |
| Source | STRING | Where the feedback comes from: zendesk, appstore, playstore, trustpilot, typeform, zefi (Zefi surveys), … |
| Interaction Types | STRING[] | review, chat, ticket, message, comment, survey, interview, email, note, meeting, call, page |
| Survey Campaigns | STRING | The survey campaign the answer belongs to. Survey records only. |
| Original Language | STRING | Language detected in the original text, e.g. ita, spa, eng. |
Who
| Field | Type | What it holds |
|---|---|---|
| Customers | STRING | The customer or company the feedback is from. |
| Agents | STRING | The agent or account manager who handled the record, e.g. the Zendesk assignee. |
| Segments | STRING[] | The segments configured in Zefi that the record belongs to. |
What it is about
Assigned by Zefi's classification.
| Field | Type | What it holds |
|---|---|---|
| Topics | STRING[] | Main topics from your Zefi taxonomy found in the feedback. |
| Subtopics | STRING[] | The more detailed subtopics under those topics. |
| Signal Groups | STRING[] | The third taxonomy level, below subtopic. Only filled for workspaces on a three-level taxonomy. |
| Categories | STRING[] | Type of feedback: issue, request, doubt, praise, distrust, churn. |
| Urgency | STRING | none, low, medium, high, critical |
Scores
| Field | Type | What it holds |
|---|---|---|
| Sentiment | INTEGER 1–5 | Sentiment inferred from the text. Not a score the customer gave. |
| Initial Sentiment | INTEGER 1–5 | Sentiment at the start of the conversation (tickets and chats), to compare with the final Sentiment. |
| User Rating | INTEGER 1–5 | The star rating the user gave, e.g. on an app store or Trustpilot review. |
| CSAT | INTEGER 1–5 | Satisfaction score the customer gave in a survey. |
| NPS | INTEGER 0–10 | NPS the customer gave in a survey. |
What the values mean:
| Scale | Values |
|---|---|
| Sentiment, Initial Sentiment | 1 Critic · 2 Unhappy · 3 Passive · 4 Satisfied · 5 Enthusiast |
| CSAT | 1 Bad · 2 Dissatisfied · 3 Neutral · 4 Satisfied · 5 Good |
| NPS | 0–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 bucket | We write to your bucket | |
|---|---|---|
| Who owns the bucket | Zefi | You |
| What you send us | Your AWS account ID | A role ARN, bucket, region and prefix |
| Retention | 365 days, managed by us | Yours to set |
| Effort on your side | Grant read access to your users | Create 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:
| Permission | On |
|---|---|
s3:ListBucket, s3:ListBucketVersions | The bucket, limited to zefi_export/* |
s3:GetObject, s3:GetObjectVersion | The 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.
We send you the ARN of our role. It is created for your workspace.
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:GenerateDataKeyandkms:Encrypt.Send us the role ARN, the bucket name, the bucket region and the prefix to write under.
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.
