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
priority	string	The priority of the request. Allowed values : low, normal, high, urgent
author	object	An object containing details of the request author.
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.
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

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

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 Name Type Description 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.
Name	Type	Description
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.
Name	Type	Description
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. Name Type Description value number The time difference (in minutes) between when a request message was sent, and when it was resolved for the final time. is_breached boolean If SLA Config is set up for the account, this field will indicate whether the request has breached Resolution Time SLA. This field will be absent in case Resolution Time SLA Config is not setup.
Name	Type	Description
value	number	The time difference (in minutes) between when a request message was sent, and when it was resolved for the final time.
is_breached	boolean	If SLA Config is set up for the account, this field will indicate whether the request has breached Resolution Time SLA. This field will be absent in case Resolution Time SLA Config is not setup.
Name	Type	Description
value	number	The time difference (in minutes) between when a request message was sent, and when it was resolved for the final time.
is_breached	boolean	If SLA Config is set up for the account, this field will indicate whether the request has breached Resolution Time SLA. This field will be absent in case Resolution Time SLA Config is not setup.
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. Name Type Description value number The time difference (in minutes) between when the request message was sent, and when it received a first response. is_breached boolean If SLA Config is set up for the account, this field will indicate whether the request has breached the First Response Time SLA. This field will be absent in case First Response Time SLA config is not setup.
Name	Type	Description
value	number	The time difference (in minutes) between when the request message was sent, and when it received a first response.
is_breached	boolean	If SLA Config is set up for the account, this field will indicate whether the request has breached the First Response Time SLA. This field will be absent in case First Response Time SLA config is not setup.
Name	Type	Description
value	number	The time difference (in minutes) between when the request message was sent, and when it received a first response.
is_breached	boolean	If SLA Config is set up for the account, this field will indicate whether the request has breached the First Response Time SLA. This field will be absent in case First Response Time SLA config is not setup.
first_resolution_time	object	This field will hold null if the request has not been marked as solved at least once. Name Type Description value number The time difference (in minutes) between when a request message was sent, and when it was resolved for the first time.
Name	Type	Description
value	number	The time difference (in minutes) between when a request message was sent, and when it was resolved for the first time.
Name	Type	Description
value	number	The time difference (in minutes) between when a request message was sent, and when it was resolved for the first time.

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="[e-mail]"' \
--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.

Feature Availability

This API is not enabled for all users by default. To access this feature, contact support at [e-mail].

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.
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	'messages'
	Use include query parameter to include more data for each request.

200

{
  "requests": [
    {
      "id": 1,
      "title": "Can you check this out?",
      "state": "open",
      "priority": "normal",
      "author": "UXYZ123",
      "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"
        }
      ],
      "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",
    "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"
      }
    ],
    "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)

{
  "request": {
    "id": 255,
    "title": "I need help",
    "state": "pending",
    "priority": "normal",
    "author": "U02PKBD0RSB",
    "assignee": {
      "id": "U087T6WGBPB"
    },
    "assigned_team": null,
    "tickets": [
      {
        "id": "255",
        "type": "clearfeed",
        "key": "CF-255",
        "created_at": "2025-02-28T12:27:51.551Z",
        "url": "https://cf-john.slack.com/archives/C08BH222DGT/p1740745641520939"
      }
    ],
    "csat_survey": null,
    "channel": {
      "id": "C08BH222DGT",
      "name": "req8",
      "owner": "U087T6WGBPB"
    },
    "collection": {
      "id": 11,
      "name": "new8"
    },
    "custom_field_values": {},
    "request_thread": {
      "channel_id": "C08BH222DGT",
      "thread_ts": "1740745641.520939",
      "team_id": "T087GJ1FMN0",
      "url": "https://cf-john.slack.com/archives/C08BH222DGT/p1740745641520939"
    },
    "triage_thread": {
      "channel_id": "C08B2JGF163",
      "thread_ts": "1740745671.420209",
      "team_id": "T087GJ1FMN0",
      "url": "https://cf-john.slack.com/archives/C08B2JGF163/p1740745671420209"
    },
    "sla_metrics": {
      "first_response_time": {
        "value": 0,
        "is_breached": null
      },
      "resolution_time": null,
      "first_resolution_time": null
    },
    "created_at": "2025-02-28T12:27:21.520Z",
    "updated_at": "2025-02-28T12:55:00.346Z",
    "messages": [
      {
        "text": "hi i need help",
        "author": "U02PKBD0RSB",
        "ts": "1740745641.520939",
        "thread_ts": null,
        "is_responder": false
      },
      {
        "text": "okay",
        "author": "U087T6WGBPB",
        "ts": "1740745683.751609",
        "thread_ts": "1740745641.520939",
        "is_responder": true
      },
      {
        "text": "test",
        "author": "U087T6WGBPB",
        "ts": "1740747010.696119",
        "thread_ts": "1740745641.520939",
        "is_responder": true
      },
      {
        "text": "test again",
        "author": "U087T6WGBPB",
        "ts": "1740747300.346039",
        "thread_ts": "1740745641.520939",
        "is_responder": true
      }
    ]
  }
}

404: Not Found Request Not Found

// Occurs if no request exists with the specified id for the account

{
  "statusCode": 404,
  "message": "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