Ticket APIs

Use the ticket APIs to create support tickets from external systems and retrieve 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	5 requests
Per hour	200 requests
Per day	1000 requests

Request Body

Field	Type	Required	Description
customer	object	Yes	Customer information. See Customer Object.
orderName	string	No	Order name or order number associated with the ticket.
subject	string	No	Short summary or title for the ticket.
query	string	Yes	Customer question or issue description. Either subject or query must be provided.
payload	string	No	Additional context as a JSON string, for example "{\"key\":\"value\"}".
payloadFormat	string	No	Identifier for the payload structure. Use a unique name for each distinct payload shape.
source	string	No	Ticket source. Accepted values are whatsapp, email, liveChat, instagram, voiceCall, and manual.
taskName	string	No	Workflow task name to route the ticket to. It is looked up by name within the account.
relatedTicketNumber	string	No	Ticket number of a related or previous ticket.
fastResponse	boolean	No	If true, the API returns ticketId instead of requestId.
skipExecuteAction	boolean	No	If true, Flowcall skips configured execution actions for the ticket.
images	string[]	No	Image URLs related to the ticket.

Customer Object

Field	Type	Required	Description
name	string	No	Customer full name.
phone	string	Yes*	Customer phone number.
email	string	Yes*	Customer email address.
shopifyCustomerId	string	No	Shopify customer ID, if applicable.

*Either phone or email is required.

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",
    "subject": "Return request - wrong size",
    "query": "I want to return my order, the size does not fit.",
    "payload": "{\"source\":\"ivr\",\"priority\":\"high\"}",
    "payloadFormat": "ivr_return_v1",
    "source": "voiceCall",
    "relatedTicketNumber": "TKT-2048",
    "fastResponse": true,
    "skipExecuteAction": true,
    "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"
  },
  "requestId": "64f7b2c1c9d2a4e7b1f3a9d0"
}

When fastResponse is true, the response includes ticketId instead of requestId:

{
  "success": true,
  "customer": {
    "id": "cust_abc123",
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "john@example.com"
  },
  "ticketId": "64f7b2c1c9d2a4e7b1f3a9d0"
}

Error Responses

Status	Body	Cause
400	{ "error": "phone or email is required" }	Missing customer.phone and customer.email.
403	{ "error": "Not authorized" }	Invalid or missing Bearer token.
429	Rate limit error	Rate limit exceeded.

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, 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.

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 or number, customer name, email, and phone.
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 exact ticket name or number. Supports comma-separated values.
source	string	Filter by ticket source.

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.

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",
      "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