API

Learn how to create ClearFeed tickets programmatically using the API

ClearFeed provides REST API endpoints to create and manage tickets programmatically. This allows you to integrate ClearFeed ticketing into your existing tools, workflows, and automation systems.

ClearFeed Tickets Only: This method is only available for ClearFeed's native ticketing system. For external ticketing systems (Zendesk, Jira, etc.), use their native APIs or refer to integration-specific documentation.

When to Use the API

Use the ClearFeed API to create tickets when:

• Integrating with internal tools - Connect your custom applications to ClearFeed

• Automating ticket creation - Create tickets from monitoring systems, webhooks, or scheduled jobs

• Bulk operations - Create or update multiple tickets programmatically

• Custom workflows - Build custom ticketing flows for your specific needs

• Third-party integrations - Connect services that don't have native ClearFeed integration

Setup API Collection

Before using the API, you need to create an API Collection to manage API-based tickets.

Step 1: Create API Collection

1. Go to Collections → Click Add New Collection

2. Select API Collection

3. Configure the Collection settings:

   • Name - Give your API Collection a descriptive name

   • Add Responders - Select users who will respond to these tickets

   • Select Request Channel - Choose the Slack channel where API tickets will be posted

     • For private channels, follow the channel management guide

   • (Optional) Associate Triage Channel - Link or create a triage channel for team visibility

     • Learn more: Triage Channel Setup

4. Enable Workflows (Optional) - Set up alerts for unattended tickets

   • Learn more: Workflows Guide

Step 2: Get API Credentials

1. Navigate to Settings → Developer Settings

2. Generate or copy your Personal Access Token

3. Use a Read & Write token for ticket creation and other API calls that modify ClearFeed data. Store the token securely. Learn More: Developer Settings

Creating Tickets via API

API Endpoint

Use the Create Request API endpoint to create new tickets:

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

API Documentation: Create Request API Reference

Request Format

Headers:

Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN
Content-Type: application/json

Body:

{
  "collection_id": "col_abc123",
  "title": "API ticket title",
  "description": "Detailed description of the issue",
  "priority": "high",
  "requester_email": "[e-mail]",
  "custom_fields": {
    "environment": "production",
    "severity": "critical"
  }
}

Required Fields:

• collection_id - The ID of your API Collection

• title - Ticket title/subject

• description - Detailed description of the issue

Optional Fields:

• priority - Ticket priority (low, medium, high, urgent)

• requester_email - Email of the person requesting support

• assignee_id - User ID to assign the ticket to

• custom_fields - Additional metadata as key-value pairs

• tags - Array of tags for categorization

Example: Create Ticket with cURL

curl -X POST https://api.clearfeed.app/v1/rest/requests \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "col_abc123",
    "title": "Production API Error - 500 responses",
    "description": "Users are experiencing 500 errors when accessing the /api/orders endpoint. Started approximately 30 minutes ago.",
    "priority": "urgent",
    "requester_email": "[e-mail]",
    "custom_fields": {
      "environment": "production",
      "service": "orders-api",
      "error_rate": "25%"
    }
  }'

Example: Create Ticket with Python

import requests

url = "https://api.clearfeed.app/v1/rest/requests"
headers = {
    "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "collection_id": "col_abc123",
    "title": "Production API Error - 500 responses",
    "description": "Users are experiencing 500 errors when accessing the /api/orders endpoint.",
    "priority": "urgent",
    "requester_email": "[e-mail]",
    "custom_fields": {
        "environment": "production",
        "service": "orders-api",
        "error_rate": "25%"
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Response

Successful ticket creation returns:

{
  "id": "req_xyz789",
  "ticket_id": "CF-12345",
  "collection_id": "col_abc123",
  "title": "Production API Error - 500 responses",
  "status": "open",
  "priority": "urgent",
  "created_at": "2025-01-15T10:30:00Z",
  "slack_thread_url": "https://yourworkspace.slack.com/archives/C123/p1234567890"
}

What Happens After Creating a Ticket

Once you create a ticket via API:

1. Ticket is posted to Slack - A message appears in the configured Request Channel

2. Team notification - Responders receive Slack notifications

3. Ticket ID assigned - A unique ClearFeed ticket ID is generated (e.g., CF-12345)

4. Tracking begins - The ticket is tracked in the ClearFeed system

5. Team can respond - Responders reply in the Slack thread to manage the ticket

Email Communication for API Tickets

API-created tickets support full email communication with the requester, enabling bidirectional email exchanges alongside Slack and WebApp responses.

How Email Communication Works

When you create a ticket via API with a requester_email:

• Agent replies send emails - When agents respond to the ticket (via WebApp or Slack), the requester receives an email notification

• Email format - The email subject uses the format CF-<id> <title> and includes a Reply-To address that encodes the ticket ID

• Requester replies appear in ticket - When the requester replies to the email, their response is added as a new message in the ClearFeed ticket thread

• CC recipients visible - If CC recipients are included in the email thread, they appear in the triage DM CC field

• Subsequent agent replies - Additional agent responses continue to send emails to the requester, maintaining the email thread

Configuration

For email communication to work with API tickets:

• Requester email required - Include the requester_email field when creating the ticket via API

• Email integration configured - Email integration must be set up in your ClearFeed account

This email behavior matches the existing email communication for Portal and Email-origin tickets, ensuring consistent requester experience across all ticket sources.

Managing Tickets via API

Beyond creating tickets, the ClearFeed API supports:

• Update tickets - Modify status, priority, assignee

• Get ticket details - Retrieve ticket information

• Add comments - Post updates to tickets programmatically

• Search tickets - Query tickets by various criteria

• Close tickets - Mark tickets as resolved

Full API Documentation: ClearFeed API Reference

FAQs

1. How do I get my API credentials? Answer: Navigate to Settings → Developer Settings in the ClearFeed web app to generate your Personal Access Token. Use a read/read &write token for creating or updating tickets.

2. Is there a rate limit for API requests? Answer: Yes, API rate limits apply. Refer to the API Documentation for current rate limits and best practices.

3. Can I create tickets in multiple Collections using the same token? Answer: Yes, if your Personal Access Token has read/write access and your user has access to those Collections. Specify different collection_id values to create tickets in different Collections.

4. How do I specify who the ticket is assigned to? Answer: Include the assignee_id field in your API request with the user's ID. You can get user IDs from the ClearFeed API or web app

5. What happens if the API request fails? Answer: The API returns appropriate HTTP status codes and error messages. Implement error handling in your code to retry or log failures.

6. Can I update an existing ticket via API? Answer: Yes, use the Update Request endpoint. See API Documentation for details.

7. Are webhooks available to receive ticket updates? Answer: Yes, ClearFeed supports webhooks for ticket events. Configure them in Settings → Developer Settings → Events API Subscription.