# List custom preset filters
Source: https://developers.initdesk.com/api-reference/custom-preset-filters/list-custom-preset-filters

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/custom-preset-filters/
Return saved ticket search filters visible to the caller. Integration tokens receive organization-shared filters only.



# Retrieve custom preset filter
Source: https://developers.initdesk.com/api-reference/custom-preset-filters/retrieve-custom-preset-filter

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/custom-preset-filters/{id}/
Return a saved ticket search filter by ID. Integration tokens may only retrieve organization-shared filters.



# Create customer
Source: https://developers.initdesk.com/api-reference/customers/create-customer

https://api.initdesk.com/schema.yaml post /organizations/{organization_id}/customers/
Create a requester (customer) in the organization.



# List customers
Source: https://developers.initdesk.com/api-reference/customers/list-customers

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/customers/
Return requesters (customers) for the organization.



# Retrieve customer
Source: https://developers.initdesk.com/api-reference/customers/retrieve-customer

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/customers/{pk}/
Return a requester by ID.



# Update customer
Source: https://developers.initdesk.com/api-reference/customers/update-customer

https://api.initdesk.com/schema.yaml put /organizations/{organization_id}/customers/{pk}/
Replace requester fields (full update).



# Create article
Source: https://developers.initdesk.com/api-reference/help-center/create-article

https://api.initdesk.com/schema.yaml post /organizations/{organization_id}/portal/articles/
Create a knowledge base article.



# Create collection
Source: https://developers.initdesk.com/api-reference/help-center/create-collection

https://api.initdesk.com/schema.yaml post /organizations/{organization_id}/portal/collections/
Create a knowledge base collection.



# Delete article
Source: https://developers.initdesk.com/api-reference/help-center/delete-article

https://api.initdesk.com/schema.yaml delete /organizations/{organization_id}/portal/articles/{pk}/
Delete an article. Address the article by ID or slug.



# Delete collection
Source: https://developers.initdesk.com/api-reference/help-center/delete-collection

https://api.initdesk.com/schema.yaml delete /organizations/{organization_id}/portal/collections/{pk}/
Delete a collection.



# Get portal favicon URL
Source: https://developers.initdesk.com/api-reference/help-center/get-portal-favicon-url

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/portal/favicon/{size}/
Retrieve the portal favicon URL for the given size (pixels).



# Get portal logo URL
Source: https://developers.initdesk.com/api-reference/help-center/get-portal-logo-url

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/portal/logo/{size}/
Retrieve the portal logo URL for the given size. Use a number for a square image (e.g. 128), or a number with 'h'/'w' suffix to constrain height or width while preserving aspect ratio (e.g. 100h or 100w).



# Get portal settings
Source: https://developers.initdesk.com/api-reference/help-center/get-portal-settings

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/portal/
Return the organization's support portal settings. Creates a portal record if one does not exist yet.



# List articles
Source: https://developers.initdesk.com/api-reference/help-center/list-articles

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/portal/articles/
Return knowledge base articles for the organization. Filter by collection or publication status with query parameters.



# List collection tree
Source: https://developers.initdesk.com/api-reference/help-center/list-collection-tree

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/portal/collections/tree/
Return collections as a nested tree. Use include_articles to embed articles per collection node.



# List collections
Source: https://developers.initdesk.com/api-reference/help-center/list-collections

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/portal/collections/
Return knowledge base collections for the organization's portal.



# Partially update article
Source: https://developers.initdesk.com/api-reference/help-center/partially-update-article

https://api.initdesk.com/schema.yaml patch /organizations/{organization_id}/portal/articles/{pk}/
Update selected article fields. Address the article by ID or slug.



# Partially update collection
Source: https://developers.initdesk.com/api-reference/help-center/partially-update-collection

https://api.initdesk.com/schema.yaml patch /organizations/{organization_id}/portal/collections/{pk}/
Update selected collection fields.



# Replace portal settings
Source: https://developers.initdesk.com/api-reference/help-center/replace-portal-settings

https://api.initdesk.com/schema.yaml put /organizations/{organization_id}/portal/
Replace all portal settings for the organization (full update).



