Requests

Request Object

Requests are represented as JSON objects with the following properties

Name	Type	Description
id	integer	The ID of the request
title	string	The title of the request
state	string	The state of the request. Allowed values : open, in_progress, pending, on_hold, solved, closed, null
not_a_request_state	string	temporary - marked as not-a-request temporarily, there is a possibility of re-opening the request permanent - marked as not-a-request permanently null - All the requests that were created and were never marked as not a request
priority	string	The priority of the request. Allowed values : low, normal, high, urgent
author	object	An object containing details of the request author.
author_email	string	The email id of the request author.
customer_id	number	The ID of the customer associated with the request
assignee	object	The id of the request assignee. Details about the object can be found here.
assigned_team	object	The assigned team for this request, if any. This field will be null if no team is assigned. For more details, see here.
tickets	array	An array of ticket objects linked to the request. Details about the object can be found here.
csat_survey	object	An object containing information related to the csat_survey response of the request. Details about the object can be found here.
channel	object	An object containing channel information where the request was sent. Details about the object can be found here.
collection	object	An object containing collection information to which the above channel belongs where the request was sent. Details about the object can be found here.
custom_field_values	object	An object containing custom field values The object will have custom field ids as keys and the values of the custom fields as values of the object. Note: Values will be ids in case of select and multi_select type custom fields.
ai_field_values	object	An Object that denotes the values of the fields (i.e - Auto-Category, Auto-Emotion and Auto-CSAT) of a Request auto populated by AI Category : A List of values to categorize the type of request, it is auto updated every time the request is updated with a Public Comment Sentiment : Customer Satisfaction as analyzed by the AI, It is updated when the request is updated by the Customer Emotion : Detected sentiment of a Customer based on the Overall discussions in the request Ex :- "ai_field_values": { "category": [ "problem_report", "bug" ], "sentiment": "neutral", "emotion": "negative" }
request_thread	object	An object containing information related to the thread corresponding to the request. Details about the object can be found here.
triage_thread	object	An object containing information related to the triage thread corresponding to the request. Details about the object can be found here.
sla_metrics	object	An object containing SLA metrics information Details about the object can be found here.
created_at	string	The creation timestamp of the request
updated_at	string	The update timestamp of the request
last_message_time	string	Timestamp of when customer was last active

Assignee Object

Assignee of the request is represented as a JSON object with the following property

Name	Type	Description
id	string	Slack/MS Teams User ID of the assignee for the request

Assigned Team Object

The assigned team for a request is represented as a JSON object with the following property:

Name	Type	Description
id	number	The numeric ID of the assigned team for the request

Ticket Object

Tickets are represented as JSON objects with the following properties

Name	Type	Description
id	integer	The ID of the ticket
type	string	Type of the ticket Allowed values : zendesk, jira, jsm, salesforce, freshdesk, hubspot, clearfeed, github, intercom, linear
key	string	The key used for the ticket id.
url	string	The url of the ticket.
created_at	string	The creation timestamp of the ticket
form_id	integer	The ID of the form used to create this ticket, if one was used. Use the Get Ticket Form endpoint to retrieve full form details.

CSAT Survey Response Object

CSAT survey responses are represented as JSON objects with the following properties

Name	Type	Description
status	string	Status of the csat_survey. Allowed values: pending, received
response	object	This object will only be present if the status of the csat survey is received
survey_type	string	Type of the the cast survey. Allowed Values: five_point_rating
value	number	Points given in the CSAT survey response.
max_value	number	Maximum possible value of the response.

Thread Object

Thread are represented as JSON objects with the following properties

Name	Type	Description
channel_id	string	id of the channel where the thread exists.
thread_ts	string	id of the thread
team_id	string	team_id of the workspace where channel containing this thread exists.
url	string	URL of the thread

SLA Metrics Object

SLA Metrics are represented as JSON objects with the following properties

