Documentation Index
Fetch the complete documentation index at: https://developers.initdesk.com/llms.txt
Use this file to discover all available pages before exploring further.
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 is a simplified diagram to explain the entity hierarchy. Not all relationships are exposed.
- 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.
| Concept | Detail |
|---|
| Identity | Unique (organization, email) pair |
| API fields | id, name, email, is_spam |
| Role in tickets | Every ticket links to exactly one customer |
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
| Field | Use |
|---|
id | Primary key in API URLs (/tickets/{pk}/, /tickets/{ticket_id}/messages/) |
public_id | Human-facing ticket number shown in email subjects and the UI (per-organization sequence) |
id in API calls. Display public_id to end users when you need the familiar “Ticket #1234” label.
/
Lifecycle fields
| Field | Meaning |
|---|
status | Workflow state (created, active, closed, plus legacy values). Use List ticket statuses for allowed values and labels. |
waiting_on | Who is expected to act next: associate, customer, or none. |
classification | Resolution category when closed (resolved, invalid, inactivity, etc.). |
is_spam | Spam tickets are excluded from default list/search unless you pass is_spam=true. |
origin | How the ticket was created (email, api, …). |
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:
/organizations/{organization_id}/tickets/{ticket_id}/messages/
Roles
role | Typical meaning |
|---|
customer | Inbound from the requester (API value; interface may say “requester”) |
cc | Inbound from an external CC participant |
associate | Support associate (a human user) from your team |
system | Automated system line (closures, reminders) |
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 textcontent_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/:
| Resource | Purpose |
|---|
| Portal settings | Singleton configuration for the customer-facing portal (get / full or partial update) |
| Collections | Hierarchical groupings for articles; includes a tree view |
| Articles | Knowledge base articles (CRUD) |
| Article search | Full-text search across title, excerpt, and body |
NOTE: All AI agents (chat, email draft, etc) use Help Center articles to provide support. AI assistance is as good as your knowledge base.
