Skip to main content

Export tickets API

Prerequisites​

To use the APIs, you need to have a token. Tokens can be generated by an admin at the setting section in Filum CX platform. Ensure you have the necessary permissions to access the admin settings for token generation.

APIs​

Access the APIs via the endpoint: https://api.filum.ai/

POST /external/tickets/export​

Summary​

Export Tickets

Limitations:

  • Each export request can include up to 5000 rows of data.
  • Each date range you provide may cover at most 90 days. A longer range is rejected with 400 — it is no longer silently trimmed to the last 90 days, so a truncated file can never be mistaken for a complete one.

Date ranges​

The endpoint accepts three independent date windows, and each one filters a different timestamp:

ParametersFilters onUse it for
start_date / end_dateticket created time"all tickets opened in this period"
updated_start_date / updated_end_dateticket last updated timeincremental sync — "everything touched in this period"
closed_start_date / closed_end_dateticket last updated time, restricted to tickets currently closed"tickets closed in this period" (approximate — see note below)

Rules:

  • At least one of start_date, end_date, updated_start_date, updated_end_date must be provided. Without any of them the request fails with 400. A closed_* range on its own does not satisfy this requirement.
  • The windows are ANDed. Passing a created range and an updated range returns only the tickets matching both, not the union.
  • Each window is validated and capped at 90 days independently.
  • A window may be one-sided: updated_start_date with no updated_end_date means "from that date until now". The reverse — an end date with no start date — is rejected with 400, because it would reach back to your first ticket ever and silently truncate at 5000 rows.
  • closed_start_date and closed_end_date only take effect when both are given.
  • Both bounds are inclusive, and dates are read in the workspace timezone (UTC+7 by default): start_date begins at 00:00:00 of that day and end_date ends at 23:59:59 of that day.
Which window should a data warehouse sync use?

updated_start_date / updated_end_date. A ticket keeps changing long after the day it was created — an agent assigns it and fills in its custom fields the next morning — so a pull windowed on the created date alone freezes each ticket in whatever state it happened to be in when that day was last exported.

About closed_*

There is no dedicated "closed at" timestamp; this filter means "last updated inside the window AND currently closed". A ticket closed inside the window but edited again afterwards falls outside it.

Query Parameters​

NameDescriptionRequiredSchema
start_dateThe lower boundary of the created date rangeConditionaldate
end_dateThe upper boundary of the created date rangeConditionaldate
updated_start_dateThe lower boundary of the last updated date rangeConditionaldate
updated_end_dateThe upper boundary of the last updated date rangeConditionaldate
closed_start_dateThe lower boundary of the closed date range. Requires closed_end_dateNodate
closed_end_dateThe upper boundary of the closed date range. Requires closed_start_dateNodate
searchSearch term to filter tickets by subject, description, or customer information. Ignored when shorter than 3 charactersNostring
statusesFilter tickets by status key. The system statuses are new, open, pending, solved, closed, plus any custom status your workspace has defined. Deleted tickets are never exportedNo[ string ]
prioritiesFilter tickets by priority. Options are: low, medium, high, urgentNo[ string ]
survey_response_idsFilter tickets by survey response IDsNo[ integer ]
review_keysFilter tickets by review keysNo[ string ]
assignee_account_idsFilter tickets by assignee account IDsNo[ integer ]
creator_account_idsFilter tickets by creator account IDs. Use 0 to include tickets created by the system (no creator). When mixing 0 with other IDs, the result includes both system-created tickets and tickets created by the specified accounts.No[ integer ]
overdueFilter tickets that are overdue (past their due date and still open or pending)Noboolean
has_assigneetrue returns only assigned tickets, false only unassigned onesNoboolean
has_teamtrue returns only tickets that belong to a team, false only tickets without oneNoboolean
assigned_to_meFilter tickets assigned to the current userNoboolean
installed_source_idsFilter tickets by channel (installed source) IDsNo[ integer ]
custom_field_<id>Filter by a custom field value, where <id> is the custom field ID — e.g. custom_field_42=VIPNo[ string ]

Examples for list-type parameters:

# Filter tickets with status 'open' or 'pending'
statuses=open&statuses=pending

# Only tickets created by the system (creator_account_id IS NULL)
creator_account_ids=0

# Tickets created by the system OR by accounts 12 and 34
creator_account_ids=0&creator_account_ids=12&creator_account_ids=34

# Incremental sync: everything touched on 2026-10-22, whenever it was created
updated_start_date=2026-10-22&updated_end_date=2026-10-22

# Custom field 42 is 'VIP' or 'Gold'
custom_field_42=VIP&custom_field_42=Gold

Header Parameters​

