Skip to main content
This page describes how initdesk models helpdesk resources and how they appear in the Customer API. For request/response fields, use the API reference.

​
Scoping model

Everything integrators touch lives under one organization:
NOTE: This diagram illustrates a simplified view of the entity hierarchy. It does not represent the exhaustive set of exposed entities or relationships.
  • Organization — Your initdesk tenant. URL segment {organization_id} is the numeric database id. The organization also has a separate string public_id used in product URLs and branding; API paths use the numeric id.
  • All other resources are nested under /organizations/{organization_id}/. Authentication never widens scope: an org-scoped token cannot read or write another organization’s data.

​
Organization

Represents the business using initdesk. Use this endpoint to confirm you are on the correct tenant and to read configuration that affects ticket behavior (for example whether auto-tagging is enabled).

​
Customers (requesters)

A customer is an end user who can open and participate in tickets — not an initdesk agent user.
NOTE: Marking is_spam on a customer affects how inbound tickets from that address is treated in the product. Tickets related to customers with is_spam=True (via email or API) go directly to spam folder and are not processed until removed from the folder.

​
Tickets

A ticket is the conversation container: subject, status, assignee, inbox, tags, and denormalized counters. It is not the full thread—that lives in messages.

​
Two identifiers

Always use id in API calls. Display public_id to end users when you need the familiar “Ticket #1234” label. /

​
Lifecycle fields

​
Initial body vs thread

On create, the ticket may include description (plain text) / description_html (HTML) for the opening content — on user inteface, initdesk always show the one with most chars. Ongoing conversation is stored as messages (see below).

​
Assignee

Tickets may have an assignee (initdesk user). The Unassign ticket action clears the assignee without closing the ticket.

​
CC routing (when enabled)

If the organization has CC email routing enabled (default option), ticket create and customer-visible message create accept external_recipient_emails:
  • On ticket create, the list sets the ticket’s external CC snapshot for that moment only; omitting the field means no external CCs at creation. The requester’s email is always kept on the list.
  • On message create, the list applies to that message’s snapshot only; it does not rewrite the ticket row.

​
Messages

Messages are the thread: customer replies, associate replies, internal notes, system events, and CC participants. Messages are immutable. Nested under:

​
Roles

​
Visibility

is_visible_to_customer controls whether the message is part of the customer-facing thread. Internal notes are associate-only.

​
Content fields

Messages (and ticket descriptions) may include both:
  • content — plain text
  • content_html — HTML
    When both are present, display the longer of the two when rendering to users. The same rule applies when processing inbound content in integrations.

​
Creating messages

The create message operation adds a reply or internal note. It can drive workflow side effects (status changes, assignee updates) via next_action where supported—see the request schema in OpenAPI.

​
Inboxes

Each ticket belongs to an inbox (routing address / queue). Inbox appears on ticket payloads as id, name, and email_prefix.
NOTE: Integration tokens see all inboxes in the organization (unlike human users, who may be inbox-restricted).

​
Help Center

Under /organizations/{organization_id}/portal/: Help Center resources are independent of tickets but share the same organization scope and token auth.
NOTE: All AI agents (chat, email draft, etc) use Help Center articles to provide support. AI assistance is as good as your knowledge base.