> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telemetron.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Ticket

> Create a new support ticket

## Overview

Creates a new support ticket in Telemetron.

**Behavior:**

* Requires either `customerEmail` or `customerId` to associate the ticket with a customer
* If `customerEmail` is provided and no matching customer exists, a new customer is created automatically
* Tickets are automatically categorized and routed based on your organization's rules

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your organization's API key
</ParamField>

## Request Body

<ParamField body="title" type="string" required>
  Ticket title (max 255 characters)
</ParamField>

<ParamField body="description" type="string">
  Detailed description of the issue or request
</ParamField>

<ParamField body="priority" type="string" default="medium">
  Ticket priority. One of: `low`, `medium`, `high`, `urgent`
</ParamField>

<ParamField body="customerEmail" type="string">
  Customer's email address. If the customer doesn't exist, one will be created automatically. Either `customerEmail` or `customerId` is required.
</ParamField>

<ParamField body="customerId" type="string">
  Existing Telemetron customer ID. Use this if you already have the customer's ID from a previous API call. Either `customerEmail` or `customerId` is required.
</ParamField>

<ParamField body="category" type="string">
  Category name for ticket routing. Must match an existing category in your organization. If not provided or not matched, the ticket will be categorized automatically by AI.
</ParamField>

<ParamField body="messages" type="array">
  Conversation history to include with the ticket. Each message has a `role` (`customer`, `agent`, or `bot`) and `content` string. If no `description` is provided, messages are used to generate the ticket description automatically. The first customer message is also included in Slack notifications.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the operation was successful
</ResponseField>

<ResponseField name="ticketId" type="string">
  The unique identifier for the created ticket
</ResponseField>

<ResponseField name="message" type="string">
  Description of the operation result
</ResponseField>

## Examples

### Create Ticket with Customer Email

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/ticket/createTicket \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Device not connecting to WiFi",
      "description": "Customer reports their device fails to connect after firmware update v2.3.1",
      "priority": "high",
      "customerEmail": "john.doe@example.com",
      "category": "Connectivity"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/ticket/createTicket', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Device not connecting to WiFi',
      description: 'Customer reports their device fails to connect after firmware update v2.3.1',
      priority: 'high',
      customerEmail: 'john.doe@example.com',
      category: 'Connectivity'
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/ticket/createTicket',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'title': 'Device not connecting to WiFi',
          'description': 'Customer reports their device fails to connect after firmware update v2.3.1',
          'priority': 'high',
          'customerEmail': 'john.doe@example.com',
          'category': 'Connectivity'
      }
  )

  data = response.json()
  ```
</CodeGroup>

### Create Ticket with Customer ID

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/ticket/createTicket \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Battery draining too fast",
      "customerId": "cust_a1b2c3d4e5f6",
      "priority": "medium"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/ticket/createTicket', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Battery draining too fast',
      customerId: 'cust_a1b2c3d4e5f6',
      priority: 'medium'
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/ticket/createTicket',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'title': 'Battery draining too fast',
          'customerId': 'cust_a1b2c3d4e5f6',
          'priority': 'medium'
      }
  )

  data = response.json()
  ```
</CodeGroup>

