Skip to main content

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​

WindowLimit
Per minute10 requests
Per hour200 requests
Per day1000 requests

Request Body​

FieldTypeRequiredDescription
customerobjectYes*Customer information. Required unless customerId or the top-level phone is supplied. See Customer Object.
customerIdstringNoExisting Flowcall customer ID in this account. Takes precedence over customer lookup by phone or email.
phonestringNoAlternative to customer.phone; customer.phone takes precedence when both are supplied.
orderNamestringNoOrder name or order number associated with the ticket.
orderCustomerIdstringNoFlowcall customer ID for the order's owner in this account. Requires orderName; useful when the caller and order owner differ.
selectedLineItemTitlestringNoTitle of one selected item in the order. Sets the workflow's selected-item context. See Order and Line Item Selection.
subjectstringNoShort summary or title for the ticket.
querystringNoCustomer question or issue description. Provide subject or query for AI task selection, or explicitly select a task.
payloadobjectNoInitial workflow output values keyed by parameter, for example { "priority": "high" }. Send a JSON object, not a serialized JSON string.
payloadFormatstringNoAccepted for compatibility; the current manual-ticket path does not persist or apply this identifier.
sourcestringNoBuilt-in ticket source, or a manual-source label. See Manual Source Labels.
manualSourceLabelstringNoOptional configured label when source is manual, such as Store or POS.
currentTaskIdstringNoWorkflow task ID to route the ticket to. Takes precedence over taskName.
taskNamestringNoWorkflow task name to route the ticket to. It is looked up by name within the account.
objectiveValuesobjectNoValues for normal task objectives, keyed by objective parameter.
dataPointOverridesobjectNoRequest-scoped string values that replace referenced read-only data points for this task execution.
sharedStatePatchobjectNoWorkflow context merged before evaluation, including media URLs or multiple selected item titles. See Order and Line Item Selection.
ticketIdstringNoUpdates an existing ticket in this account when objectiveValues or dataPointOverrides is also supplied. See Update an Existing Ticket.
mediumstringNoConversation channel: whatsapp, gmail, chat-widget, instagram, or voiceCall. The channel mapped from source takes precedence.
waitForTicketbooleanNoDefaults 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.
forceCreateTicketbooleanNoDefaults to false: eligible tickets for the same customer, task, and order may be reused. Send true to bypass implicit reuse when creating a ticket.
fastResponsebooleanNoDefaults to false. Send true to skip AI inference during creation. Task objectives and data points are still evaluated before returning.
skipExecuteActionbooleanNoDefaults to true for all manual creates and updates, including downstream task transitions. Send false explicitly to run configured execution actions.
imagesstring[]NoImage URLs related to the ticket.
initialNoteobjectNoNote saved on the created or reused ticket. See Initial Note.
isTestbooleanNoDefaults to false. Marks the ticket as a test ticket; test tickets skip normal SLA and distribution side effects.
markTaskCompletedOnHumanAgentHandoffbooleanNoDefaults to false. Excludes human-agent objectives from the task-completion check while preserving the handoff evaluation.
queueIncompleteTicketbooleanNoDefaults 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​

FieldTypeRequiredDescription
namestringNoCustomer full name.
phonestringYes*Customer phone number.
emailstringYes*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:

FieldTypeDescription
textstringNote text. Leading and trailing whitespace is removed.
imagesobject[]Attachments. Each requires a non-empty filePath; fileName, publicUrl, and contentType are optional strings.
createdByUserstringOptional author label; defaults to the authenticated user.
shareWithUserbooleanDefaults 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​

StatusBodyCause
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.
429Rate limit errorRate 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​

FieldTypeRequiredDescription
ticketIdstringYes*Flowcall ID of the parent ticket. Takes precedence when both fields are supplied.
ticketNumbernumber or stringYes*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 stale through 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​

StatusBodyCause
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​

