> 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

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.

{% 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**.