List tickets

Returns a paginated list of tickets in your organization, ordered by the sort field. A ticket is the case container: it always has one primary conversation with the requester, plus any side conversations. To export everything since a point in time, page this endpoint with an updatedAt[gte] filter, then fetch each changed ticket’s threads.

GET /v1/tickets

Authentication

Bearer token in the Authorization header. See Authentication.

Authorization: Bearer rfl_live_...

Query parameters

Pagination

integer

default:"20"

Number of tickets per page. Range 1–100.

string

Opaque cursor from the previous response’s nextCursor. See Pagination.

Sorting

string

default:"-updatedAt"

Field and direction. Prefix with - for descending. One of:

createdAt
-createdAt
updatedAt
-updatedAt

Filters

string | string[]

Filter by ticket status. Repeat the parameter to match multiple values (e.g. ?status=open&status=snoozed). Matching is exact — resolved does not include assumed_resolved. One of:

open
snoozed
resolved
assumed_resolved
closed

string

Only return tickets this contact is involved in: as the requester, or as a participant in any of the ticket’s conversations. Compare requester.id to tell which. An unknown contact ID gives an empty list. Get the ID from List contacts.

Date range

Use either createdAt or updatedAt ranges — not both. Mixing them returns 422 conflicting_date_range.

string (ISO 8601)

Only return tickets created on or after this timestamp.

string (ISO 8601)

Only return tickets created on or before this timestamp.

string (ISO 8601)

Only return tickets updated on or after this timestamp.

string (ISO 8601)

Only return tickets updated on or before this timestamp.

Response

Returns a list envelope containing Ticket objects.

The Ticket object

string

Unique identifier prefixed with ti_.

string

Always "ticket".

string | null

Your own ID for the ticket, set when it was created through the API. null for every other ticket.

string

Ticket subject or summary.

string

Ticket lifecycle status. One of the values listed under the status query parameter.

string

Who has the customer’s thread: ai (Replyful’s AI or your own chatbot) or human (your team).

object

The contact the ticket is for.

Show properties

string

Contact ID prefixed with con_.

string | null

Your own user ID for the contact, from the API or user identification. null if none.

string | null

First name, if known.

string | null

Last name, if known.

string | null

Contact display name.

object | null

The contact’s email address, or null if none is known.

Show properties

string

The email address.

boolean

true when ownership of the address is proven — verified by the contact or asserted by your own backend via user identification. false for an address the contact merely typed in.

string | null

The contact’s phone number as they typed it (for example in the chat handover), or null. Not normalised.

array

Tags applied to the ticket.

Show properties

string

Tag ID.

string

Tag name.

array

Topics applied to the ticket.

Show properties

string

Topic ID.

string

Topic name.

integer | null

Replyful’s AI estimate of how satisfied the customer is, from 1 (poor) to 5 (great). The customer didn’t give this score; for their own answer, see rating. null until the ticket has been analyzed — analysis runs after the ticket is resolved.

object | null

The customer’s own answer to the customer satisfaction survey. null when no survey was sent, or it was sent and the customer hasn’t answered yet.

{ "score": 5, "comment": "Quick and friendly, thanks!", "ratedAt": "2026-04-30T09:12:00Z" }

Show properties

integer

The customer’s rating, from 1 (poor) to 5 (great).

string | null

The customer’s optional comment. null when they left none, or when the ticket’s content has been erased (the score is kept).

string

ISO 8601 UTC timestamp of the customer’s answer. If they change their rating, this is the latest one.

object[]

The data fields saved for this case, like an order number: the ticket’s own and the ones remembered on the requester. Empty when none are saved. Values are erased with the ticket or the contact.

Show properties

string

The field’s key, as processes mention it (order_number).

string

The field’s name.

string

The value, written in the field’s format.

string

ticket (asked again on the next case) or contact (remembered).

string

handover when the visitor typed it in the handover form, ai when the AI read it in the chat.

string

ISO 8601 UTC timestamp of the latest save.

string | null

What kind of email the ticket is: request, notification, marketing, cold_outreach, auto_reply or bounce. null for chat tickets and email from before categories existed. An agent replying makes it request, and so does the customer replying, unless it is cold_outreach or marketing. A category an agent picks by hand stays until they change it.

string | null

Set when the customer wrote back more than 7 days after an earlier ticket was resolved or closed: this ticket was opened as a follow-up, and the field holds the earlier ticket’s ID. null otherwise.

string | null

The language the customer writes in on this ticket, as a short code such as sv or de. null until Replyful has detected it.

array

References to every conversation on the ticket, ordered by creation. Exactly one has role: "primary". Fetch a thread via List messages — no ticket detail call needed.

Show properties

string

Conversation ID prefixed with conv_.

string

