Tickets

Create a ticket

Creates a new ticket.

POST

/v2/tickets

Create a ticket

curl --request POST \
  --url https://do.featurebase.app/v2/tickets \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assigneeId": "507f1f77bcf86cd799439013",
  "author": {
    "email": "john@example.com",
    "id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "profilePicture": "https://example.com/avatar.png",
    "userId": "usr_12345"
  },
  "companyId": "507f1f77bcf86cd799439015",
  "content": "<p>I get a 403 error when logging in.</p>",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "customFields": {},
  "linkedConversationId": "507f1f77bcf86cd799439012",
  "skipNotifications": false,
  "statusId": "507f1f77bcf86cd799439016",
  "ticketCategoryId": "507f1f77bcf86cd799439011",
  "title": "Cannot login to dashboard"
}
'

{
  "assigneeId": "507f1f77bcf86cd799439013",
  "author": {
    "email": "john@example.com",
    "id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "profilePicture": "https://cdn.example.com/avatars/john.png",
    "type": "customer"
  },
  "categoryType": "customer",
  "companyId": "507f1f77bcf86cd799439015",
  "content": "<p>I get a 403 error when logging in.</p>",
  "conversationParts": [
    {
      "author": {
        "email": "john@example.com",
        "id": "676f0f6765bdaa7d7d760f88",
        "name": "John Doe",
        "profilePicture": "https://cdn.example.com/avatars/user.png",
        "type": "customer"
      },
      "bodyHtml": "<p>Hello, I have a question about your product.</p>",
      "bodyMarkdown": "Hello, I have a question about your product.",
      "channel": "desktop",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "id": "1",
      "object": "conversation_part",
      "partType": "user_msg",
      "redacted": false,
      "slack": {
        "channelId": "C01EFGH",
        "messageTs": "1705313410.001200",
        "teamId": "T01ABCD",
        "threadTs": "1705313400.001100"
      },
      "tagApplications": [
        {
          "appliedAt": "2025-01-15T10:30:00.000Z",
          "appliedBy": {
            "id": "507f1f77bcf86cd799439011",
            "name": "John Doe",
            "type": "admin"
          },
          "removedAt": "2025-01-15T11:00:00.000Z",
          "removedBy": {
            "id": "507f1f77bcf86cd799439011",
            "name": "John Doe",
            "type": "admin"
          },
          "tag": {
            "id": "67ec1234abcd5678ef901234",
            "name": "Churn",
            "type": "tag"
          },
          "tagId": "67ec1234abcd5678ef901234"
        }
      ],
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00.000Z",
  "customFields": {
    "507f1f77bcf86cd799439099": "{\"key\":\"org/pending/file.pdf\",\"name\":\"document.pdf\",\"url\":\"https://...\"}",
    "priority": "high"
  },
  "id": "507f1f77bcf86cd799439011",
  "integrations": {
    "clickup": [
      {
        "id": "86a1b2c3d",
        "title": "Fix login bug",
        "url": "https://app.clickup.com/t/86a1b2c3d"
      }
    ],
    "devops": [
      {
        "id": 789,
        "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "projectName": "My Project",
        "title": "Implement SSO",

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

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

assigneeIdstring

Example: 507f1f77bcf86cd799439013

authorobjectrequired

Author to attribute the post to. If not provided, uses the authenticated user — unless source is given, in which case a guest author is synthesised from source.label (or the channel name), because a relayed request belongs to the customer who said it. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email.

Show child attributes

companyIdstring

Example: 507f1f77bcf86cd799439015

contentstringdefault:

Example: <p>I get a 403 error when logging in.</p>

createdAtstring | null

Example: 2025-01-15T10:30:00.000Z

customFieldsobject

linkedConversationIdstring

Example: 507f1f77bcf86cd799439012

skipNotificationsbooleandefault:false

Example: false

statusIdstring

Example: 507f1f77bcf86cd799439016

ticketCategoryIdstringrequired

Example: 507f1f77bcf86cd799439011

titlestringrequired

Minimum string length: 2

Example: Cannot login to dashboard

Response

Created

assigneeIdstring | nullrequired

Assigned admin ID

Example: 507f1f77bcf86cd799439013

authorobject | nullrequired

Contact who created the ticket

Show child attributes

categoryTypeenum<string>required

Ticket category type

Available options: customer, tracker, back-office

Example: customer

companyIdstring | nullrequired

Associated company ID

Example: 507f1f77bcf86cd799439015

contentstringrequired

Ticket content/description (HTML)

Example: <p>I get a 403 error when logging in.</p>

conversationPartsobject[]

Conversation message history. Only included when fetching a single ticket by ID.

Show child attributes

createdAtstringrequired

ISO 8601 creation timestamp

Example: 2025-01-15T10:30:00.000Z

customFieldsobjectrequired

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.

idstringrequired

Unique identifier (MongoDB ID)

Example: 507f1f77bcf86cd799439011

integrationsobjectrequired

Third-party integration links

Show child attributes

linkedConversationsobject[]required

Linked conversations

Show child attributes

objectenum<string>required

Object type identifier

Available options: ticket

Example: ticket

openbooleanrequired

Whether the ticket is open

Example: true

snoozedUntilstring | nullrequired

ISO 8601 timestamp until snoozed (from linked conversation)

Example: 2025-01-16T09:00:00.000Z

statusobjectrequired

Current ticket status

Show child attributes

teamAssigneeIdstring | nullrequired

Assigned team ID (from linked conversation)

Example: 507f1f77bcf86cd799439014

ticketCategoryIdstringrequired

Ticket category ID

Example: 507f1f77bcf86cd799439011

ticketNumbernumberrequired

Sequential display ID (e.g. TK-42)

Example: 42

ticketUrlstringrequired

Full URL to view the ticket

Example: https://feedback.example.com/p/cannot-login

titlestringrequired

Ticket title

Example: Cannot login to dashboard

updatedAtstringrequired

ISO 8601 last updated timestamp

Example: 2025-01-15T12:30:00.000Z

Still need help? Ask the team