NameDescriptionRequiredSchema
authorizationThe authorization token to validate the request. The value must be in the format Bearer <your_api_token>Yesstring
organization-idThe unique identifier of your organizationYesstring
auth-typeThe type of authorization used for the request. In this case, the value must be tokenYesstring
acceptThe format of the exported file. Options are: text/csv, application/x-ndjson, or */* (treated as text/csv)Yesstring

Responses​

CodeDescriptionContent type
200Successful Responsetext/csv; charset=utf-16le or application/x-ndjson; charset=utf-16le
400Bad Request (missing, inverted or too-wide date range)application/json
422Validation Errorapplication/json
429Too Many Requestsapplication/json

200 Successful Response​

File Format Details:

  • The output file will be provided in either CSV or NDJSON format
  • The file is encoded in UTF-16LE (Little Endian)
  • The CSV file starts with a UTF-16LE BOM (Byte Order Mark)
  • Fields in CSV format are tab-separated
  • Values containing special characters are enclosed in double quotes

In NDJSON format, each line of the response is one standalone ticket object whose keys are the column names listed below. Empty values are left out of the object.

The output file will provide the following information:

Default columns:

  • Ticket ID
  • Created at (in the workspace timezone, UTC+7 by default)
  • Updated at (in the workspace timezone, UTC+7 by default)
  • Customer Filum ID
  • Customer ID
  • Customer name
  • Customer phone
  • Customer email
  • Subject
  • Description
  • Status
  • Priority
  • Due Date
  • Assignee Name
  • Assignee Email
  • Creator Name
  • Creator Email
  • Team ID
  • Team
  • Channel ID (also exported as Installed Source ID, see Deprecated columns)
  • Channel Name (also exported as Installed Source Name, see Deprecated columns)
  • Channel Type
  • Source ID
  • Source Name
  • Ticket Link
  • Customer Link
  • SLA First Response Time
  • SLA Next Response Time
  • SLA Time to Closed
  • SLA Time to Resolved

Custom field columns (varies based on workspace setup):

  • Each custom field will have its own column with the field name as the column header

Each row in the table will represent a unique ticket. The columns will contain the following information:

  • Ticket ID: A unique identifier for the ticket
  • Created at: The timestamp when the ticket was created
  • Updated at: The timestamp when the ticket was last updated
  • Customer Filum ID: The Filum ID of the customer associated with the ticket
  • Customer ID: The ID of the customer in your own system, as opposed to the Filum ID above — this is what you join the exported rows back onto your own customer table. Taken from the ticket, falling back to the matched customer profile. Empty when the ticket has no customer, or when that customer has no ID in your system (e.g. a walk-in identified only by phone number)
  • Customer name: The name of the customer associated with the ticket
  • Customer phone: The phone number of the customer
  • Customer email: The email of the customer
  • Subject: The subject of the ticket
  • Description: The description of the ticket
  • Status: The current status of the ticket
  • Priority: The priority level of the ticket
  • Due Date: The due date of the ticket (if set)
  • Assignee Name: The name of the person assigned to the ticket
  • Assignee Email: The email of the person assigned to the ticket
  • Creator Name: The name of the user who created the ticket (empty when ticket has no creator, e.g. created via internal/system)
  • Creator Email: The email of the user who created the ticket (empty when ticket has no creator)
  • Team ID: The ID of the team the ticket is assigned to (empty when the ticket is not assigned to a team)
  • Team: The name of the team the ticket is assigned to (empty when the ticket is not assigned to a team)
  • Channel ID: The ID of the installed channel where the ticket was created
  • Channel Name: The name of the installed channel where the ticket was created
  • Channel Type: The type of data the channel carries: Chat, Call, Comment, Email, Review or Survey. A channel carrying several data types is exported as a /-joined list, e.g. Chat/Comment
  • Source ID: The ID of the source the channel belongs to (e.g. Facebook, Zalo OA)
  • Source Name: The name of the source the channel belongs to
  • Ticket Link: The link to the ticket in the Filum CX platform
  • Customer Link: The link to the customer profile in the Filum CX platform
  • SLA *: The status of each SLA metric on the ticket — Đáp ứng (met), Không đáp ứng (breached) or Pending. Empty when the metric does not apply to the ticket
  • Custom Fields: Additional custom fields defined in your workspace, with their respective values
note

Columns are added over time, and new ones are inserted next to the columns they relate to rather than appended at the end. Read the CSV by its header row rather than by column position, so a new column cannot shift your integration. The JSON format is keyed by column name and is unaffected either way.

Deprecated columns​

Channel ID and Channel Name were previously named Installed Source ID and Installed Source Name. Both names are still exported, side by side and with the same values, so existing integrations keep working:

Deprecated columnReplacement
Installed Source IDChannel ID
Installed Source NameChannel Name

The deprecated columns are kept for backward compatibility. New integrations should read Channel ID / Channel Name.

Rate Limiting​

The API endpoints are rate-limited to ensure fair usage and system stability. The default rate limits are:

  • Per second: 5 requests
  • Per minute: 50 requests

If you exceed these limits, you will receive a 429 Too Many Requests response. Please implement appropriate retry logic with exponential backoff in your integration.

Error Responses​

400 Bad Request​

No date range given:

{
"detail": {
"message": "Provide a created date range (start_date/end_date) or an updated date range (updated_start_date/updated_end_date).",
"params": null
}
}

A window wider than 90 days:

{
"detail": {
"message": "Export is limited to {{max_days}} days per file. The requested range covers {{requested_days}} days. Please export in smaller ranges.",
"params": { "max_days": 90, "requested_days": 365 }
}
}

An end date with no matching start date:

{
"detail": {
"message": "Export requires a start date, covering at most {{max_days}} days.",
"params": { "max_days": 90 }
}
}

An end date earlier than its start date:

{
"detail": {
"message": "end_date must be on or after start_date",
"params": null
}
}

The {{...}} placeholders in message are filled from params, so a client can render the message in its own locale.

429 Too Many Requests​

{
"detail": "Rate limit exceeded"
}