Name	Type	Description
resolution_time	object	This field will hold null if the request is currently not in solved or closed state.
first_response_time	object	This field will hold null if currently, the request hasn't had a first response in some way or the other.
first_resolution_time	object	This field will hold null if the request has not been marked as solved at least once.

Collection Object

The collection of a request is represented as a JSON object with the following properties:

Name	Type	Description
id	string	Id of the collection
name	string	name of the collection

Channel Object

Channel of a request is represented as JSON object with the following properties:

Name	Type	Description
id	string	Id of the channel
name	string	name of the channel
owner	string	id of the channel owner

Message Object

The message of a request is represented as a JSON object with the following properties. It is included in the API when the include query parameter is passed with the value messages.

Name	Type	Description
text	string	Text content of the message
author	string	Author of the message
ts	string	Id of the message
thread_ts	string	Id of the thread where the message was sent
is_responder	boolean	Indicates whether the message was sent by a responder.

Create Request

POST https://api.clearfeed.app/v1/rest/requests

Create a new request in ClearFeed.

Request Body

Name	Type	Description
description*	string	The description of the request in HTML format. Max Length: 4000 characters.
title	string	(Optional) The title of the request as plain text. If omitted, a title will be generated using AI. Max Length: 300 characters.
requester_email	string	(Optional) The email of the requester. If omitted, the request will be created on behalf of the user associated with the provided token.
priority	string	(Optional) The priority of the request. If omitted, a priority will be generated using AI. Allowed values: low, normal, high, urgent.
attachments	file	(Optional) A list of file attachments. Each file must not exceed 100MB in size, and a maximum of 5 files can be uploaded.

Example cURL Request

curl --location 'https://api.clearfeed.app/v1/rest/requests' \
--form 'description="<p>Hi there\!</p>"' \
--form 'title="REQUEST FROM API"' \
--form 'requester_email="[email protected]"' \
--form 'priority="high"' \
--form 'attachments=@path/to/file1' \
--form 'attachments=@path/to/file2'

Response

Name	Type	Description
request	object	Contains the request details
id	string	The ID of the newly created request

Example Response

{
  "request": {
    "id": "12345"
  }
}

Notes

• Description must be provided in HTML format and should not exceed 4000 characters.

• Title and Priority are optional. If not provided, AI will generate them.

• If requester_email is not provided, the request will be created on behalf of the authenticated user.

• Attachments must adhere to the following constraints:

  • Maximum file size per attachment: 100MB.

  • Maximum number of files: 5.

Add Message to an Existing Request

POST https://api.clearfeed.app/v1/rest/requests/:id/message

Post a reply message to an existing request. This endpoint allows you to send messages to request threads, either as a bot or as yourself.

Path Parameters

Name	Type	Description
id*	Number	Request Id

Request Body

Name	Type	Description
html_body	string	The message content in HTML/string format. Posts the Message as the Actual User
thread_ts	string	Thread timestamp for posting the message to a specific thread.
is_private	boolean	If true, posts the message as a private internal note that is only visible to members of your support team and others with access to the triage channel or ClearFeed web app; it is not shown to the requester or other external users. Defaults to false.
post_as_bot	boolean	If true, posts the message as a bot with the Users creds (i.e - ClearFeed Logo visible on User Profile). Defaults to false
attachments	file	A list of file attachments. Each file must not exceed 100MB in size, and a maximum of 5 files can be uploaded.

NOTE : We cannot post an Empty Message, either the html_body or atleast one attachments is required

Example cURL Request

curl --location 'https://api.clearfeed.app/v1/rest/requests/123/message' \
--form 'html_body="Thank you for your request. We are looking into this issue."' \
--form 'is_private="false"' \
--form 'post_as_bot="true"' \
--form 'attachments=@path/to/file1'

Response

Returns 201 on Successfully posting the Message.

NOTES

• Data to the Endpoint needs to be sent via form-data from Request Body and not as Query/URL Parameters

• html_body should be provided in HTML/string format and must have at least 1 character if specified.

