Tickets

Create ticket

Create a ticket. Optional inbox_id targets a specific inbox; when omitted, the ticket routes to the organization’s default inbox (is_default: true). Use created_by_role to choose associate-on-behalf (agent logs a ticket for a requester; always emails the customer) versus customer self-service (requester opens their own ticket; emails only when inbox auto-reply is enabled). When CC email routing is enabled, optional external_recipient_emails sets CC recipients for the new ticket: omit or send null for none; send a list (empty or not) to set recipients. The requester (from_email) is always included in that list. Optional attachment_ids claims files previously uploaded via POST .../pending-attachments/ (see Tickets tag for the upload flow).

POST

organizations

{organization_id}

tickets

Create ticket

curl --request POST \
  --url https://api.initdesk.com/organizations/{organization_id}/tickets/ \
  --header 'Content-Type: application/json' \
  --header 'X-Initdesk-Token: <api-key>' \
  --data '
{
  "subject": "<string>",
  "from_name": "<string>",
  "from_email": "jsmith@example.com",
  "inbox_id": 123,
  "description": "<string>",
  "description_html": "<string>",
  "created_by_role": "associate",
  "external_recipient_emails": [
    "jsmith@example.com"
  ],
  "bcc_recipient_emails": [
    "jsmith@example.com"
  ],
  "attachment_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

import requests

url = "https://api.initdesk.com/organizations/{organization_id}/tickets/"

payload = {
    "subject": "<string>",
    "from_name": "<string>",
    "from_email": "jsmith@example.com",
    "inbox_id": 123,
    "description": "<string>",
    "description_html": "<string>",
    "created_by_role": "associate",
    "external_recipient_emails": ["jsmith@example.com"],
    "bcc_recipient_emails": ["jsmith@example.com"],
    "attachment_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
}
headers = {
    "X-Initdesk-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Initdesk-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subject: '<string>',
    from_name: '<string>',
    from_email: 'jsmith@example.com',
    inbox_id: 123,
    description: '<string>',
    description_html: '<string>',
    created_by_role: 'associate',
    external_recipient_emails: ['jsmith@example.com'],
    bcc_recipient_emails: ['jsmith@example.com'],
    attachment_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
  })
};

fetch('https://api.initdesk.com/organizations/{organization_id}/tickets/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.initdesk.com/organizations/{organization_id}/tickets/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subject' => '<string>',
    'from_name' => '<string>',
    'from_email' => 'jsmith@example.com',
    'inbox_id' => 123,
    'description' => '<string>',
    'description_html' => '<string>',
    'created_by_role' => 'associate',
    'external_recipient_emails' => [
        'jsmith@example.com'
    ],
    'bcc_recipient_emails' => [
        'jsmith@example.com'
    ],
    'attachment_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Initdesk-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.initdesk.com/organizations/{organization_id}/tickets/"

	payload := strings.NewReader("{\n  \"subject\": \"<string>\",\n  \"from_name\": \"<string>\",\n  \"from_email\": \"jsmith@example.com\",\n  \"inbox_id\": 123,\n  \"description\": \"<string>\",\n  \"description_html\": \"<string>\",\n  \"created_by_role\": \"associate\",\n  \"external_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"bcc_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"attachment_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Initdesk-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.initdesk.com/organizations/{organization_id}/tickets/")
  .header("X-Initdesk-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subject\": \"<string>\",\n  \"from_name\": \"<string>\",\n  \"from_email\": \"jsmith@example.com\",\n  \"inbox_id\": 123,\n  \"description\": \"<string>\",\n  \"description_html\": \"<string>\",\n  \"created_by_role\": \"associate\",\n  \"external_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"bcc_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"attachment_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.initdesk.com/organizations/{organization_id}/tickets/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Initdesk-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subject\": \"<string>\",\n  \"from_name\": \"<string>\",\n  \"from_email\": \"jsmith@example.com\",\n  \"inbox_id\": 123,\n  \"description\": \"<string>\",\n  \"description_html\": \"<string>\",\n  \"created_by_role\": \"associate\",\n  \"external_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"bcc_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"attachment_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": 123,
  "public_id": "<string>",
  "inbox": {
    "id": 123,
    "name": "<string>",
    "email_prefix": "<string>",
    "customer_interaction_style": "helpdesk"
  },
  "subject": "<string>",
  "from_name": "<string>",
  "from_email": "jsmith@example.com",
  "description": "<string>",
  "description_html": "<string>",
  "external_recipient_emails": [
    "jsmith@example.com"
  ],
  "bcc_recipient_emails": [
    "jsmith@example.com"
  ]
}

Authorizations

X-Initdesk-Token

string

header

required

Path Parameters

organization_id

string

required

Pattern: ^[-a-zA-Z0-9_]+$

Body

subject

string

required

Required string length: 1 - 255

from_name

string

required

Display name used only when resolving or creating the requester Customer at ticket creation. After create, read customer.name for the live requester. Not updated when the requester is changed.

Required string length: 1 - 255

from_email

string<email>

required

Email used only to resolve or create the requester Customer at ticket creation. After create, read customer.email for the live requester. Not updated when the requester is changed.

Required string length: 1 - 254

inbox_id

integer

write-only

Optional inbox to route the new ticket. When omitted, the ticket is created in the organization's default inbox (is_default: true, typically named Main Inbox). Provide an inbox ID to target a specific mailbox; list available inboxes via the inboxes endpoint. Inbox-level settings (e.g. auto-reply) on the resolved inbox apply.

description

string

description_html

string

created_by_role

enum<string>

default:associate

write-only

Who is creating the ticket via the API. Affects initial status, waiting_on, and whether the customer receives a ticket-created email. associate: an authenticated agent creates the ticket on behalf of the requester (from_email); use for phone support or proactive outreach. Sets status to active, waiting_on to customer, and created_by_user to the authenticated user. Always sends a ticket-created email to the customer, even when inbox auto-reply is disabled. customer: the requester creates the ticket for themselves (self-service portal, app, or integration acting as the end user). Sets status to created, waiting_on to associate, and leaves created_by_user unset. Sends a ticket-created email only when the inbox has auto-reply enabled.

associate - Associate
customer - Customer

Available options:

associate,

customer

external_recipient_emails

string<email>[] | null

When provided as a list (empty or not), sets the ticket external CC list when CC email routing is enabled; omitted or null leaves it as the default empty list. The ticket requester (from_email) is always kept on the list.

Minimum string length: 1

bcc_recipient_emails

string<email>[] | null

When provided as a list (empty or not), sets creation-time BCC addresses used only for the ticket-created outbound email when CC email routing is enabled. Omitted or null leaves an empty list. Cannot overlap the requester or the CC list. Not applied to later associate replies.

Minimum string length: 1

attachment_ids

string<uuid>[]

write-only

List of pending attachment IDs to attach to the new ticket. Upload files via the organization pending-attachments endpoints before creating the ticket.

Response

integer

required

read-only

public_id

string

required

read-only

inbox

object

required

Show child attributes

subject

string

required

Maximum string length: 255

from_name

string

required

Display name used only when resolving or creating the requester Customer at ticket creation. After create, read customer.name for the live requester. Not updated when the requester is changed.

Maximum string length: 255

from_email

string<email>

required

Email used only to resolve or create the requester Customer at ticket creation. After create, read customer.email for the live requester. Not updated when the requester is changed.

Maximum string length: 254

description

string

description_html

string

external_recipient_emails

string<email>[] | null

bcc_recipient_emails

string<email>[] | null

Create ticket

curl --request POST \
  --url https://api.initdesk.com/organizations/{organization_id}/tickets/ \
  --header 'Content-Type: application/json' \
  --header 'X-Initdesk-Token: <api-key>' \
  --data '
{
  "subject": "<string>",
  "from_name": "<string>",
  "from_email": "jsmith@example.com",
  "inbox_id": 123,
  "description": "<string>",
  "description_html": "<string>",
  "created_by_role": "associate",
  "external_recipient_emails": [
    "jsmith@example.com"
  ],
  "bcc_recipient_emails": [
    "jsmith@example.com"
  ],
  "attachment_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

import requests

url = "https://api.initdesk.com/organizations/{organization_id}/tickets/"

payload = {
    "subject": "<string>",
    "from_name": "<string>",
    "from_email": "jsmith@example.com",
    "inbox_id": 123,
    "description": "<string>",
    "description_html": "<string>",
    "created_by_role": "associate",
    "external_recipient_emails": ["jsmith@example.com"],
    "bcc_recipient_emails": ["jsmith@example.com"],
    "attachment_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
}
headers = {
    "X-Initdesk-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Initdesk-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subject: '<string>',
    from_name: '<string>',
    from_email: 'jsmith@example.com',
    inbox_id: 123,
    description: '<string>',
    description_html: '<string>',
    created_by_role: 'associate',
    external_recipient_emails: ['jsmith@example.com'],
    bcc_recipient_emails: ['jsmith@example.com'],
    attachment_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
  })
};