FieldTypeDefaultDescription
pagenumber1Page number for pagination.
limitnumber10Number of results per page. Maximum 250.
sortOrder"asc" or "desc""desc"Sort direction based on the timestamp column selected by timestampKey.
timestampKeystringcreatedAtColumn to sort and filter by date. Accepted values are createdAt, updatedAt, resolvedAt, executedAt, and assignedAt.

Date Filters​

FieldTypeDescription
startDatestringISO 8601 date string. Filters tickets on or after this date based on timestampKey.
endDatestringISO 8601 date string. Filters tickets on or before this date based on timestampKey.
ignoreDateRangebooleanIf true, skips date range filtering. Only allowed when filtering by assigned or queued statuses.

Status And Assignment Filters​

FieldTypeDescription
statusesstring[]Filter by ticket statuses, for example ["open", "assigned", "resolved"].
excludeInProgressbooleanExclude tickets with in_progress status.
agentIdstringFilter by assigned agent ID.
involvedAgentIdstringFilter tickets where this agent was involved.
agentInvolvement"only_ai" or "agents_involved"Filter by whether human agents were involved.
unassignedbooleanFilter for unassigned tickets only.
createdByUserIdstringFilter 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​

FieldTypeDescription
taskIdsstring[]Filter by specific task IDs.
noTaskIdsbooleanFilter for tickets with no associated task.
taskTeamIdsstring[]Filter by task team IDs.

Search And Lookup Filters​

FieldTypeDescription
searchstringSearch 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.
phoneNumberstringFilter by customer phone number. Supports comma-separated values.
orderNamestringFilter by order name. Supports comma-separated values.
ticketNumberstringFilter 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.
sourcestringFilter by ticket source.
manualSourceLabelstringFilter manual tickets by their exact manual-source label. When provided without source, source: "manual" is implied.

Classification And Other Filters​

FieldTypeDescription
categorystringFilter by disposition category.
subcategorystringFilter by disposition subcategory.
sentimentsstring[]Filter by customer sentiments. Matches any value in the array.
excludeChildTicketsbooleanExclude child tickets.
parentTicketIdstringFilter 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​

StatusMessage
400Limit cannot be greater than 250
400Invalid date range or status combination
500Internal 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:

FieldTypeDefaultDescription
timezonestringBusiness timezone, then Asia/KolkataIANA timezone name, for example Asia/Kolkata or America/New_York.
localestringen-USUnicode locale identifier used to format local timestamp strings, for example en-IN.
timestampFormatstringdisplayTimestamp 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:

GroupColumns
TicketTicket Number, Ticket Type, Child Ticket Param, Task Names, Team, Actions, Status, Source, Sentiments, Order Name, Summary, Resolution
AssignmentAssigned To, Assigned By, Assigned At, Involved Sources, Involved Agents, Has Involved Agent, Resolved By
CustomerCustomer Name, Customer Phone, Customer Email, Customer ID, Chat Link
TimingCreated 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 workChild 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
SLAOne SLA: <label> column for every SLA configuration. Duplicate labels receive a numeric suffix.
Task objectivesOne Objective: <param> column for every objective parameter configured on the tasks included in the filtered result.
Other payload dataAdditional Data, containing a JSON object of payload keys that are not task objectives, main display fields, summary, or emailClient.
Main display fieldsOne 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.
CSATCSAT Status, CSAT Rating, CSAT Comment, CSAT Sent At, CSAT Submitted At
DispositionCategory, 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 valueCalculation
YesThe 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.
NoThe 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.
BlankThe 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 valueMeaning
YesTranscript analysis confirmed resolved_on_call, the root family passed its final protection checks, and the family was resolved.
NoThe 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.
UnknownThe root has an incoming call but no stored decision, including legacy tickets that were not backfilled.
BlankThe 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​

StatusMessage
400Invalid startDate or endDate
400endDate must be after startDate
400Export is limited to a maximum date range of 92 days
400Invalid export locale or timezone
404Ticket export job not found
429Rate limit exceeded. The ticket list and export endpoints allow 200 requests per hour per access token.
500Failed to enqueue or fetch the ticket export