• Attachments must adhere to the following constraints:

  • Maximum file size per attachment: 100MB.

  • Maximum number of files: 5.

Get Requests

GET https://api.clearfeed.app/v1/rest/requests

Get all requests in an account

Query Parameters

Name	Type	Description
collection_id	Number	Use the collection_id parameter to filter requests for a specific collection. Provide the collection's unique identifier to narrow down the results to that collection's requests.
sort_order	String	The sort_order parameter lets you set the result sorting order. Use 'asc' for ascending and 'desc' for descending. By default, results are sorted in 'desc' order, arranging them from newest to oldest based on creation time.
next_cursor	String	Utilize the next_cursor parameter to access the next batch of results when paginating. This field will be present under response_metadata in the previous API response.
limit	Number	Specify the number of results per response (1-100), defaulting to 50.
filter_by	String	Specify which field to use for sorting and filtering. Allowed values: created_at, updated_at. Defaults to created_at if not specified. When set to updated_at, requests are sorted and paginated by their last updated time.
after	ISO Date	Employ the after parameter to fetch entities created after the provided ISO8601 date. The default value is None.
before	ISO Date	Use the before parameter to retrieve entities created before the provided ISO8601 date. The default value is None.
include	String	Must be set to the exact value messages to include the list of associated messages (messages array) within the response object.
state	String	Fetches Request's based on their State (open, on_hold, in_progress, solved, pending, closed, none)
channel_id	String	Fetch all requests created in a specific Request Channel, using the channel_id (ex :- CABC1234)
author_emails	String	Fetch all Requests created by an User via their email (ex :- [email protected])

IMPORTANT POINTS : 1) When using filter_by = updated_at, due to the dynamic nature of updated records, paginating through API responses may occasionally lead to repeated or missing entries if changes occur between requests. For consistent pagination results, consider using filter_by=created_at (default behavior).

2) To fetch conversations that were marked as "not a request" or were never converted into requests, use state = none query parameter. Refer to the not_a_request_state field description in request object definition. i) When state = none is included in the GET call, then not_a_request_state will always return null in the Response Object ii) When state = none is not included in the GET call, then not_a_request_state can return any of the 3 values (i.e - temporary, permanent and null)

3) If you want to search for requests in multiple states, you need to add the state parameter once for each state in the URL. ex :- To get all requests that are in OPEN and PENDING state Request URL : https://api.clearfeed.app/v1/rest/requests?state=open&state=pending

200

{
  "requests": [
    {
      "id": 1,
      "title": "Can you check this out?",
      "state": "open",
      "priority": "normal",
      "author": "UXYZ123",
      "customer_id": 456,
      "assignee": {
        "id": "UABC123"
      },
      "assigned_team": {
        "id": 1
      },
      "tickets": [
        {
          "id": "12345",
          "type": "jira",
          "key": "CLRF-2",
          "created_at": "2023-01-01T00:00:00.000Z",
          "url": "https://clearfeed.atlassian.net/browse/CLRF-2",
          "form_id": 789
        }
      ],
      "csat_survey": {},
      "channel": {
        "id": "CABC1234",
        "name": "ClearFeed-Nexova",
        "owner": "UABC1234"
      },
      "collection": {
        "id": 1,
        "name": "enterprise-customers"
      },
      "custom_field_values": {},
      "request_thread": {
        "channel_id": "CABC1234",
        "thread_ts": "1692781448.777319",
        "team_id": "T024NBB217Z",
        "url": "https://clearfeed.slack.com/archives/CABC1234/p1692781448777319?thread_ts=1692781448.777319"
      },
      "triage_thread": {
        "channel_id": "CTRIAG1235",
        "thread_ts": "1692781449.545479",
        "team_id": "T024NBB217Z",
        "url": "https://clearfeed.slack.com/archives/CTRIAG1235/p1692781449545479?thread_ts=1692781449.545479"
      },
      "sla_metrics": {
        "resolution_time": null,
        "first_response_time": null,
        "first_resolution_time": null
      },
      "messages": [
        {
          "text": "I need some help with this issue.",
          "author": "UABC1234",
          "ts": "1670011050.128179",
          "thread_ts": null,
          "is_responder": true
        }
      ],
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z"
    }
  ],
  "response_metadata": {
    "next_cursor": "NjM4OQ==",
    "count": "number"
  }
}