fetch('https://api.initdesk.com/organizations/{organization_id}/tickets/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.initdesk.com/organizations/{organization_id}/tickets/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subject' => '<string>',
    'from_name' => '<string>',
    'from_email' => 'jsmith@example.com',
    'inbox_id' => 123,
    'description' => '<string>',
    'description_html' => '<string>',
    'created_by_role' => 'associate',
    'external_recipient_emails' => [
        'jsmith@example.com'
    ],
    'bcc_recipient_emails' => [
        'jsmith@example.com'
    ],
    'attachment_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Initdesk-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.initdesk.com/organizations/{organization_id}/tickets/"

	payload := strings.NewReader("{\n  \"subject\": \"<string>\",\n  \"from_name\": \"<string>\",\n  \"from_email\": \"jsmith@example.com\",\n  \"inbox_id\": 123,\n  \"description\": \"<string>\",\n  \"description_html\": \"<string>\",\n  \"created_by_role\": \"associate\",\n  \"external_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"bcc_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"attachment_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Initdesk-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.initdesk.com/organizations/{organization_id}/tickets/")
  .header("X-Initdesk-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subject\": \"<string>\",\n  \"from_name\": \"<string>\",\n  \"from_email\": \"jsmith@example.com\",\n  \"inbox_id\": 123,\n  \"description\": \"<string>\",\n  \"description_html\": \"<string>\",\n  \"created_by_role\": \"associate\",\n  \"external_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"bcc_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"attachment_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.initdesk.com/organizations/{organization_id}/tickets/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Initdesk-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subject\": \"<string>\",\n  \"from_name\": \"<string>\",\n  \"from_email\": \"jsmith@example.com\",\n  \"inbox_id\": 123,\n  \"description\": \"<string>\",\n  \"description_html\": \"<string>\",\n  \"created_by_role\": \"associate\",\n  \"external_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"bcc_recipient_emails\": [\n    \"jsmith@example.com\"\n  ],\n  \"attachment_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": 123,
  "public_id": "<string>",
  "inbox": {
    "id": 123,
    "name": "<string>",
    "email_prefix": "<string>",
    "customer_interaction_style": "helpdesk"
  },
  "subject": "<string>",
  "from_name": "<string>",
  "from_email": "jsmith@example.com",
  "description": "<string>",
  "description_html": "<string>",
  "external_recipient_emails": [
    "jsmith@example.com"
  ],
  "bcc_recipient_emails": [
    "jsmith@example.com"
  ]
}