# Create a ticket

Creates a new ticket.

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| ticketCategoryId | string | Ticket category ID |
| title | string | Ticket title (min 2 characters) |
| author | object | Author/contact info (id, userId, email, name, profilePicture) |

### Optional Fields

| Field | Type | Description |
|-------|------|-------------|
| content | string | Ticket description (HTML) |
| customFields | object | Custom field values |
| companyId | string | Company to associate |
| linkedConversationId | string | Conversation to link |
| assigneeId | string | Admin to assign |
| statusId | string | Initial status |
| createdAt | string | ISO 8601 timestamp for backdating |
| skipNotifications | boolean | Skip sending notifications (default false) |

### File Custom Fields

File-type custom fields can be provided in two ways:

Method 1: Multipart upload — Send the request as multipart/form-data. Put the JSON body in a field named data, and attach files with field names like customFields.. For allowMultiple fields, send multiple files with the same field name.

Method 2: External URL — In the JSON body, set the file custom field value to { "url": "https://..." }. Optionally include "name" to set the filename (e.g. { "url": "https://...", "name": "report.pdf" }); if omitted, the filename is extracted from the download response. For allowMultiple fields, use an array: [{ "url": "..." }, ...]. The server downloads the file (max 10MB, HTTPS only) and stores it.

Both methods produce signed download URLs in the response.

Limits: Max 10 files per request, 400MB total upload size. Executable file types (.exe, .bat, .js, .sh, etc.) are blocked.

Response format: File custom field values in the response are JSON strings containing { "key": "...", "name": "...", "url": "https://signed-url..." }. For allowMultiple fields, an array of these objects. The url is a time-limited signed download URL (expires in 1 hour).

### Response

Returns the created ticket object with 201 Created status.

Endpoint: POST /v2/tickets
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Request fields (application/json):

  - `ticketCategoryId` (string, required)
    Example: "507f1f77bcf86cd799439011"

  - `title` (string, required)
    Example: "Cannot login to dashboard"

  - `content` (string)
    Example: "<p>I get a 403 error when logging in.</p>"

  - `author` (object, required)
    Author to attribute the post to. If not provided, uses the authenticated user. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email.

  - `author.id` (string)
    Featurebase user ID to attribute content to
    Example: "507f1f77bcf86cd799439011"

  - `author.userId` (string)
    External user ID from your system (matched via SSO)
    Example: "usr_12345"

  - `author.email` (string)
    Author email (used to find or create user)
    Example: "john@example.com"

  - `author.name` (string)
    Author display name
    Example: "John Doe"

  - `author.profilePicture` (string)
    Author profile picture URL
    Example: "https://example.com/avatar.png"

  - `customFields` (object)

  - `companyId` (string)
    Example: "507f1f77bcf86cd799439015"

  - `linkedConversationId` (string)
    Example: "507f1f77bcf86cd799439012"

  - `assigneeId` (string)
    Example: "507f1f77bcf86cd799439013"

  - `createdAt` (string,null)
    Example: "2025-01-15T10:30:00.000Z"

  - `skipNotifications` (boolean)

  - `statusId` (string)
    Example: "507f1f77bcf86cd799439016"

