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:
| Parameters | Filters on | Use it for |
|---|---|---|
start_date / end_date | ticket created time | "all tickets opened in this period" |
updated_start_date / updated_end_date | ticket last updated time | incremental sync — "everything touched in this period" |
closed_start_date / closed_end_date | ticket 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_datemust be provided. Without any of them the request fails with400. Aclosed_*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_datewith noupdated_end_datemeans "from that date until now". The reverse — an end date with no start date — is rejected with400, because it would reach back to your first ticket ever and silently truncate at 5000 rows. closed_start_dateandclosed_end_dateonly take effect when both are given.- Both bounds are inclusive, and dates are read in the workspace timezone (UTC+7 by default):
start_datebegins at00:00:00of that day andend_dateends at23:59:59of that day.
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.
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
| Name | Description | Required | Schema |
|---|---|---|---|
| start_date | The lower boundary of the created date range | Conditional | date |
| end_date | The upper boundary of the created date range | Conditional | date |
| updated_start_date | The lower boundary of the last updated date range | Conditional | date |
| updated_end_date | The upper boundary of the last updated date range | Conditional | date |
| closed_start_date | The lower boundary of the closed date range. Requires closed_end_date | No | date |
| closed_end_date | The upper boundary of the closed date range. Requires closed_start_date | No | date |
| search | Search term to filter tickets by subject, description, or customer information. Ignored when shorter than 3 characters | No | string |
| statuses | Filter 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 exported | No | [ string ] |
| priorities | Filter tickets by priority. Options are: low, medium, high, urgent | No | [ string ] |
| survey_response_ids | Filter tickets by survey response IDs | No | [ integer ] |
| review_keys | Filter tickets by review keys | No | [ string ] |
| assignee_account_ids | Filter tickets by assignee account IDs | No | [ integer ] |
| creator_account_ids | Filter 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 ] |
| overdue | Filter tickets that are overdue (past their due date and still open or pending) | No | boolean |
| has_assignee | true returns only assigned tickets, false only unassigned ones | No | boolean |
| has_team | true returns only tickets that belong to a team, false only tickets without one | No | boolean |
| assigned_to_me | Filter tickets assigned to the current user | No | boolean |
| installed_source_ids | Filter tickets by channel (installed source) IDs | No | [ integer ] |
| custom_field_<id> | Filter by a custom field value, where <id> is the custom field ID — e.g. custom_field_42=VIP | No | [ 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
| Name | Description | Required | Schema |
|---|---|---|---|
| authorization | The authorization token to validate the request. The value must be in the format Bearer <your_api_token> | Yes | string |
| organization-id | The unique identifier of your organization | Yes | string |
| auth-type | The type of authorization used for the request. In this case, the value must be token | Yes | string |
| accept | The format of the exported file. Options are: text/csv, application/x-ndjson, or */* (treated as text/csv) | Yes | string |
Responses
| Code | Description | Content type |
|---|---|---|
| 200 | Successful Response | text/csv; charset=utf-16le or application/x-ndjson; charset=utf-16le |
| 400 | Bad Request (missing, inverted or too-wide date range) | application/json |
| 422 | Validation Error | application/json |
| 429 | Too Many Requests | application/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,RevieworSurvey. 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) orPending. Empty when the metric does not apply to the ticket - Custom Fields: Additional custom fields defined in your workspace, with their respective values
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 column | Replacement |
|---|---|
Installed Source ID | Channel ID |
Installed Source Name | Channel 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"
}