# 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)                                |
| 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 cURL 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",
    "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](https://docs.clearfeed.ai/api/reference/requests#ticket-object) to get the full form details

## 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 cURL 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.