## Response 201 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "ticket"

  - `id` (string, required)
    Unique identifier (MongoDB ID)
    Example: "507f1f77bcf86cd799439011"

  - `ticketNumber` (number, required)
    Sequential display ID (e.g. TK-42)
    Example: 42

  - `title` (string, required)
    Ticket title
    Example: "Cannot login to dashboard"

  - `content` (string, required)
    Ticket content/description (HTML)
    Example: "<p>I get a 403 error when logging in.</p>"

  - `ticketCategoryId` (string, required)
    Ticket category ID
    Example: "507f1f77bcf86cd799439011"

  - `categoryType` (string, required)
    Ticket category type
    Enum: "customer", "tracker", "back-office"

  - `ticketUrl` (string, required)
    Full URL to view the ticket
    Example: "https://feedback.example.com/p/cannot-login"

  - `author` (object,null, required)
    Contact who created the ticket

  - `author.id` (string,null, required)
    Author unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `author.name` (string, required)
    Author display name
    Example: "John Doe"

  - `author.email` (string,null, required)
    Author email
    Example: "john@example.com"

  - `author.profilePicture` (string,null, required)
    Author profile picture URL
    Example: "https://cdn.example.com/avatars/john.png"

  - `author.type` (string, required)
    Type of user
    Enum: "admin", "customer", "guest", "integration", "bot", "lead"

  - `status` (object, required)
    Current ticket status

  - `status.id` (string, required)
    Unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `status.name` (string, required)
    Display name
    Example: "In Progress"

  - `status.color` (string, required)
    Color for UI display
    Example: "Blue"

  - `status.type` (string, required)
    The workflow stage this status represents
    Enum: "reviewing", "unstarted", "active", "completed", "canceled"

  - `status.isDefault` (boolean, required)
    Whether this is the default status for new posts

  - `customFields` (object, required)
    Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects.
    Example: {"priority":"high","507f1f77bcf86cd799439099":"{\"key\":\"org/pending/file.pdf\",\"name\":\"document.pdf\",\"url\":\"https://...\"}"}

  - `companyId` (string,null, required)
    Associated company ID
    Example: "507f1f77bcf86cd799439015"

  - `assigneeId` (string,null, required)
    Assigned admin ID
    Example: "507f1f77bcf86cd799439013"

  - `teamAssigneeId` (string,null, required)
    Assigned team ID (from linked conversation)
    Example: "507f1f77bcf86cd799439014"

  - `open` (boolean, required)
    Whether the ticket is open
    Example: true

  - `snoozedUntil` (string,null, required)
    ISO 8601 timestamp until snoozed (from linked conversation)
    Example: "2025-01-16T09:00:00.000Z"

  - `linkedConversations` (array, required)
    Linked conversations

  - `linkedConversations.id` (string, required)
    Conversation ID
    Example: "507f1f77bcf86cd799439011"

  - `linkedConversations.role` (string, required)
    Link role
    Enum: "customer", "tracker", "back-office"

  - `conversationParts` (array)
    Conversation message history. Only included when fetching a single ticket by ID.

  - `createdAt` (string, required)
    ISO 8601 creation timestamp
    Example: "2025-01-15T10:30:00.000Z"

  - `updatedAt` (string, required)
    ISO 8601 last updated timestamp
    Example: "2025-01-15T12:30:00.000Z"

  - `integrations` (object, required)
    Third-party integration links

  - `integrations.linear` (array, required)

  - `integrations.linear.issueId` (string, required)
    Linear issue ID
    Example: "LIN-123"

  - `integrations.linear.issueUrl` (string,null, required)
    URL to the Linear issue
    Example: "https://linear.app/team/issue/LIN-123"

  - `integrations.jira` (array, required)

  - `integrations.jira.issueId` (string, required)
    Jira issue ID
    Example: "PROJ-456"

  - `integrations.jira.issueUrl` (string,null, required)
    URL to the Jira issue
    Example: "https://company.atlassian.net/browse/PROJ-456"

  - `integrations.clickup` (array, required)

  - `integrations.clickup.id` (string, required)
    ClickUp task ID
    Example: "86a1b2c3d"

  - `integrations.clickup.url` (string, required)
    URL to the ClickUp task
    Example: "https://app.clickup.com/t/86a1b2c3d"

  - `integrations.clickup.title` (string, required)
    ClickUp task title
    Example: "Fix login bug"

  - `integrations.github` (array, required)

  - `integrations.github.id` (string, required)
    GitHub issue ID
    Example: "1234567890"

  - `integrations.github.number` (string, required)
    GitHub issue number
    Example: "42"

  - `integrations.github.repositoryName` (string, required)
    Repository name
    Example: "frontend"

  - `integrations.github.repositoryFullName` (string, required)
    Full repository name (owner/repo)
    Example: "acme/frontend"

  - `integrations.github.url` (string, required)
    URL to the GitHub issue
    Example: "https://github.com/acme/frontend/issues/42"

  - `integrations.github.title` (string, required)
    GitHub issue title
    Example: "Login page returns 403"

  - `integrations.devops` (array, required)

  - `integrations.devops.id` (number, required)
    Azure DevOps work item ID
    Example: 789

  - `integrations.devops.url` (string, required)
    URL to the work item
    Example: "https://dev.azure.com/org/project/_workitems/edit/789"

  - `integrations.devops.projectId` (string, required)
    Azure DevOps project ID
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `integrations.devops.projectName` (string, required)
    Azure DevOps project name
    Example: "My Project"

  - `integrations.devops.title` (string, required)
    Work item title
    Example: "Implement SSO"

  - `integrations.hubspot` (array, required)

  - `integrations.hubspot.objectId` (number, required)
    HubSpot object ID
    Example: 12345

  - `integrations.hubspot.type` (string, required)
    HubSpot object type
    Enum: "TICKET", "DEAL", "CONTACT"

  - `integrations.hubspot.dealAmount` (number,null, required)
    Deal amount (for DEAL type)
    Example: 5000

  - `integrations.hubspot.dealClosed` (boolean,null, required)
    Whether the deal is closed (for DEAL type)

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "invalid_request", "missing_parameter"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 400

## Response 404 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "resource_not_found"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 404