> For the complete documentation index, see [llms.txt](https://docs.clearfeed.ai/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clearfeed.ai/api/reference/api-reference/tickets.md).

# Tickets

## Get Ticket Form by ID

<mark style="color:blue;">`GET`</mark> `https://api.clearfeed.app/v1/rest/tickets/forms/:id`

Retrieves detailed information about a ticket form by its ID, including the form's configuration, fields, and integration type.

### Path Parameters

| Name                                 | Type    | Description                       |
| ------------------------------------ | ------- | --------------------------------- |
| id<mark style="color:red;">\*</mark> | integer | The unique identifier of the form |

### Response

Returns a ticket form object with the following properties:

| Name              | Type    | Description                                                              |
| ----------------- | ------- | ------------------------------------------------------------------------ |
| id                | integer | The unique identifier of the form                                        |
| name              | string  | The display name of the form                                             |
| description       | string  | The description of the form (can be null)                                |
| enabled           | boolean | Whether the form is enabled for use                                      |
| action\_config    | object  | Configuration object containing the form's actions and field definitions |
| created\_at       | string  | The creation timestamp of the form                                       |
| updated\_at       | string  | The update timestamp of the form                                         |
| integration\_type | string  | The type of integration this form is associated with                     |

### Example Request

```bash
curl --location 'https://api.clearfeed.app/v1/rest/tickets/forms/789' \
--header 'Authorization: Bearer YOUR_API_TOKEN'
```

### Response

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "ticket_form": {
    "id": 789,
    "name": "Customer Support Request",
    "description": "Standard support ticket form for customer inquiries",
    "enabled": true,
    "action_config": {
      "create": {
        "enabled": true,
        "fields": [
          {
            "key": "subject",
            "audience": "all",
            "is_hidden": false,
            "required_by_responder": true,
            "required_by_non_responder": true
          },
          {
            "key": "description",
            "audience": "all",
            "is_hidden": false,
            "required_by_responder": true,
            "required_by_non_responder": true
          }
        ]
      }
    },
    "created_at": "2025-01-03T05:38:21.836Z",
    "updated_at": "2025-08-19T12:38:32.872Z",
    "integration_type": "zendesk"
  }
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "message": "Ticket form with id 789 not found",
  "error": "NOT_FOUND"
}
```

{% endtab %}
{% endtabs %}

### Notes

* This endpoint returns form details only for forms that belong to the authenticated account
* The `action_config` object contains the form's field definitions and validation rules
* Use this endpoint when you receive a `form_id` in the [Requests API](/api/reference/api-reference/requests.md#ticket-object) to get the full form details

## List Ticket Forms

<mark style="color:blue;">`GET`</mark> `https://api.clearfeed.app/v1/rest/tickets/forms`