### Create Ticket with Messages

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/ticket/createTicket \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Device overheating during charging",
      "customerEmail": "john.doe@example.com",
      "priority": "high",
      "messages": [
        { "role": "customer", "content": "My device gets very hot when I plug it in to charge." },
        { "role": "bot", "content": "I'\''m sorry to hear that. How long has this been happening?" },
        { "role": "customer", "content": "Started about a week ago after the latest update." }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/ticket/createTicket', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Device overheating during charging',
      customerEmail: 'john.doe@example.com',
      priority: 'high',
      messages: [
        { role: 'customer', content: 'My device gets very hot when I plug it in to charge.' },
        { role: 'bot', content: "I'm sorry to hear that. How long has this been happening?" },
        { role: 'customer', content: 'Started about a week ago after the latest update.' }
      ]
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/ticket/createTicket',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'title': 'Device overheating during charging',
          'customerEmail': 'john.doe@example.com',
          'priority': 'high',
          'messages': [
              {'role': 'customer', 'content': 'My device gets very hot when I plug it in to charge.'},
              {'role': 'bot', 'content': "I'm sorry to hear that. How long has this been happening?"},
              {'role': 'customer', 'content': 'Started about a week ago after the latest update.'}
          ]
      }
  )

  data = response.json()
  ```
</CodeGroup>

### Response

<CodeGroup>
  ```json Success theme={null}
  {
    "success": true,
    "ticketId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Ticket created successfully"
  }
  ```

  ```json Error - Missing Title theme={null}
  {
    "error": "title is required"
  }
  ```

  ```json Error - Missing Customer theme={null}
  {
    "error": "Either customerEmail or customerId is required"
  }
  ```

  ```json Error - Customer Not Found theme={null}
  {
    "error": "Customer not found"
  }
  ```

  ```json Error - Invalid Priority theme={null}
  {
    "error": "priority must be one of: low, medium, high, urgent"
  }
  ```
</CodeGroup>

<RequestExample>
  ```bash cURL - Create with Email theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/ticket/createTicket \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Device not connecting to WiFi",
      "description": "Customer reports their device fails to connect after firmware update v2.3.1",
      "priority": "high",
      "customerEmail": "john.doe@example.com",
      "category": "Connectivity"
    }'
  ```

  ```bash cURL - Create with Customer ID theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/ticket/createTicket \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Battery draining too fast",
      "customerId": "cust_a1b2c3d4e5f6",
      "priority": "medium"
    }'
  ```

  ```javascript JavaScript - Create with Email theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/ticket/createTicket', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Device not connecting to WiFi',
      description: 'Customer reports their device fails to connect after firmware update v2.3.1',
      priority: 'high',
      customerEmail: 'john.doe@example.com',
      category: 'Connectivity'
    })
  });

  const data = await response.json();
  ```

  ```javascript JavaScript - Create with Customer ID theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/ticket/createTicket', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Battery draining too fast',
      customerId: 'cust_a1b2c3d4e5f6',
      priority: 'medium'
    })
  });

  const data = await response.json();
  ```

  ```python Python - Create with Email theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/ticket/createTicket',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'title': 'Device not connecting to WiFi',
          'description': 'Customer reports their device fails to connect after firmware update v2.3.1',
          'priority': 'high',
          'customerEmail': 'john.doe@example.com',
          'category': 'Connectivity'
      }
  )

  data = response.json()
  ```

  ```python Python - Create with Customer ID theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/ticket/createTicket',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'title': 'Battery draining too fast',
          'customerId': 'cust_a1b2c3d4e5f6',
          'priority': 'medium'
      }
  )

  data = response.json()
  ```

  ```bash cURL - Create with Messages theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/ticket/createTicket \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Device overheating during charging",
      "customerEmail": "john.doe@example.com",
      "priority": "high",
      "messages": [
        { "role": "customer", "content": "My device gets very hot when I plug it in to charge." },
        { "role": "bot", "content": "I'\''m sorry to hear that. How long has this been happening?" },
        { "role": "customer", "content": "Started about a week ago after the latest update." }
      ]
    }'
  ```

  ```javascript JavaScript - Create with Messages theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/ticket/createTicket', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Device overheating during charging',
      customerEmail: 'john.doe@example.com',
      priority: 'high',
      messages: [
        { role: 'customer', content: 'My device gets very hot when I plug it in to charge.' },
        { role: 'bot', content: "I'm sorry to hear that. How long has this been happening?" },
        { role: 'customer', content: 'Started about a week ago after the latest update.' }
      ]
    })
  });

  const data = await response.json();
  ```

  ```python Python - Create with Messages theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/ticket/createTicket',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'title': 'Device overheating during charging',
          'customerEmail': 'john.doe@example.com',
          'priority': 'high',
          'messages': [
              {'role': 'customer', 'content': 'My device gets very hot when I plug it in to charge.'},
              {'role': 'bot', 'content': "I'm sorry to hear that. How long has this been happening?"},
              {'role': 'customer', 'content': 'Started about a week ago after the latest update.'}
          ]
      }
  )

  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "ticketId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Ticket created successfully"
  }
  ```

  ```json Error - Missing Title theme={null}
  {
    "error": "title is required"
  }
  ```

  ```json Error - Missing Customer theme={null}
  {
    "error": "Either customerEmail or customerId is required"
  }
  ```

  ```json Error - Customer Not Found theme={null}
  {
    "error": "Customer not found"
  }
  ```

  ```json Error - Invalid Priority theme={null}
  {
    "error": "priority must be one of: low, medium, high, urgent"
  }
  ```
</ResponseExample>

## Status Codes

| Code | Description                                                                          |
| ---- | ------------------------------------------------------------------------------------ |
| 200  | Ticket created successfully                                                          |
| 400  | Invalid request (missing required fields, invalid JSON payload, or invalid priority) |
| 401  | Invalid or missing API key                                                           |
| 404  | Customer not found (when using customerId)                                           |
| 500  | Internal server error                                                                |