# Tickets

Tickets represent support requests in your Featurebase organization. Create, update, reply to, and manage tickets via these endpoints.

## List tickets

 - [GET /v2/tickets](https://docs.featurebase.app/rest-api/tickets/listtickets.md): Returns a list of tickets in your organization using cursor-based pagination.

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| limit | number | Number of tickets to return (1-100, default 10) |
| cursor | string | Cursor from previous response for pagination |
| ticketCategoryIds | string[] | Filter by ticket category IDs |
| statusIds | string[] | Filter by status IDs |
| q | string | Search query |
| assigneeId | string | Filter by assignee ID |
| categoryType | string | Filter by category type: "customer", "tracker", or "back-office" |
| sortBy | string | Sort field: "date" (default), "recent", or "ticketNumber" |
| sortOrder | string | Sort direction: "asc" or "desc" (default) |

### Response

Returns a list object with data (array of ticket objects) and nextCursor.

## Create a ticket

 - [POST /v2/tickets](https://docs.featurebase.app/rest-api/tickets/createticket.md): Creates a new ticket.

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| ticketCategoryId | string | Ticket category ID |
| title | string | Ticket title (min 2 characters) |
| author | object | Author/contact info (id, userId, email, name, profilePicture) |

### Optional Fields

| Field | Type | Description |
|-------|------|-------------|
| content | string | Ticket description (HTML) |
| customFields | object | Custom field values |
| companyId | string | Company to associate |
| linkedConversationId | string | Conversation to link |
| assigneeId | string | Admin to assign |
| statusId | string | Initial status |
| createdAt | string | ISO 8601 timestamp for backdating |
| skipNotifications | boolean | Skip sending notifications (default false) |

### File Custom Fields

File-type custom fields can be provided in two ways:

Method 1: Multipart upload — Send the request as multipart/form-data. Put the JSON body in a field named data, and attach files with field names like customFields.. For allowMultiple fields, send multiple files with the same field name.

Method 2: External URL — In the JSON body, set the file custom field value to { "url": "https://..." }. Optionally include "name" to set the filename (e.g. { "url": "https://...", "name": "report.pdf" }); if omitted, the filename is extracted from the download response. For allowMultiple fields, use an array: [{ "url": "..." }, ...]. The server downloads the file (max 10MB, HTTPS only) and stores it.

Both methods produce signed download URLs in the response.

Limits: Max 10 files per request, 400MB total upload size. Executable file types (.exe, .bat, .js, .sh, etc.) are blocked.

Response format: File custom field values in the response are JSON strings containing { "key": "...", "name": "...", "url": "https://signed-url..." }. For allowMultiple fields, an array of these objects. The url is a time-limited signed download URL (expires in 1 hour).

### Response

Returns the created ticket object with 201 Created status.

## Get a ticket

 - [GET /v2/tickets/{id}](https://docs.featurebase.app/rest-api/tickets/getticket.md): Retrieves a single ticket by its ticket number.

### Path Parameters

- id - The ticket number (e.g. 42 from TK-42)

### Response

Returns the ticket object, including conversationParts from the linked conversation (message history).

## Update a ticket

 - [PATCH /v2/tickets/{id}](https://docs.featurebase.app/rest-api/tickets/updateticket.md): Updates a ticket's properties. Only provided fields will be updated.

### Path Parameters

- id - The ticket number

### Request Body

All fields are optional.

| Field | Type | Description |
|-------|------|-------------|
| title | string | Update title |
| content | string | Update description (HTML) |
| statusId | string | Set status by ID |
| open | boolean | Close (false) or reopen (true) the ticket |
| assigneeId | string/null | Assign/unassign admin |
| companyId | string/null | Update company association |
| customFields | object | Update custom field values |
| snoozedUntil | string/null | Snooze until ISO 8601 timestamp (null to unsnooze) |
| skipNotifications | boolean | Skip notifications (default false) |

### Closing a Ticket

Set open: false to close the ticket. Closing a ticket will also unsnooze it. The status is not changed automatically — use statusId to change the status explicitly.

### File Custom Fields

File-type custom fields support the same two upload methods as ticket creation: multipart upload (customFields. file parts with JSON in the data field) and external URLs ({ "url": "https://..." } with optional "name" in the custom field value). Same limits apply (10 files, 400MB total, executable types blocked).

### Response

Returns the updated ticket object.

## Delete a ticket

 - [DELETE /v2/tickets/{id}](https://docs.featurebase.app/rest-api/tickets/deleteticket.md): Permanently deletes a ticket by its ticket number.

### Path Parameters

- id - The ticket number

### Response

Returns a deletion confirmation:

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "ticket",
  "deleted": true
}


### Behavior

- Customer-facing tickets: Deletes the ticket and its linked conversation.
- Back-office / tracker tickets: Deletes the ticket and unlinks it from the conversation (conversation is preserved).

### Caution

This operation is irreversible.

## Reply to a ticket

 - [POST /v2/tickets/{id}/reply](https://docs.featurebase.app/rest-api/tickets/replytoticket.md): Adds a reply to a ticket's linked conversation. Supports both contact and admin replies.

### Path Parameters

- id - The ticket number

### Contact Reply

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| type | string | Yes | Must be "contact" |
| contactId | string | No* | Featurebase contact ID |
| contactEmail | string | No* | Contact email |
| body | string | Yes | Message content (HTML) |
| messageType | string | No | Always "comment" for contacts |
| attachmentUrls | string[] | No | Attachment URLs (max 10) |
| skipNotifications | boolean | No | Skip notifications (default false) |
| createdAt | string | No | ISO 8601 timestamp to backdate the reply |

*At least one of contactId or contactEmail is required.

### Admin Reply

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| type | string | Yes | Must be "admin" |
| adminId | string | Yes | ID of the admin authoring the reply |
| body | string | Yes | Message content (HTML) |
| messageType | string | No | "comment" (default) or "note" for internal notes |
| attachmentUrls | string[] | No | Attachment URLs (max 10) |
| skipNotifications | boolean | No | Skip notifications (default false) |
| createdAt | string | No | ISO 8601 timestamp to backdate the reply |

### Response

Returns a reply confirmation object.

## List custom fields

 - [GET /v2/tickets/custom_fields](https://docs.featurebase.app/rest-api/tickets/listticketcustomfields.md): Returns all custom fields configured in your organization that can be used on tickets.

This endpoint returns all custom fields at once. No pagination is supported.

### Custom Field Object

Each custom field includes:
- id - Unique field identifier
- label - Field label displayed to users
- type - Field type (text, number, select, multi-select, checkbox, date, file)
- required - Whether the field is required
- placeholder - Placeholder text (for text/number fields)
- public - Whether the field value is publicly visible
- internal - Whether the field is for internal use only
- options - Array of options (for select/multi-select fields)
- allowMultiple - Whether multiple files can be uploaded (file fields only)

## Get a custom field by ID

 - [GET /v2/tickets/custom_fields/{id}](https://docs.featurebase.app/rest-api/tickets/getticketcustomfield.md): Retrieves a single custom field by its unique identifier.

### Response

Returns a custom field object with:
- id - Unique field identifier
- label - Field label displayed to users
- type - Field type (text, number, select, multi-select, checkbox, date, file)
- required - Whether the field is required
- placeholder - Placeholder text (for text/number fields)
- public - Whether the field value is publicly visible
- internal - Whether the field is for internal use only
- options - Array of options (for select/multi-select fields)
- allowMultiple - Whether multiple files can be uploaded (file fields only)

## List ticket categories

 - [GET /v2/tickets/categories](https://docs.featurebase.app/rest-api/tickets/listticketcategories.md): Returns all ticket categories for the authenticated organization.

Ticket categories organize tickets into distinct containers. Each category can have different:
- Access controls (public, private, segment-restricted)
- Feature toggles (comments, posting enabled)
- Custom fields

Use the supportBoard and supportBoardType fields to identify ticket categories.

This endpoint returns all categories without pagination.

## Get a ticket category by ID

 - [GET /v2/tickets/categories/{id}](https://docs.featurebase.app/rest-api/tickets/getticketcategory.md): Retrieves a single ticket category by its unique identifier.

Returns the full category object including access controls, feature toggles, and localization settings.

## List ticket statuses

 - [GET /v2/tickets/statuses](https://docs.featurebase.app/rest-api/tickets/listticketstatuses.md): Returns all ticket statuses for the authenticated organization.

Ticket statuses define workflow stages. Each status has:
- A display name and color
- A type indicating the workflow stage (reviewing, unstarted, active, completed, canceled)
- A flag indicating if it's the default status for new tickets

This endpoint returns all statuses without pagination.

## Get a ticket status by ID

 - [GET /v2/tickets/statuses/{id}](https://docs.featurebase.app/rest-api/tickets/getticketstatus.md): Retrieves a single ticket status by its unique identifier.

Returns the status object including name, color, type, and default flag.