Get Request by ID

GET https://api.clearfeed.app/v1/rest/requests/:id

Path Parameters

Name	Type	Description
id*	Number	Request Id

Query Parameters

Name	Type	Description
include	string	(Optional) Must be set to the exact value messages to include the list of associated messages (messages array) within the response object.

200 OK (Without Messages)

{
  "request": {
    "id": 1,
    "title": "Can you check this out?",
    "state": "open",
    "priority": "normal",
    "author": "UXYZ123",
    "customer_id": 456,
    "assignee": {
      "id": "UABC123"
    },
    "assigned_team": {
      "id": 1
    },
    "tickets": [
      {
        "id": "12345",
        "type": "jira",
        "key": "CLRF-2",
        "created_at": "2023-01-01T00:00:00.000Z",
        "url": "https://clearfeed.atlassian.net/browse/CLRF-2",
        "form_id": 789
      }
    ],
    "csat_survey": {},
    "channel": {
      "id": "CABC1234",
      "name": "ClearFeed-Nexova",
      "owner": "UABC1234"
    },
    "collection": {
      "id": 1,
      "name": "enterprise-customers"
    },
    "custom_field_values": {},
    "request_thread": {
      "channel_id": "CABC1234",
      "thread_ts": "1692781448.777319",
      "team_id": "T024NBB217Z",
      "url": "https://clearfeed.slack.com/archives/CABC1234/p1692781448777319?thread_ts=1692781448.777319"
    },
    "triage_thread": {
      "channel_id": "CTRIAG1235",
      "thread_ts": "1692781449.545479",
      "team_id": "T024NBB217Z",
      "url": "https://clearfeed.slack.com/archives/CTRIAG1235/p1692781449545479?thread_ts=1692781449.545479"
    },
    "sla_metrics": {
      "resolution_time": null,
      "first_response_time": null,
      "first_resolution_time": null
    },
    "created_at": "2023-01-01T00:00:00.000Z",
    "updated_at": "2023-01-01T00:00:00.000Z"
  }
}

200 OK (With Messages)

404: Not Found Request Not Found

Update Request

PATCH https://api.clearfeed.app/v1/rest/requests/:id

Updates an existing request. Only the specified fields in the request body will be updated.

Path Parameters

Name	Type	Required	Description
id*	Number	Yes	Request Id

Request Body

All fields are optional; however, at least one must be provided. If no fields are supplied or if all are empty or invalid, the request will fail with a 400 Bad Request error.

Name	Type	Description
state	String	(Optional) New state of the request. Allowed values : open, in_progress, pending, on_hold, solved, closed If you attempt to set the state to on_hold but your account disallows it, you will get a 400 Bad Request. If the existing state is closed, you cannot change it (406 Not Acceptable).
assignee	String	(Optional) User ID of the new assignee.
title	String	(Optional) New title for the request, with a minimum length of 1 character and a maximum of 300 characters.
priority	String	(Optional) New priority for the request. Allowed values : low, normal, high, urgent
custom_field_values	Object	(Optional) Map of custom field ID → new value. Setting a value to null deletes the entry. Any invalid field IDs or invalid value formats cause a 400 Bad Request. Refer Custom Field Value Format Guide for more details.

Example Request Body

{
  "state": "on_hold",
  "assignee": "UABC123",
  "title": "Updated request title",
  "priority": "high",
  "custom_field_values": {
    "1": "some_value",
    "2": null
  }
}

Custom Field Value Format Guide

The table below outlines the expected value formats when updating custom fields via the custom_field_values object. Each field type requires a specific format to ensure successful updates.