primary (the requester’s thread) or side (an isolated thread with another party).

string

ISO 8601 UTC timestamp of ticket creation.

string

ISO 8601 UTC timestamp of the most recent update.

Examples

List the most recently updated tickets

curl "https://api.replyful.com/v1/tickets?limit=5" \
  -H "Authorization: Bearer rfl_live_..."

const res = await fetch(
  "https://api.replyful.com/v1/tickets?limit=5",
  { headers: { Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}` } },
);
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.replyful.com/v1/tickets",
    headers={"Authorization": f"Bearer {os.environ['REPLYFUL_API_KEY']}"},
    params={"limit": 5},
)
res.raise_for_status()
data = res.json()["data"]

Response

{
  "object": "list",
  "data": [
    {
      "id": "ti_8kNwq2Tt7yGkX9wM4bDfP",
      "object": "ticket",
      "externalId": null,
      "title": "Refund request",
      "status": "open",
      "handledBy": "human",
      "requester": {
        "id": "con_9dKmT3xWq6bYrN8cJfA2eH4gp",
        "externalId": null,
        "firstName": "Ada",
        "lastName": "Lovelace",
        "name": "Ada Lovelace",
        "email": { "email": "[email protected]", "verified": true },
        "phone": null
      },
      "tags": [
        { "id": "tag_7fQwXk3mB9tRc2Ns6", "name": "vip" }
      ],
      "topics": [
        { "id": "tpc_4mHbW8xKq2eYd7Tf3", "name": "Billing" }
      ],
      "estimatedScore": null,
      "rating": null,
      "dataFields": [
        {
          "key": "order_number",
          "name": "Order number",
          "value": "ORD-482913",
          "savedOn": "ticket",
          "source": "handover",
          "updatedAt": "2026-04-29T14:31:10Z"
        }
      ],
      "followUpOfTicketId": null,
      "category": "request",
      "language": "en",
      "conversations": [
        { "id": "conv_x7Kw2mQb9tRfN4c", "role": "primary" },
        { "id": "conv_p3Tf8xWq2mKb6rN", "role": "side" }
      ],
      "createdAt": "2026-04-29T14:30:00Z",
      "updatedAt": "2026-04-29T14:32:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJzIjoiMjAyNi0wNC0yOVQxNDozMjowMC4wMDBaIiwiaSI6InRpXzhrTndxMlR0N3lHa1g5d000YkRmUCJ9",
  "url": "/v1/tickets"
}

Export everything updated since a timestamp

curl --get "https://api.replyful.com/v1/tickets" \
  -H "Authorization: Bearer rfl_live_..." \
  --data-urlencode "updatedAt[gte]=2026-04-01T00:00:00Z" \
  --data-urlencode "sort=updatedAt" \
  --data-urlencode "limit=100"

List a contact’s tickets

Use sort=createdAt when you need every ticket, for example to export everything about a person. With the default sort, a ticket that is updated while you page can be skipped. With sort=createdAt a ticket created during the walk shows up at the end, and nothing is skipped or repeated.

curl --get "https://api.replyful.com/v1/tickets" \
  -H "Authorization: Bearer rfl_live_..." \
  --data-urlencode "contactId=con_9dKmT3xWq6bYrN8cJfA2e" \
  --data-urlencode "sort=createdAt" \
  --data-urlencode "limit=100"

Walk every page

See the pagination guide for a copy-paste loop in Node and Python.

Error responses

Status	`error.code`	When
`401`	`missing_api_key`	The `Authorization` header is absent.
`401`	`invalid_api_key`	The token is malformed, unknown, or archived.
`422`	`invalid_query_parameter`	A query parameter failed validation. The `param` field names the offender.
`422`	`invalid_cursor`	The `startingAfter` cursor could not be decoded.
`422`	`conflicting_date_range`	Both `createdAt[...]` and `updatedAt[...]` were provided.
`429`	`too_many_requests`	Rate limit exceeded. Honor `Retry-After`.

See Errors for the full error envelope reference.

Documentation

Tickets

Channels

Conversations

Contacts

Attachments

Knowledge

Authentication

Query parameters

Sorting

Filters

Date range

Response

The Ticket object

Examples

List the most recently updated tickets

Export everything updated since a timestamp

List a contact’s tickets

Walk every page

Error responses

​Authentication

​Query parameters

​Pagination

​Sorting

​Filters

​Date range

​Response

​The Ticket object

​Examples

​List the most recently updated tickets

​Export everything updated since a timestamp

​List a contact’s tickets

​Walk every page

​Error responses

Authentication

Query parameters

Pagination

Sorting

Filters

Date range

Response

The Ticket object

Examples

List the most recently updated tickets

Export everything updated since a timestamp

List a contact’s tickets

Walk every page

Error responses