Ticket APIs
Use the ticket APIs to create support tickets from external systems, mark parent tickets stale, and retrieve or export tickets for reporting, reconciliation, or operational workflows.
Authentication
Create an access token from Settings -> Integrations in the Flowcall dashboard.
Pass the token as a Bearer token in every request:
Authorization: Bearer <your_access_token>
Create a Manual Ticket
Creates a new support ticket with customer details and the customer's query.
POST https://api.flowcall.co/apis/tickets/manual
Rate Limits
| Window | Limit |
|---|---|
| Per minute | 10 requests |
| Per hour | 200 requests |
| Per day | 1000 requests |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
customer | object | Yes* | Customer information. Required unless customerId or the top-level phone is supplied. See Customer Object. |
customerId | string | No | Existing Flowcall customer ID in this account. Takes precedence over customer lookup by phone or email. |
phone | string | No | Alternative to customer.phone; customer.phone takes precedence when both are supplied. |
orderName | string | No | Order name or order number associated with the ticket. |
orderCustomerId | string | No | Flowcall customer ID for the order's owner in this account. Requires orderName; useful when the caller and order owner differ. |
selectedLineItemTitle | string | No | Title of one selected item in the order. Sets the workflow's selected-item context. See Order and Line Item Selection. |
subject | string | No | Short summary or title for the ticket. |
query | string | No | Customer question or issue description. Provide subject or query for AI task selection, or explicitly select a task. |
payload | object | No | Initial workflow output values keyed by parameter, for example { "priority": "high" }. Send a JSON object, not a serialized JSON string. |
payloadFormat | string | No | Accepted for compatibility; the current manual-ticket path does not persist or apply this identifier. |
source | string | No | Built-in ticket source, or a manual-source label. See Manual Source Labels. |
manualSourceLabel | string | No | Optional configured label when source is manual, such as Store or POS. |
currentTaskId | string | No | Workflow task ID to route the ticket to. Takes precedence over taskName. |
taskName | string | No | Workflow task name to route the ticket to. It is looked up by name within the account. |
objectiveValues | object | No | Values for normal task objectives, keyed by objective parameter. |
dataPointOverrides | object | No | Request-scoped string values that replace referenced read-only data points for this task execution. |
sharedStatePatch | object | No | Workflow context merged before evaluation, including media URLs or multiple selected item titles. See Order and Line Item Selection. |
ticketId | string | No | Updates an existing ticket in this account when objectiveValues or dataPointOverrides is also supplied. See Update an Existing Ticket. |
medium | string | No | Conversation channel: whatsapp, gmail, chat-widget, instagram, or voiceCall. The channel mapped from source takes precedence. |
waitForTicket | boolean | No | Defaults to true. Send false to only find or create the customer, provided fastResponse is false, there is no non-empty initialNote, and no ticketId is supplied. |
forceCreateTicket | boolean | No | Defaults to false: eligible tickets for the same customer, task, and order may be reused. Send true to bypass implicit reuse when creating a ticket. |
fastResponse | boolean | No | Defaults to false. Send true to skip AI inference during creation. Task objectives and data points are still evaluated before returning. |
skipExecuteAction | boolean | No | Defaults to true for all manual creates and updates, including downstream task transitions. Send false explicitly to run configured execution actions. |
images | string[] | No | Image URLs related to the ticket. |
initialNote | object | No | Note saved on the created or reused ticket. See Initial Note. |
isTest | boolean | No | Defaults to false. Marks the ticket as a test ticket; test tickets skip normal SLA and distribution side effects. |
markTaskCompletedOnHumanAgentHandoff | boolean | No | Defaults to false. Excludes human-agent objectives from the task-completion check while preserving the handoff evaluation. |
queueIncompleteTicket | boolean | No | Defaults to false. Send true to allow queueing while required customer inputs or an active human-agent handoff would otherwise keep the ticket in progress. |
For creation, identify the customer with customerId, customer.phone,
customer.email, or top-level phone. When selecting a task explicitly, use
currentTaskId or an exact taskName; currentTaskId takes precedence. A selected
task allows a structured request with objectiveValues and no subject or query.
With fastResponse: true, select the task explicitly because AI task selection is skipped.
relatedTicketNumber and customer.shopifyCustomerId appeared in earlier versions
of this documentation, but the current handler does not use them to link a ticket
or set the Shopify customer ID.
Customer Object
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Customer full name. |
phone | string | Yes* | Customer phone number. |
email | string | Yes* | Customer email address. |
*Either phone or email is required when neither customerId nor top-level
phone is supplied. Phone numbers are normalized with country code 91 as the
fallback; send the full country code for customers elsewhere.
Order and Line Item Selection
Send orderName to load the order into the workflow context. For a single item,
send its title exactly as it appears in the order's lineItems[].title:
{
"orderName": "#1042",
"selectedLineItemTitle": "Cotton T-Shirt - Blue / M"
}
selectedLineItemTitle sets sharedState.selectedFulfillmentItemNames to a
one-element array. Workflows use that context to resolve the built-in
selectedLineItemTitle (first title) and selectedLineItemsTitle (comma-separated
titles) data points. This field takes a title, not a line item ID or SKU.
For multiple items, send the array through sharedStatePatch:
{
"orderName": "#1042",
"sharedStatePatch": {
"selectedFulfillmentItemNames": [
"Cotton T-Shirt - Blue / M",
"Cotton T-Shirt - Black / L"
]
}
}
The explicit patch is applied after orderName and selectedLineItemTitle, so
sharedStatePatch.selectedFulfillmentItemNames takes precedence if both forms
are supplied. There is no top-level selectedLineItemsTitle,
selectedLineItemTitles, or selectedLineItemsTitles parameter on this endpoint.
If the selected task defines a normal item-selection objective, its value can
also be supplied by its exact parameter name in objectiveValues; that does
not add a top-level request field.
Use orderCustomerId when the order belongs to another Flowcall customer. It must
identify a customer in the same account and be accompanied by orderName.
Initial Note
initialNote supports these fields:
| Field | Type | Description |
|---|---|---|
text | string | Note text. Leading and trailing whitespace is removed. |
images | object[] | Attachments. Each requires a non-empty filePath; fileName, publicUrl, and contentType are optional strings. |
createdByUser | string | Optional author label; defaults to the authenticated user. |
shareWithUser | boolean | Defaults to false. Send true to attempt customer delivery through the ticket's source channel. Shared notes require text. |
A note is saved only when it contains text or a valid attachment. A non-empty
note causes ticket creation even if waitForTicket is false, and is returned
as initialNote. For example:
{
"initialNote": {
"text": "Customer requested a return during the call.",
"shareWithUser": false,
"images": [
{
"filePath": "ticket-attachments/size-label.jpg",
"fileName": "size-label.jpg",
"publicUrl": "https://cdn.example.com/images/size-label.jpg",
"contentType": "image/jpeg"
}
]
}
}
Update an Existing Ticket
Send ticketId together with objectiveValues or dataPointOverrides to
evaluate and update that ticket. Its customer and current task are used unless
a new task is selected with currentTaskId or taskName. The ticket must
belong to the authenticated account. This update path does not save initialNote
and does not apply the creation-only fastResponse shortcut.
{
"ticketId": "64f7b2c1c9d2a4e7b1f3a9d0",
"orderName": "#1042",
"selectedLineItemTitle": "Cotton T-Shirt - Blue / M",
"objectiveValues": {
"returnReason": "Wrong size"
},
"skipExecuteAction": true
}
Always include one of the value objects when sending ticketId; without it,
the handler takes the creation path rather than updating that ticket.
Manual Source Labels
The built-in source values are whatsapp, email, liveChat, instagram,
voiceCall, and manual.
Accounts can configure additional labels for manually created tickets, such as
Store or POS, in Settings → Ticket Lifecycle → Ticket basics → Manual Ticket Sources. You can
send one of these labels directly in source:
{
"source": "POS"
}
Flowcall stores this as:
{
"source": "manual",
"manualSourceLabel": "POS"
}
Configured labels are matched case-insensitively and stored using their
configured casing. Any non-empty source value that is not a built-in source is
also normalized to source: "manual" and retained in manualSourceLabel, even
when it has not been configured yet.
Alternatively, send the fields explicitly:
{
"source": "manual",
"manualSourceLabel": "Store"
}
Data Point Overrides
Use dataPointOverrides when a manually created ticket must evaluate a task
with an explicit value instead of reading that value from its normal data
source. Overrides apply only to this request; they do not update the customer,
order, Google Sheet, or custom integration that normally supplies the data.
A task must be selected with taskName (or currentTaskId). Each override key
must be a data point directly referenced by that task, and values must be
non-empty strings. Keys are matched case-insensitively to the task's canonical
data point names. A request can contain at most 50 overrides.
The API rejects an override when:
- the data point is unknown or is not directly used by the selected task;
- it represents a computed or execute-action objective;
- it writes to a Google Sheet;
- its value is outside the data point's configured
possibleValues; or - the same key (matched case-insensitively) is also present in
objectiveValues.
The overridden value is used by dependent objectives and task transitions. To
reduce unintended side effects, execution actions are skipped by default for
all manual creates and updates. Set skipExecuteAction to false explicitly
only when those actions should run with the overridden inputs.
For example:
{
"taskName": "Return order",
"objectiveValues": {
"returnReason": "Wrong size"
},
"dataPointOverrides": {
"orderStatus": "delivered"
},
"fastResponse": true
}
Example Request
curl -X POST https://api.flowcall.co/apis/tickets/manual \
-H "Authorization: Bearer <your_access_token>" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"name": "John Doe",
"phone": "911234567890",
"email": "john@example.com"
},
"orderName": "#1042",
"selectedLineItemTitle": "Cotton T-Shirt - Blue / M",
"subject": "Return request - wrong size",
"query": "I want to return my order, the size does not fit.",
"taskName": "Return order",
"objectiveValues": {
"returnReason": "Wrong size"
},
"dataPointOverrides": {
"orderStatus": "delivered"
},
"payload": { "priority": "high" },
"source": "voiceCall",
"fastResponse": true,
"skipExecuteAction": true,
"initialNote": {
"text": "Return requested during the call.",
"shareWithUser": false
},
"images": [
"https://cdn.example.com/images/damaged-item-1.jpg",
"https://cdn.example.com/images/damaged-item-2.jpg"
]
}'
Success Response
{
"success": true,
"customer": {
"id": "cust_abc123",
"name": "John Doe",
"phone": "+1234567890",
"email": "john@example.com"
},
"ticketId": "64f7b2c1c9d2a4e7b1f3a9d0",
"existingTicket": false,
"ticket": { "id": "64f7b2c1c9d2a4e7b1f3a9d0", "...": "..." }
}
existingTicket is true when an eligible ticket was reused. The result also
includes workflow evaluation fields such as output, nextObjectives,
resolved, and, when applicable, childTicketId and resolution.
When waitForTicket is false, fastResponse is false, no non-empty initialNote
is supplied, and no ticketId is supplied, only the customer is found or created.
The response includes requestId instead of ticketId:
{
"success": true,
"customer": {
"id": "cust_abc123",
"name": "John Doe",
"phone": "+1234567890",
"email": "john@example.com"
},
"requestId": "64f7b2c1c9d2a4e7b1f3a9d0"
}
Error Responses
| Status | Body | Cause |
|---|---|---|
400 | { "error": "phone or email is required" } | No customerId, customer.phone, customer.email, or top-level phone supplied. |
400 | { "error": "Data point ..." } | Invalid or unsafe dataPointOverrides input. |
400 | { "error": "Order and order customer are required" } | Invalid orderCustomerId or missing orderName. |
400 | { "error": "Order customer not found in this account" } | orderCustomerId is outside this account or does not exist. |
400 | { "error": "Selected task was not found in this ticket's account" } | Invalid task selected for an existing-ticket update. |
403 | { "error": "Not authorized" } | Invalid or missing Bearer token. |
403 | { "error": "This task is not available to your team for manual ticket creation" } | Selected task is unavailable to the authenticated user's team. |
404 | { "error": "Ticket not found" } | Update target was not found in this account. |
409 | { "error": "...", "code": "..." } | Business configuration or the ticket numbering counter prevents allocation. |
429 | Rate limit error | Rate limit exceeded. |
500 | { "success": false, "error": "Ticket initial note could not be saved", "ticketId": "..." } | Ticket creation may have succeeded, but its initial note could not be saved. |
Mark a Ticket as Stale
Marks a parent ticket as stale when its work is no longer relevant. This uses the same action as Mark stale / spam in the dashboard. Child and interaction tickets cannot be marked stale directly through this endpoint.
POST https://api.flowcall.co/apis/task-runs/tickets/mark-stale
Use the Bearer token described under Authentication. Dashboard users need the Mark stale / spam action permission; integration access tokens can perform this action in their account.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
ticketId | string | Yes* | Flowcall ID of the parent ticket. Takes precedence when both fields are supplied. |
ticketNumber | number or string | Yes* | Account-scoped ticket number, such as 1234 or "1234", or the full parent ticket name, such as "FC-1234". |
*Supply either ticketId or ticketNumber. Numeric ticket numbers must be positive
integers up to 2147483647. String values are trimmed, may start with #, and
full ticket names are matched case-insensitively. Number and name lookups use only
the authenticated account and select parent tickets, even when a child shares
the parent's number. Child and interaction suffixes such as _c1 and _i1 are
not accepted.
Example Request
curl -X POST 'https://api.flowcall.co/apis/task-runs/tickets/mark-stale' \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{"ticketNumber": 1234}'
To use the ticket ID instead, send:
{
"ticketId": "64f7b2c1c9d2a4e7b1f3a9d0"
}
Behavior
- Sets the parent to
stale, records the resolution time and actor, and clears assignment, awaiting-response, follow-up, and snooze state. - Completes the assigned agent's activity, ends the parent's SLA timer, and records a status-change log.
- Marks eligible unresolved child tickets
stalethrough the existing family cleanup, completing their activities and ending their SLA timers. Children already resolved or closed retain their terminal state. - Closes open interaction tickets and refreshes the ticket sidebar. Where the parent has a customer and source, records that AI is enabled for that channel.
Success Response
{
"success": true,
"message": "Ticket marked as stale"
}
Error Responses
| Status | Body | Cause |
|---|---|---|
400 | { "error": "Ticket ID or ticket number is required" } | Neither identifier supplied. |
400 | { "error": "Ticket ID is required" } | An empty or invalid ticketId was supplied. |
400 | { "error": "Invalid ticket number" } | Invalid number, name, or child/interaction suffix. |
400 | { "error": "Only parent tickets can be marked as stale" } | ticketId identifies a child or interaction ticket. |
403 | { "error": "Your role does not allow this action", "action": "ticket.mark_stale" } | The user lacks the action permission in the ticket's account. |
404 | { "error": "Ticket not found" } | No matching ticket exists in the permitted account scope. |
500 | { "error": "Failed to mark ticket as stale" } | The stale action could not be completed. |
List Tickets
Retrieves a paginated list of tickets with filtering, sorting, and search.
POST https://api.flowcall.co/apis/task-runs/tickets/list
Request Body
All fields are optional unless noted otherwise.
Pagination And Sorting
| Field | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number for pagination. |
limit | number | 10 | Number of results per page. Maximum 250. |
sortOrder | "asc" or "desc" | "desc" | Sort direction based on the timestamp column selected by timestampKey. |
timestampKey | string | createdAt | Column to sort and filter by date. Accepted values are createdAt, updatedAt, resolvedAt, executedAt, and assignedAt. |
Date Filters
| Field | Type | Description |
|---|---|---|
startDate | string | ISO 8601 date string. Filters tickets on or after this date based on timestampKey. |
endDate | string | ISO 8601 date string. Filters tickets on or before this date based on timestampKey. |
ignoreDateRange | boolean | If true, skips date range filtering. Only allowed when filtering by assigned or queued statuses. |
Status And Assignment Filters
| Field | Type | Description |
|---|---|---|
statuses | string[] | Filter by ticket statuses, for example ["open", "assigned", "resolved"]. |
excludeInProgress | boolean | Exclude tickets with in_progress status. |
agentId | string | Filter by assigned agent ID. |
involvedAgentId | string | Filter tickets where this agent was involved. |
agentInvolvement | "only_ai" or "agents_involved" | Filter by whether human agents were involved. |
unassigned | boolean | Filter for unassigned tickets only. |
createdByUserId | string | Filter by the user who created the ticket. |
orderResolutionTriggers | ("webhook" or "manual")[] | Root tickets currently resolved by order re-evaluation. Manual includes single and bulk refresh; values combine with OR. |
The trigger belongs to the current resolution event. A previous re-evaluation does
not qualify an open or reopened ticket, or a ticket later resolved another way.
Historical webhook closures are supported; older manual closures recorded only under
a human actor may lack enough information to classify.
The CSV includes Resolution Trigger beside Resolved By: Webhook order re-evaluation, Manual order re-evaluation, or blank when no trigger is known.
Task And Team Filters
| Field | Type | Description |
|---|---|---|
taskIds | string[] | Filter by specific task IDs. |
noTaskIds | boolean | Filter for tickets with no associated task. |
taskTeamIds | string[] | Filter by task team IDs. |
Search And Lookup Filters
| Field | Type | Description |
|---|---|---|
search | string | Search ticket summary, order name, ticket name (a number finds the ticket named with it), customer name, email, and phone. Needs at least 3 letters or numbers; a shorter search is ignored. |
phoneNumber | string | Filter by customer phone number. Supports comma-separated values. |
orderName | string | Filter by order name. Supports comma-separated values. |
ticketNumber | string | Filter by ticket name. Case, spaces, separators and a leading # are ignored, so fc 1234 finds FC-1234, and a number finds the ticket named with it (1234 finds FC-1234). Tickets created before April 2026 that have no name are not found by number. Supports comma-separated values. |
source | string | Filter by ticket source. |
manualSourceLabel | string | Filter manual tickets by their exact manual-source label. When provided without source, source: "manual" is implied. |
Classification And Other Filters
| Field | Type | Description |
|---|---|---|
category | string | Filter by disposition category. |
subcategory | string | Filter by disposition subcategory. |
sentiments | string[] | Filter by customer sentiments. Matches any value in the array. |
excludeChildTickets | boolean | Exclude child tickets. |
parentTicketId | string | Filter child tickets belonging to this parent ticket ID. |
Example Request
curl -X POST https://api.flowcall.co/apis/task-runs/tickets/list \
-H "Authorization: Bearer <your_access_token>" \
-H "Content-Type: application/json" \
-d '{
"page": 1,
"limit": 20,
"startDate": "2026-03-01T00:00:00.000Z",
"endDate": "2026-03-18T23:59:59.999Z",
"statuses": ["open", "assigned"],
"sortOrder": "desc"
}'
Success Response
{
"data": [
{
"id": "ticket-id",
"ticketNumber": 1234,
"status": "assigned",
"summary": "Customer inquiry about order",
"orderName": "#1001",
"source": "whatsapp",
"manualSourceLabel": null,
"customerId": "customer-id",
"assignedToId": "agent-id",
"taskId": "task-id",
"createdAt": "2026-03-15T10:00:00.000Z",
"resolvedAt": null,
"csat": {
"rating": 5,
"comment": "Great support!"
}
}
],
"total": 150,
"page": 1,
"limit": 20,
"totalPages": 8
}
Error Responses
| Status | Message |
|---|---|
400 | Limit cannot be greater than 250 |
400 | Invalid date range or status combination |
500 | Internal server error |
Export Tickets as CSV
Ticket CSV exports run asynchronously. Starting an export returns a job ID immediately; use that ID to check progress and retrieve a short-lived download URL when the CSV is ready.
Start an Export
POST https://api.flowcall.co/apis/task-runs/tickets/export
Request Body
The export endpoint accepts the same filters and sorting fields as
List Tickets. Pagination fields such as page and limit are
not required because every matching ticket is exported.
The following optional fields control how timestamps are displayed in the CSV:
| Field | Type | Default | Description |
|---|---|---|---|
timezone | string | Business timezone, then Asia/Kolkata | IANA timezone name, for example Asia/Kolkata or America/New_York. |
locale | string | en-US | Unicode locale identifier used to format local timestamp strings, for example en-IN. |
timestampFormat | string | display | Timestamp format: display (DD-MM-YY HH:MM:SS), legacy (locale-sensitive), or iso (ISO 8601 with offset). |
When both startDate and endDate are provided, the export date range cannot
exceed 92 days. Dates are filtered using timestampKey, in the same way as the
list endpoint.
Example Request
curl -X POST https://api.flowcall.co/apis/task-runs/tickets/export \
-H "Authorization: Bearer <your_access_token>" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2026-03-01T00:00:00.000Z",
"endDate": "2026-03-18T23:59:59.999Z",
"timestampKey": "createdAt",
"statuses": ["open", "assigned", "resolved"],
"sortOrder": "desc",
"timezone": "Asia/Kolkata",
"locale": "en-IN"
}'
Success Response
The endpoint returns HTTP 202 Accepted after the job has been queued:
{
"success": true,
"jobId": "8ce98fc2-8a5a-4ab1-b42c-00c09a0526a7",
"status": "queued",
"total": 1499,
"fileName": "tickets-2026-03-01_to_2026-03-18.csv",
"statusUrl": "/apis/task-runs/tickets/export/8ce98fc2-8a5a-4ab1-b42c-00c09a0526a7"
}
Check Export Status and Download
Poll the returned statusUrl using the same Bearer token:
GET https://api.flowcall.co/apis/task-runs/tickets/export/{jobId}
curl https://api.flowcall.co/apis/task-runs/tickets/export/8ce98fc2-8a5a-4ab1-b42c-00c09a0526a7 \
-H "Authorization: Bearer <your_access_token>"
The job status is one of queued, running, succeeded, or failed. While
the export is being generated, the response contains progress information:
{
"success": true,
"job": {
"jobId": "8ce98fc2-8a5a-4ab1-b42c-00c09a0526a7",
"status": "running",
"total": 1499,
"processed": 800,
"fileName": "tickets-2026-03-01_to_2026-03-18.csv",
"createdAt": "2026-03-19T05:30:00.000Z",
"startedAt": "2026-03-19T05:30:02.000Z",
"updatedAt": "2026-03-19T05:30:08.000Z"
}
}
When job.status is succeeded, the response includes the download URL:
{
"success": true,
"job": {
"jobId": "8ce98fc2-8a5a-4ab1-b42c-00c09a0526a7",
"status": "succeeded",
"total": 1499,
"processed": 1499,
"fileName": "tickets-2026-03-01_to_2026-03-18.csv",
"fileSizeBytes": 3223018,
"createdAt": "2026-03-19T05:30:00.000Z",
"startedAt": "2026-03-19T05:30:02.000Z",
"completedAt": "2026-03-19T05:30:14.000Z",
"availableUntil": "2026-03-20T05:30:14.000Z",
"updatedAt": "2026-03-19T05:30:14.000Z"
},
"downloadUrl": "https://storage.googleapis.com/...",
"expiresAt": "2026-03-19T05:45:15.000Z",
"downloadExpired": false
}
Download the CSV directly from downloadUrl. The generated file is retained
for 24 hours. Each signed URL is valid for 15 minutes; call the status endpoint
again to obtain a fresh URL while the file is still retained. When the job is
failed, the job.error field contains a safe error message.
If no timezone is supplied when starting the export, the API uses the account's
business timezone. If that is missing or invalid, it uses Asia/Kolkata.
CSV Columns
The export contains the same operational values used by the Tickets dashboard, organized into these column groups:
| Group | Columns |
|---|---|
| Ticket | Ticket Number, Ticket Type, Child Ticket Param, Task Names, Team, Actions, Status, Source, Sentiments, Order Name, Summary, Resolution |
| Assignment | Assigned To, Assigned By, Assigned At, Involved Sources, Involved Agents, Has Involved Agent, Resolved By |
| Customer | Customer Name, Customer Phone, Customer Email, Customer ID, Chat Link |
| Timing | Created At, Queued Time, First Response Timestamp, Response Time, First Response Time (minutes), Total Response Time (minutes), Latest Response Time, Age, Resolution Time, Last Updated At, Executed At, Resolved At |
| Related work | Child Tickets, Interaction Tickets, Chat Interactions, Email Threads, Customer Email Messages, Agent Email Messages, Incoming Calls, Outgoing Calls, Voice Calls, FCR, Voice FCR, Voice FCR Reason, Voice FCR Evaluated At, Email ThreadId, Email Client, Auto Resolved |
| SLA | One SLA: <label> column for every SLA configuration. Duplicate labels receive a numeric suffix. |
| Task objectives | One Objective: <param> column for every objective parameter configured on the tasks included in the filtered result. |
| Other payload data | Additional Data, containing a JSON object of payload keys that are not task objectives, main display fields, summary, or emailClient. |
| Main display fields | One column per field selected under Settings → Ticket Fields → Main display Fields, named by the field key (for example awb_number). A key that matches a built-in column name is exported as Main Display: <key>. The value comes from the ticket payload, then from disposition data. |
| CSAT | CSAT Status, CSAT Rating, CSAT Comment, CSAT Sent At, CSAT Submitted At |
| Disposition | Category, Subcategory, plus one Disposition: <label> column for every active disposition field, including category fields. |
Local ticket timestamp columns are formatted using the resolved locale and
timezone. CSAT Sent At and CSAT Submitted At remain ISO 8601 timestamps.
Response Time measures ticket creation to first response. Resolution Time
measures ticket creation to resolution; both use HH:MM durations. When
opening hours are configured for a ticket's account, both durations count
only configured opening hours and exclude closed days and configured holidays;
otherwise they use ordinary elapsed time. First Response Time (minutes) uses
the same business-hours-aware duration as Response Time.
For manual tickets, the CSV Source column contains manualSourceLabel when
present; otherwise it contains Manual.
Customer Email Messages counts distinct messages in the ticket family's linked
email threads that were sent by addresses outside the configured mailboxes.
Agent Email Messages counts distinct messages sent from configured mailbox owner
or alias addresses, excluding messages tagged as AI- or system-generated. These
family metrics are populated on parent ticket rows and left blank on child and
interaction-ticket rows.
Chat Interactions counts distinct chat sessions across the ticket family.
Voice Calls is the sum of Incoming Calls and Outgoing Calls.
Legacy FCR calculation
FCR means First Contact Resolution. It is calculated from the lifetime activity
of the complete ticket family and is populated only on the parent ticket row. Child
and interaction-ticket rows have a blank FCR value.
| Export value | Calculation |
|---|---|
Yes | The parent is in closed, stale, stale_marked_automatically, resolved_by_agent, or resolved_by_ai; the family has no more than one customer-contact channel; and every applicable channel rule passes. Voice requires exactly one incoming call. Email requires one or two customer emails and at most one human-agent email message. |
No | The family has a customer email or incoming-voice contact but the parent is not terminal, the voice or email rule fails, or the family has more than one customer-contact channel. A multi-channel family is No even when each individual channel rule passes. |
| Blank | The row is a child or interaction ticket, or the parent family has neither a customer email nor an incoming call. A family with only one unsupported FCR channel, such as chat, also remains blank. |
The email rule counts distinct messages sent from configured mailbox owner or alias
addresses. AI- and system-generated messages are excluded. Customer email establishes
email as a contact channel, and more than two customer emails makes FCR No.
Agent-originated email without a customer email does not add a second channel, so
an agent can send a confirmation email during a qualifying voice call without making
FCR No. The voice rule counts incoming calls only; outgoing calls do not affect FCR.
Channel count comes from the family's interaction sources, with email included only
when the family contains a customer-originated email and voice included only when it
contains an incoming call. manual is added as a synthetic channel when it appears as
the current or an involved source because manual tickets do not create interaction
rows.
Stored voice FCR
Voice FCR is the evidence-backed value persisted on the customer-facing root
ticket when an incoming call is evaluated. It is separate from the legacy FCR
calculation so existing exports and integrations retain their current meaning.
| Export value | Meaning |
|---|---|
Yes | Transcript analysis confirmed resolved_on_call, the root family passed its final protection checks, and the family was resolved. |
No | The call was evaluated as unresolved, follow-up was delegated, resolution occurred without usable evaluation evidence, or a later inbound customer contact was linked to the same family. |
Unknown | The root has an incoming call but no stored decision, including legacy tickets that were not backfilled. |
| Blank | The row is a child or interaction ticket, or the root has no incoming voice call. |
Voice FCR Reason contains the stored machine-readable reason and
Voice FCR Evaluated At contains the decision timestamp. A frontend child that is created
and immediately auto-closed with the root does not by itself disqualify FCR.
Protected or delegated child work does. Outbound calls and agent-only confirmation
emails do not invalidate the value; a later customer-originated message or a
different incoming call linked to the family does.
The set of task-objective, SLA, and disposition columns depends on the account
configuration and on the tasks included by the export filters. Unknown payload
keys do not create additional CSV columns; they are serialized into
Additional Data instead.
Child ticket rows use the parent ticket's collected data: objective, main
display field and Additional Data values missing on the child are taken from
the parent's payload, and disposition values always come from the parent.
Values set on the child itself take precedence.
Related-work counts are lifetime totals for the complete ticket family and are populated only on parent-ticket rows. Email thread counts include every email provider represented in the ticket interaction history.
Error Responses
| Status | Message |
|---|---|
400 | Invalid startDate or endDate |
400 | endDate must be after startDate |
400 | Export is limited to a maximum date range of 92 days |
400 | Invalid export locale or timezone |
404 | Ticket export job not found |
429 | Rate limit exceeded. The ticket list and export endpoints allow 200 requests per hour per access token. |
500 | Failed to enqueue or fetch the ticket export |