Custom Field Type	Expected Value Format	Example Value
Single Select	String (Option id)	"1"
Multi Select	Array of strings (option IDs)	["1", "2"]
Text	String	"Customer request details"
Date	ISO 8601 date string	"2024-02-24" (ISO 8601 Format)
Number	Number (integer or float)	42, 99.99
User Type	String (user ID)	"user_12345"

200: OK

400: Bad Request

404: Not Found

406: Not Acceptable

Bulk Import Requests

POST https://api.clearfeed.app/v1/rest/requests/batch

Import up to 50 historical requests in a single API call. Each request is created with its full message history, requester, optional assignee, state, and priority. Requests are created in ClearFeed's API collection.

This endpoint is designed for migrating requests from external systems into ClearFeed. All timestamps are historical — messages and requests are stored with their original creation times.

Request Body

The body must be a JSON object with a single requests array.

Name	Type	Description
requests*	array	Array of request objects to import. Min: 1, Max: 50 items. Items with the same external_id within a single call are rejected (must be unique).

Request Item Object

Each element of the requests array is a request item with the following fields:

Name	Type	Description
requester*	object	The user who created the request. See User Reference Object.
messages*	array	Array of message objects. Min: 1, Max: 500 messages. The first message (messages[0]) is treated as the original request message. Subsequent messages are reply messages, and must not have a created_at earlier than messages[0].created_at.
title*	string	Title of the request as plain text. Max length: 300 characters.
state	string	(Optional) State of the request. Allowed values: open, in_progress, pending, on_hold, solved, closed. Defaults to in_progress.
priority	string	(Optional) Priority of the request. Allowed values: low, normal, high, urgent. Defaults to normal.
assignee	object	(Optional) The support agent assigned to the request. Must be a workspace member (Slack user or email). Set to null to explicitly leave unassigned. See Member Reference Object.
solved_at	string	(Optional) ISO 8601 timestamp of when the request was resolved. Only valid when state is solved or closed. Must be >= messages[0].created_at. When omitted for solved/closed requests, the last message timestamp is used for resolution-time metrics.
external_id	string	(Optional) Your system's unique identifier for this request. Used for deduplication — if a request with this external_id was previously imported for the same account, the item is returned as duplicate instead of being re-created. Deduplication is maintained for 2 weeks after import.
custom_field_values	object	(Optional) Map of custom field ID → value to set on the request at creation time. Custom fields must be pre-created before import (see Custom Fields). Setting a value to null is a no-op for new requests. Any invalid field IDs or value formats cause the item to be marked as failed. See Custom Field Value Format Guide for expected value formats per field type.

User Reference Object

Identifies a user by one or more primary identifiers. At least one of slack_user_id, email, or external_id must be provided. If multiple are provided, resolution follows priority: slack_user_id → email → external_id.

Name	Type	Description
slack_user_id	string	The Slack user ID of the user (e.g. UABC123). Takes precedence over email and external_id when present.
email	string	Email address of the user. Required when neither slack_user_id nor external_id is provided.
external_id	string	Your system's opaque identifier for the user. Used when neither slack_user_id nor email is available. Creates a ClearFeed-internal user profile.
name	string	(Optional) Display name for the user. Used when creating a new user profile.

Member Reference Object

Identifies a support team member (for the assignee field). Assignees must be workspace members — external_id is not supported.

Name	Type	Description
slack_user_id	string	The Slack user ID of the member. Takes precedence over email when present.
email	string	Email address of the member. Required when slack_user_id is absent.
name	string	(Optional) Display name for the member.

Message Object (Bulk Import)

