Tickets

Get Ticket Form by ID

GET 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*	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

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

Response

200: OK

{
  "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"
  }
}

404: Not Found

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

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 to get the full form details

List Ticket Forms

GET 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_ids before calling 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

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.

200: OK

{
  "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
  }
}

Create Ticket via Form

POST 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 (GET /v1/rest/tickets/forms) to find available forms, or Get Ticket Form by ID to inspect a specific form's fields and integration_type.

• Custom field ids — Use 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.

Request Body

Name	Type	Description
type*	string	Must be "create".
form_id*	integer	The id of the ClearFeed ticket form to use. Must refer to an existing, enabled ClearFeed-type form.
description*	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 below. Optional — required fields configured on the form must still be supplied here.
<attachment files>	file	Optional file attachments. See 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) and the value to a format that matches the field's type. Refer to the 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

FIELDS='{"title":"Comprehensive all valid mixed test","priority":"low","assignee":"[e-mail]","assigned_team":"S0B4C8D470X","contributors":["[e-mail]","[e-mail]"],"12":"3","15":["1","2"],"54":"[e-mail]"}'

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

201: Created

{
  "ticket": {
    "id": 12345
  }
}

Link Ticket to Request

POST 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*	string	The type of ticket action to perform. Must be link.
data*	object	Contains the ticket linking information. See 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*	string	The external ticketing integration name. Supported values: zendesk, clickup.
ticket_id*	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.

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*	string	The unique identifier (timestamp) of the Slack message to link with the ticket (e.g., "1750828950.739009").
channel_id*	string	The monitored Slack channel ID where the message exists (e.g., "C05UGMKEHHN").
message_source*	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*	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 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:

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

Link via Request ID:

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

Link as Task with Sync Overrides:

{
  "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:

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:

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:

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

201: Created

The ticket was successfully linked. The API returns an empty body on success.

400: Bad Request

{
  // 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"
}

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)

⚠️ Important: 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.