# Retrieve article
Source: https://developers.initdesk.com/api-reference/help-center/retrieve-article

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/portal/articles/{pk}/
Return an article by ID or slug.



# Retrieve collection
Source: https://developers.initdesk.com/api-reference/help-center/retrieve-collection

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/portal/collections/{pk}/
Return a collection by ID.



# Search knowledge base articles
Source: https://developers.initdesk.com/api-reference/help-center/search-knowledge-base-articles

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/portal/search/
Search articles by title, excerpt, and markdown content. Results are limited by the limit query parameter.



# Update article
Source: https://developers.initdesk.com/api-reference/help-center/update-article

https://api.initdesk.com/schema.yaml put /organizations/{organization_id}/portal/articles/{pk}/
Replace article fields (full update). Address the article by ID or slug.



# Update collection
Source: https://developers.initdesk.com/api-reference/help-center/update-collection

https://api.initdesk.com/schema.yaml put /organizations/{organization_id}/portal/collections/{pk}/
Replace collection fields (full update).



# Update portal settings
Source: https://developers.initdesk.com/api-reference/help-center/update-portal-settings

https://api.initdesk.com/schema.yaml patch /organizations/{organization_id}/portal/
Partially update portal settings for the organization.



# List inboxes
Source: https://developers.initdesk.com/api-reference/inboxes/list-inboxes

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/inboxes/
Return all inboxes for the organization. On ticket create, inbox_id is optional: omit to route to the default inbox (is_default: true), or provide an inbox ID from this list to target a specific mailbox.



# Retrieve inbox
Source: https://developers.initdesk.com/api-reference/inboxes/retrieve-inbox

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/inboxes/{pk}/
Return inbox details, including email prefix and whether it is the default inbox for the organization.



# List organizations
Source: https://developers.initdesk.com/api-reference/organizations/list-organizations

https://api.initdesk.com/schema.yaml get /organizations/
List organizations the authenticated user belongs to. Use the organization ID in subsequent API paths. Filter by name with `search`.



# Retrieve organization
Source: https://developers.initdesk.com/api-reference/organizations/retrieve-organization

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/
Retrieve an organization by its internal ID or public_id.



# List organization tags
Source: https://developers.initdesk.com/api-reference/tags/list-organization-tags

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/tags/
Return all tags defined for the organization, including id, name, and color.



# Retrieve organization tag
Source: https://developers.initdesk.com/api-reference/tags/retrieve-organization-tag

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/tags/{pk}/
Return a single organization tag by ID.



# Create pending attachment
Source: https://developers.initdesk.com/api-reference/tickets/create-pending-attachment

https://api.initdesk.com/schema.yaml post /organizations/{organization_id}/pending-attachments/
Multipart upload (`file_upload`) before ticket creation. Pass the returned `id` in ticket create `attachment_ids` to claim the file. See the Tickets tag for the full upload flow.



# Create ticket
Source: https://developers.initdesk.com/api-reference/tickets/create-ticket

https://api.initdesk.com/schema.yaml post /organizations/{organization_id}/tickets/
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).



# Create ticket attachment
Source: https://developers.initdesk.com/api-reference/tickets/create-ticket-attachment

https://api.initdesk.com/schema.yaml post /organizations/{organization_id}/tickets/{ticket_id}/attachments/
Multipart upload (`file_upload`) for an existing ticket. Pass the returned `id` in message create `attachment_ids` to claim the file. See the Tickets tag for the full upload flow.



# Download ticket attachment
Source: https://developers.initdesk.com/api-reference/tickets/download-ticket-attachment

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/tickets/{ticket_id}/attachments/{pk}/
Redirects to the attachment file URL in storage (HTTP redirect response).



# List ticket messages
Source: https://developers.initdesk.com/api-reference/tickets/list-ticket-messages

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/tickets/{ticket_id}/messages/
Return messages for a ticket.



# List ticket statuses
Source: https://developers.initdesk.com/api-reference/tickets/list-ticket-statuses

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/ticketstatus/
Return all ticket status values with human-readable labels (enum value and description per entry).



# List tickets
Source: https://developers.initdesk.com/api-reference/tickets/list-tickets

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/tickets/
Return tickets for the organization. By default only non-spam tickets are included; pass `is_spam=true` to list spam tickets. Filter by requester with `customer_id`.