Name	Type	Description
created_at*	string	ISO 8601 timestamp of when the message was sent. Cannot be in the future. For reply messages, must be >= messages[0].created_at.
text	string	Plain-text content of the message. Required when html_body is absent. Max length: 4000 characters.
html_body	string	HTML content of the message. Required when text is absent. Converted to plain text for storage. Max length: 4000 characters.
author*	object	Author of this message. See User Reference Object.
is_responder	boolean	(Optional) Whether this message was sent by a support responder. When omitted, ClearFeed determines responder status from the collection's responder configuration. The requester's messages are always treated as non-responder regardless of this flag.
is_private	boolean	(Optional) Whether the message is private (internal note). Defaults to false.

Example Request Body

{
  "requests": [
    {
      "external_id": "TICKET-001",
      "title": "Cannot log in to the dashboard",
      "state": "solved",
      "priority": "high",
      "solved_at": "2024-01-15T10:30:00.000Z",
      "requester": {
        "email": "[email protected]",
        "name": "Alice"
      },
      "assignee": {
        "slack_user_id": "UABC123"
      },
      "custom_field_values": {
        "1": "2",
        "2": 42
      },
      "messages": [
        {
          "text": "I cannot log in to the dashboard since this morning.",
          "author": {
            "email": "[email protected]"
          },
          "created_at": "2024-01-15T09:00:00.000Z"
        },
        {
          "text": "We are investigating the issue.",
          "author": {
            "slack_user_id": "UABC123"
          },
          "is_responder": true,
          "created_at": "2024-01-15T09:15:00.000Z"
        },
        {
          "text": "The issue has been resolved. Please try again.",
          "author": {
            "slack_user_id": "UABC123"
          },
          "is_responder": true,
          "created_at": "2024-01-15T10:30:00.000Z"
        }
      ]
    }
  ]
}

Response

The response always contains a results array (one entry per input item, in order) and a summary object.

Response Summary Object

Name	Type	Description
total	number	Total number of items submitted.
created	number	Number of requests successfully created.
duplicate	number	Number of items skipped due to deduplication.
failed	number	Number of items that failed to import.

Response Result Item

Each item in results corresponds to the input item at the same index.

Name	Type	Description
index	number	Zero-based position of this item in the input requests array.
status	string	created — request was successfully imported. duplicate — skipped because a request with this external_id was already imported. failed — import failed.
id	number	The ClearFeed request ID. Present when status is created or duplicate.
reason	string	Human-readable error message. Present only when status is failed.

HTTP Status Codes

Status	Meaning
201	All items were successfully created.
207	Partial success — some items were created or deduplicated, but at least one failed.
422	All items failed to import.
400	Request body validation failed (e.g. missing required fields, constraint violations).

201: All Created

{
  "results": [
    { "index": 0, "status": "created", "id": 1042 },
    { "index": 1, "status": "created", "id": 1043 }
  ],
  "summary": {
    "total": 2,
    "created": 2,
    "duplicate": 0,
    "failed": 0
  }
}

207: Partial Success

422: All Failed

400: Validation Error

Notes

• Content-Type: The request body must be sent as application/json.

• Ordering: Items are processed sequentially in the order provided. The index field in each result maps back to the zero-based position in the input array.

• Deduplication: Provide external_id on each request item to enable idempotent imports. Re-submitting the same external_id within 2 weeks returns duplicate without creating a second request.

• User resolution: Users are looked up in order of priority: slack_user_id → email → external_id. If a Slack user ID is not found in the workspace, ClearFeed falls back to email if provided, then external_id.

• Assignees: must be resolvable workspace members (via slack_user_id or email). Assignees identified only by external_id are silently ignored. If the provided slack_user_id or email cannot be resolved to a workspace member, the assignee is silently ignored and the request is created unassigned.

• Responder detection: When is_responder is omitted on a message, ClearFeed uses the collection's responder configuration to classify the author. The requester is always treated as a non-responder.

• Private messages: Setting is_private: true on a reply message always stores it as a responder message (is_responder = true), regardless of any explicit is_responder: false on the same message.

• State defaults: When state is omitted, requests are created with state in_progress.

• solved_at: Only applicable when state is solved or closed. Must not be in the future and must be >= messages[0].created_at.