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

# Entities and relationships

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:

```mermaid theme={null}
flowchart TB
  Org[Organization]
  Org --> Customers[Customers / requesters]
  Org --> Inboxes[Inboxes]
  Org --> Tickets[Tickets]
  Org --> Portal[Help Center / portal]
  Inboxes --> Tickets
  Tickets --> Messages[Messages]
  Tickets --> Attachments[Attachments]
  Portal --> Collections[Collections]
  Portal --> Articles[Articles]
```

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

| 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) |

Always use `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:

```text theme={null}
/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 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/`:

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

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.