# Reply or create internal note
Source: https://developers.initdesk.com/api-reference/tickets/reply-or-create-internal-note

https://api.initdesk.com/schema.yaml post /organizations/{organization_id}/tickets/{ticket_id}/messages/
Add a reply or internal note to the ticket. For customer-visible replies, optional `external_recipient_emails` sets CC recipients for that message; omit or null to reuse CC recipients from the previous customer-visible message or from ticket creation. Internal notes ignore this field. Optional `attachment_ids` claims files previously uploaded via `POST .../tickets/{ticket_id}/attachments/` (see Tickets tag for the upload flow).



# Retrieve ticket
Source: https://developers.initdesk.com/api-reference/tickets/retrieve-ticket

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/tickets/{ticket_id}/
Return full ticket details for the given ticket ID. To retrieve its messages (replies and internal notes), use the `messages` endpoint.



# Search tickets
Source: https://developers.initdesk.com/api-reference/tickets/search-tickets

https://api.initdesk.com/schema.yaml get /organizations/{organization_id}/search/
Performs full text & faceted search over tickets. Use `preset_filter` to apply one of the predefined filter sets. Use `custom_preset_filter` (UUID) to apply a saved custom filter. Filter by tag with `tags` (repeat for OR matching). Filter by assignee with `assignee` (organization user ID). Filter by classification with `classification`. Filter by active snooze with `is_snoozed`.



# Unassign ticket
Source: https://developers.initdesk.com/api-reference/tickets/unassign-ticket

https://api.initdesk.com/schema.yaml post /organizations/{organization_id}/tickets/{ticket_id}/unassign/
Removes the current assignee from the ticket (sets assignee to null) and returns updated ticket details.



# Authentication and limits
Source: https://developers.initdesk.com/authentication



## Authentication

Use an **organization-scoped integration token** created in initdesk. Send the raw token on every request using custom header:

* `X-Initdesk-Token: <token>`

**Scope:** An org-scoped token may only access resources for the organization it was issued for. Requests to another organization's URLs return `403 Forbidden`.

**Invalid or inactive tokens:** If you send a token header and authentication fails, the API responds with `401` / `403` as appropriate.

### Issuing a new token

Access **Settings** > **API access** to generate a new token. Only users with **Account Owner** or **Admin** roles can issue tokens.

Tokens are stored server-side as salted hashes; the raw value is shown only once at creation. Revoke compromised tokens immediately.

## Rate limits and errors

The gateway applies **per-token rate limiting** (keyed on `X-Initdesk-Token`).

The limit is defined as **60 requests/minute** for most endpoints. Ticket **creation** is also throttled per organization on the backend (hourly cap).

Expect `429 Too Many Requests` when limits are exceeded; back off and retry with exponential delay.


# initdesk API
Source: https://developers.initdesk.com/endpoints



Programmatic access to your organization's helpdesk data: tickets, requesters, conversations, and help center content. The public API is the supported integration surface for external systems (CRMs, internal tools, automation, custom portals). To easily bring your data to initdesk ticket panel and AI agent, see [BYOD plugin](https://help.initdesk.com/plugins/byod-bring-your-own-data).

## How to connect

All API traffic goes through the **initdesk API gateway**.

| Item               | Detail                                 |
| ------------------ | -------------------------------------- |
| **Base URL**       | `https://api.initdesk.com`             |
| **OpenAPI schema** | `https://api.initdesk.com/schema.yaml` |

## Organization scope

All APIs paths are scoped under an organization:

```text theme={null}
/organizations/{organization_id}/{...}
```

`organization_id` is the numeric organization primary key (not the organization's `public_id` string). You can find your ID on **Settings** > **General** tab.

## Pagination and lists

List endpoints use page-number pagination with a default page size of **20**. Responses include `count`, `next`, `previous`, and `results`.

## Support

For access issues or questions about beta features exposed the API, contact your initdesk at [**support@initdesk.com**](mailto:support@initdesk.com).


# Entities and relationships
Source: https://developers.initdesk.com/main-entities



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.