Returns ticket forms for the authenticated account, sorted and paginated by creation time. Use this endpoint to discover available `form_id`s before calling [Create Ticket via Form](#create-ticket-via-form).

### Query Parameters

| Name               | Type     | Description                                                                                                                                      |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`          | boolean  | Optional. Filter by enabled state (`true` or `false`).                                                                                           |
| `integration_type` | string   | Optional. Filter forms by integration type. Allowed values: `clearfeed`, `zendesk`, `freshdesk`, `hubspot`, `clickup`, `intercom`, `salesforce`. |
| `sort_order`       | string   | Optional. `asc` or `desc`. Defaults to `desc` (newest first).                                                                                    |
| `next_cursor`      | string   | Optional. Cursor from a previous response's `response_metadata.next_cursor` to fetch the next page.                                              |
| `limit`            | number   | Optional. Number of results per page (1–100). Defaults to 50.                                                                                    |
| `after`            | ISO date | Optional. Return forms created strictly after this ISO 8601 timestamp.                                                                           |
| `before`           | ISO date | Optional. Return forms created strictly before this ISO 8601 timestamp.                                                                          |

### Example Request

```bash
curl --location 'https://api.clearfeed.app/v1/rest/tickets/forms?enabled=true&integration_type=clearfeed&limit=20' \
--header 'Authorization: Bearer YOUR_API_TOKEN'
```

### Response

Returns an object with a `ticket_forms` array and a `response_metadata` object. Each form in `ticket_forms` has the same shape as the response of [Get Ticket Form by ID](#get-ticket-form-by-id).

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "ticket_forms": [
    {
      "id": 789,
      "name": "Customer Support Request",
      "description": "Standard support ticket form for customer inquiries",
      "enabled": true,
      "action_config": {
        "edit": {
          "enabled": true,
          "fields": [
            {
              "key": "priority",
              "audience": "responder",
              "is_hidden": false,
              "required_by_responder": false
            },
            {
              "key": "assignee",
              "audience": "responder",
              "is_hidden": false,
              "required_by_responder": false
            },
            {
              "key": "status",
              "audience": "responder",
              "is_hidden": false,
              "required_by_responder": false
            },
            {
              "key": "assigned_team",
              "audience": "responder",
              "is_hidden": false,
              "required_by_responder": false
            },
            {
              "key": "contributors",
              "audience": "responder",
              "is_hidden": false,
              "required_by_responder": false
            }
          ]
        },
        "create": {
          "enabled": true,
          "fields": [
            {
              "key": "title",
              "audience": "all",
              "is_hidden": false,
              "required_by_responder": true,
              "required_by_non_responder": true
            },
            {
              "key": "priority",
              "audience": "all",
              "is_hidden": false,
              "required_by_responder": true,
              "required_by_non_responder": true
            },
            {
              "key": "153",
              "audience": "all",
              "required_by_responder": true,
              "required_by_non_responder": true
            }
          ]
        }
      },
      "created_at": "2025-01-03T05:38:21.836Z",
      "updated_at": "2025-08-19T12:38:32.872Z",
      "integration_type": "clearfeed"
    },
    {
      "id": 790,
      "name": "Bug Report",
      "description": "Form for reporting bugs",
      "enabled": true,
      "action_config": {
        "create": {
          "enabled": true,
          "fields": [
            {
              "key": "customer_email",
              "audience": "all",
              "is_hidden": true,
              "required_by_responder": true,
              "required_by_non_responder": true
            },
            {
              "key": "_default_title_",
              "audience": "all",
              "is_hidden": true,
              "required_by_responder": true,
              "required_by_non_responder": true
            },
            {
              "key": "_default_description_",
              "audience": "all",
              "is_hidden": true,
              "required_by_responder": true,
              "required_by_non_responder": true
            }
          ]
        },
        "edit": {
          "enabled": true,
          "fields": [
            {
              "key": "state",
              "audience": "responder",
              "required_by_responder": true
            },
            {
              "key": "assignee",
              "audience": "responder",
              "required_by_responder": false
            }
          ]
        }
      },
      "created_at": "2025-02-10T09:12:00.000Z",
      "updated_at": "2025-04-22T14:05:11.000Z",
      "integration_type": "clearfeed"
    }
  ],
  "response_metadata": {
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMi0xMFQwOToxMjowMC4wMDBaIiwiaWQiOjc5MH0=",
    "count": 2
  }
}
```

{% endtab %}
{% endtabs %}

## Create Ticket via Form

<mark style="color:green;">`POST`</mark> `https://api.clearfeed.app/v1/rest/tickets`

Creates a new ticket in ClearFeed using a configured ClearFeed ticket form.

Only **ClearFeed-type** ticket forms that are **enabled** are supported via this endpoint. External integration forms are not supported.

The request must be sent as `multipart/form-data`.

### Obtaining `form_id` and Custom Field IDs

* **`form_id`** — Use [List Ticket Forms](#list-ticket-forms) (`GET /v1/rest/tickets/forms`) to find available forms, or [Get Ticket Form by ID](#get-ticket-form-by-id) to inspect a specific form's fields and `integration_type`.
* **Custom field ids** — Use [Get All Custom Fields](/api/reference/api-reference/custom-fields.md#get-all-custom-fields) to retrieve the available custom fields for your account. The numeric `id` returned by that endpoint for particular form fields is the key you must use inside the `fields` object. Each value must match the field type's expected format — see the [Custom Field Value Format Guide](/api/reference/api-reference/requests.md#custom-field-value-format-guide).

### Request Body

| Name                                          | Type    | Description                                                                                                                                                                                                |
| --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type<mark style="color:red;">\*</mark>        | string  | Must be `"create"`.                                                                                                                                                                                        |
| form\_id<mark style="color:red;">\*</mark>    | integer | The id of the ClearFeed ticket form to use. Must refer to an existing, enabled ClearFeed-type form.                                                                                                        |
| description<mark style="color:red;">\*</mark> | string  | The ticket description in HTML format. **Max length:** 4000 characters.                                                                                                                                    |
| fields                                        | string  | A **JSON-encoded string** representing an object that maps field keys to values. See [Fields Object](#fields-object) below. Optional — required fields configured on the form must still be supplied here. |
| `<attachment files>`                          | file    | Optional file attachments. See [Attachments](#attachments) below.                                                                                                                                          |

### Fields Object

The `fields` parameter is a JSON-encoded object containing both **standard** field keys and **custom field ids**.

#### Standard Field Keys

| Key             | Type      | Description                                                                 |
| --------------- | --------- | --------------------------------------------------------------------------- |
| `title`         | string    | Title of the ticket. If omitted, a title will be generated using AI.        |
| `priority`      | string    | Priority of the ticket. Allowed values: `low`, `normal`, `high`, `urgent`.  |
| `assignee`      | string    | **Email** of the workspace user to assign the ticket to.                    |
| `contributors`  | string\[] | Array of **emails** of workspace users to add as contributors.              |
| `assigned_team` | string    | The **Slack user-group id** (e.g. `S0123ABCD`) of an active ClearFeed team. |
| `status`        | string    | Initial status of the ticket, if the form supports it.                      |

#### Custom Field Keys

For every custom field on the form, set the key to the **numeric custom-field id** (from [Get All Custom Fields](/api/reference/api-reference/custom-fields.md#get-all-custom-fields)) and the value to a format that matches the field's type. Refer to the [Custom Field Value Format Guide](/api/reference/api-reference/requests.md#custom-field-value-format-guide) for the expected value format per type, except user\_select and attachments which are detailed below.

For custom fields of type `user_select`, the value must be the **email** of a workspace user (resolved server-side to a user id).

### Attachments

Attachments are sent as additional `multipart/form-data` parts:

* **Story-level attachments** — use the form field name `attachment` for files that should be attached to the ticket's first message.
* **Custom-field attachments** — for custom fields of type `attachment`, use the **numeric custom-field id** as the form field name (e.g. `--form '20=@/path/to/file'`).

**Limits:** Maximum **5 files**, each up to **100MB**.

### Example Request

```bash
FIELDS='{"title":"Comprehensive all valid mixed test","priority":"low","assignee":"yuvraj@clearfeed.ai","assigned_team":"S0B4C8D470X","contributors":["yuvraj@clearfeed.ai","random@clearfeed.ai"],"12":"3","15":["1","2"],"54":"yuvraj@clearfeed.ai"}'

curl -i \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "type=create" \
  -F "form_id=8618" \
  -F "description=<p>Comprehensive all valid mixed assignment test with user select, multi select, and attachment fields.</p>" \
  -F "fields=$FIELDS" \
  -F "attachment=@/path/to/screenshot.png" \
  -F "154=@/path/to/invoice.pdf" \
  "https://api.clearfeed.app/v1/rest/tickets"
```

In the example above:

* `title`, `priority`, `assignee`, `assigned_team`, and `contributors` are standard fields — `assignee` and each entry in `contributors` is a workspace user email, and `assigned_team` is the Slack user-group id of an active ClearFeed team.
* `12` is a single-select custom field — value is the option id.
* `15` is a multi-select custom field — value is an array of option ids.
* `54` is a `user_select` custom field — value is a workspace user's email.
* `154` is an `attachment` custom field — the file is sent as a multipart part whose field name is `154`.
* `attachment=@...` is a story-level attachment, attached to the ticket's first message.

### Response

{% tabs %}
{% tab title="201: Created" %}

```json
{
  "ticket": {
    "id": 12345
  }
}
```

{% endtab %}
{% endtabs %}

## Link Ticket to Request

<mark style="color:blue;">`POST`</mark> `https://api.clearfeed.app/v1/rest/tickets`

Links an external ticket to a ClearFeed request. You can link using either:

1. **Via Slack Message**: Provide `message_ts`, `channel_id`, and `message_source` to identify the request
2. **Via Request ID**: Provide the ClearFeed `request_id` directly

### Request Body

| Name                                   | Type   | Description                                                                                                   |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| type<mark style="color:red;">\*</mark> | string | The type of ticket action to perform. Must be `link`.                                                         |
| data<mark style="color:red;">\*</mark> | object | Contains the ticket linking information. See [Link Ticket Data Object](#link-ticket-data-object) for details. |

### Link Ticket Data Object

The `data` object must include the following required fields, plus **one** of the following paths for identifying the request:

#### Always Required Fields (All Paths)

| Name                                          | Type   | Description                                                                      |
| --------------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| integration<mark style="color:red;">\*</mark> | string | The external ticketing integration name. Supported values: `zendesk`, `clickup`. |
| ticket\_id<mark style="color:red;">\*</mark>  | string | The ID of the ticket in the external system.                                     |

#### Optional Fields

| Name         | Type    | Description                                                                                                                                                  |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| is\_task     | boolean | If `true`, links as a task (`ADDED`) and allows multiple task links on the same request. If omitted/`false`, link is treated as transferred (`TRANSFERRED`). |
| sync\_config | object  | Optional sync overrides for this link action only. See [Sync Config Object](#sync-config-object-optional).                                                   |

#### Path 1: Link via Slack Message

Use these fields when linking via Slack message identifiers. **Cannot be combined with `request_id`.**

| Name                                              | Type   | Description                                                                                                   |
| ------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| message\_ts<mark style="color:red;">\*</mark>     | string | The unique identifier (timestamp) of the Slack message to link with the ticket (e.g., `"1750828950.739009"`). |
| channel\_id<mark style="color:red;">\*</mark>     | string | The monitored Slack channel ID where the message exists (e.g., `"C05UGMKEHHN"`).                              |
| message\_source<mark style="color:red;">\*</mark> | string | The source of the message. Must be: `slack_channel`.                                                          |

#### Path 2: Link via Request ID

Use this field when linking via ClearFeed request ID. **Cannot be combined with Slack message fields above.**

| Name                                          | Type   | Description                                     |
| --------------------------------------------- | ------ | ----------------------------------------------- |
| request\_id<mark style="color:red;">\*</mark> | number | The ClearFeed request ID to link the ticket to. |

### Sync Config Object (Optional)

| Name                             | Type      | Description                                                                                                                                     |
| -------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| should\_forward\_sync\_comments  | boolean   | Override forward comment sync for this link.                                                                                                    |
| should\_backward\_sync\_comments | boolean   | Override backward comment sync for this link.                                                                                                   |
| notifiable\_fields               | string\[] | Fields that can trigger thread notifications. Currently supported value: `status`. Use `[]` to disable field-based notifications for that link. |
| should\_send\_alert\_message     | boolean   | Whether to post the initial ticket-linked alert message in the request thread (does not disable later sync updates). Default: `true`.           |

**Notes**

* Partial `sync_config` is supported; omitted fields use account/integration defaults.
* `sync_config` applies only to the current link operation; it does not permanently change account settings.

#### Sync Config Behavior (Important)

`sync_config` values are per-request overrides, but they are still evaluated with the account/collection ticketing settings.

1. `sync_config` is merged with existing sync settings\
   If a field is not provided in `sync_config`, ClearFeed uses the saved integration sync settings.
2. `should_backward_sync_comments: false` will not suppress backward behavior when [screen](https://docs.clearfeed.ai/clearfeed-help-center/clearfeed-helpdesk/forms#ticket-message-visibility) is enabled.
3. `should_send_alert_message` only controls the initial "ticket linked" alert message\
   Setting `should_send_alert_message: false` suppresses only the initial link alert.\
   It does **not** disable ongoing sync/subscription-driven updates after linking.

### Example Request Body

**Link via Slack Message:**

```json
{
  "type": "link",
  "data": {
    "integration": "zendesk",
    "ticket_id": "7818",
    "message_ts": "1750828950.739009",
    "channel_id": "C05UGMKEHHN",
    "message_source": "slack_channel"
  }
}
```

**Link via Request ID:**

```json
{
  "type": "link",
  "data": {
    "integration": "clickup",
    "ticket_id": "86ab12cd3",
    "request_id": 12345
  }
}
```

**Link as Task with Sync Overrides:**

```json
{
  "type": "link",
  "data": {
    "integration": "clickup",
    "ticket_id": "86ab12cd3",
    "request_id": 12345,
    "is_task": true,
    "sync_config": {
      "should_forward_sync_comments": true,
      "should_backward_sync_comments": false,
      "notifiable_fields": ["status"],
      "should_send_alert_message": false
    }
  }
}
```

### Example Requests

**Link via Slack Message:**

```bash
curl --location 'https://api.clearfeed.app/v1/rest/tickets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data-raw '{
  "type": "link",
  "data": {
    "integration": "zendesk",
    "ticket_id": "7818",
    "message_ts": "1750828950.739009",
    "channel_id": "C05UGMKEHHN",
    "message_source": "slack_channel"
  }
}'
```

**Link via Request ID:**

```bash
curl --location 'https://api.clearfeed.app/v1/rest/tickets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data-raw '{
  "type": "link",
  "data": {
    "integration": "clickup",
    "ticket_id": "86ab12cd3",
    "request_id": 12345
  }
}'
```

**Link as Task with Sync Overrides:**

```bash
curl --location 'https://api.clearfeed.app/v1/rest/tickets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data-raw '{
  "type": "link",
  "data": {
    "integration": "clickup",
    "ticket_id": "86ab12cd3",
    "request_id": 12345,
    "is_task": true,
    "sync_config": {
      "should_forward_sync_comments": true,
      "should_backward_sync_comments": false,
      "notifiable_fields": ["status"],
      "should_send_alert_message": false
    }
  }
}'
```

### Response

{% tabs %}
{% tab title="201: Created" %}
The ticket was successfully linked. The API returns an empty body on success.
{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
  // Error message varies based on the specific validation failure
  "message": "The message with timestamp '1750828950.739009' from Slack channel 'C05UGMKEHHN' is not available in ClearFeed",
  "error": "BAD_REQUEST"
}
```

{% endtab %}
{% endtabs %}

### Notes

**Two Ways to Identify the Request**

You must provide **exactly one** of the following paths to identify which ClearFeed request to link the ticket to:

1. **Via Slack Message** — Provide all three fields:
   * `message_ts` — The unique identifier (timestamp) for a Slack message
   * `channel_id` — Must be a valid Slack channel ID that is being monitored by ClearFeed
   * `message_source` — Must be `"slack_channel"`
2. **Via Request ID** — Provide only:
   * `request_id` — The ClearFeed request ID (numeric value)

<mark style="color:orange;">⚠️</mark> <mark style="color:orange;"></mark><mark style="color:orange;">**Important:**</mark> Do not mix fields from both paths. The API uses the presence of `request_id` to determine which validation path to apply.

**Supported Integrations**

* `zendesk` — Zendesk tickets
* `clickup` — ClickUp tasks

The API will validate that the request exists and is accessible before creating the link.