> For the complete documentation index, see [llms.txt](https://docs.clearfeed.ai/clearfeed-help-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clearfeed.ai/clearfeed-help-center/how-it-works/creating-or-linking-tickets/api.md).

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

{% hint style="info" %}
**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](/clearfeed-help-center/integrations/task-and-ticketing-systems.md).
{% endhint %}

## 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](/clearfeed-help-center/sources/manage-request-channels.md)
   * **(Optional) Associate Triage Channel** - Link or create a triage channel for team visibility
     * Learn more: [Triage Channel Setup](/clearfeed-help-center/clearfeed-helpdesk/triage-channel-setup.md)
4. **Enable Workflows** (Optional) - Set up alerts for unattended tickets
   * Learn more: [Workflows Guide](/clearfeed-help-center/clearfeed-helpdesk/workflows.md)

### 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](/clearfeed-help-center/account-setup/developer-settings.md#token-scopes)

## 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](https://docs.clearfeed.ai/api/reference/api-reference/requests#create-request)

### Request Format

**Headers:**

```
Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN
Content-Type: application/json
```

**Body:**

```json
{
  "collection_id": "col_abc123",
  "title": "API ticket title",
  "description": "Detailed description of the issue",
  "priority": "high",
  "requester_email": "customer@example.com",
  "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

```bash
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": "ops@example.com",
    "custom_fields": {
      "environment": "production",
      "service": "orders-api",
      "error_rate": "25%"
    }
  }'
```

### Example: Create Ticket with Python

```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": "ops@example.com",
    "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:

```json
{
  "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](https://docs.clearfeed.ai/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](https://docs.clearfeed.ai/api/reference) 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](https://docs.clearfeed.ai/api/reference) 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**.