REST API
Help Desk MX exposes a REST API that lets you integrate your store's support system with external tools, mobile applications, and other services. Using this API, external systems can create and update tickets, exchange messages, manage drafts, and read reference data (statuses, priorities, departments, custom fields, and more) without going through the Magento admin panel.
All endpoints listed below are admin-authenticated endpoints — they are not anonymous or customer-token endpoints.
Every request must carry a valid Magento admin/integration bearer token, and the token's user or integration must be
granted the corresponding ACL resource (mostly Mirasvit_Helpdesk::helpdesk_ticket, plus helpdesk_status,
helpdesk_priority, helpdesk_department, and helpdesk_field for those resource groups). The ACL resource required
by each route is noted in its description below.
Authentication
Help Desk MX does not introduce its own authentication mechanism — it relies entirely on Magento's built-in REST
authentication. Obtain an admin token via POST /V1/integration/admin/token (or use an integration access token) and
send it as a Bearer token in the Authorization header of every request. For details on generating and using admin
tokens, refer to the Authentication
guide on the Magento DevDocs page.
Filtering, sorting, and pagination
Every getList-style endpoint (/V1/helpdesk/tickets, /V1/helpdesk/statuses, /V1/helpdesk/priorities, and so on)
accepts a standard Magento searchCriteria query parameter for filtering, sorting, and pagination — the same
convention used by core Magento REST endpoints (searchCriteria[filterGroups]..., searchCriteria[sortOrders]...,
searchCriteria[pageSize], searchCriteria[currentPage]). Refer to the
Search using REST APIs guide on the
Magento DevDocs page for the full syntax; it is not repeated here.
Tickets
Requires the Mirasvit_Helpdesk::helpdesk_ticket ACL resource.
| Method | URL | Description |
|---|---|---|
| POST | /V1/helpdesk/ticket | Creates a new ticket. |
| PUT | /V1/helpdesk/ticket/{code} | Updates an existing ticket. |
| DELETE | /V1/helpdesk/ticket/{code} | Deletes a ticket. |
| GET | /V1/helpdesk/ticket/{code} | Returns a ticket together with its messages and custom fields. |
| GET | /V1/helpdesk/tickets | Returns a filtered, sorted, paginated list of tickets. |
The {code} path parameter is the ticket's code (e.g. 000000001), not its numeric ticket_id.
Request body — POST /V1/helpdesk/ticket
| Attribute | Data Type | Description |
|---|---|---|
| customer_email | String | Email address of the ticket's customer. This field is required. |
| subject | String | The subject line of the ticket. This field is required. |
| message | String | The body of the initial ticket message. This field is required. |
| store_id | Int | The store view the ticket belongs to. |
| priority_id | Int | The ID of the priority assigned to the ticket. |
| department_id | Int | The ID of the department handling the ticket. |
| status_id | Int | The ID of the initial status assigned to the ticket. |
| order_id | Int | The ID of the order associated with the ticket. |
| customer_id | Int | The ID of the customer, if the ticket belongs to a registered customer. |
| customer_name | String | Name of the customer (used for guest tickets). |
| owner | String | Name of the ticket owner/agent to display. |
| cc | String | Comma-separated list of CC email addresses. |
| bcc | String | Comma-separated list of BCC email addresses. |
| tags | Array of String | Tag names to attach to the new ticket. |
Request parameters — PUT /V1/helpdesk/ticket/{code}
| Attribute | Data Type | Description |
|---|---|---|
| code | String | Ticket code identifier, passed in the URL. This field is required. |
| statusId | Int | New status ID for the ticket. |
| priorityId | Int | New priority ID for the ticket. |
| userId | Int | ID of the admin user (agent) to assign the ticket to. |
| subject | String | New subject line for the ticket. |
| tags | Array of String | Replaces the ticket's tags with this list. |
| folder | Int | Folder to move the ticket to: 1 = Inbox, 2 = Archive, 3 = Spam. |
| customFields | Object | Map of custom field code to value, e.g. {"f_product_id": "42"}. Each code must match an active row in mst_helpdesk_field. |
Response object — TicketInterface (returned by create, update, addMessage; and nested in the ticket node of GET)
| Attribute | Data Type | Description |
|---|---|---|
| ticket_id | Int | The internal numeric ID of the ticket. |
| code | String | The ticket's code identifier, used in the URL for all other ticket endpoints. |
| external_id | String | External identifier of the ticket, if set by an integration. |
| user_id | Int | ID of the admin user (agent) currently assigned to the ticket. |
| subject | String | The subject line of the ticket. |
| description | String | The body of the first ticket message. |
| priority_id | Int | The ID of the ticket's priority. |
| status_id | Int | The ID of the ticket's current status. |
| department_id | Int | The ID of the department handling the ticket. |
| customer_id | Int | The ID of the customer who owns the ticket, if registered. |
| customer_email | String | The email address of the ticket's customer. |
| customer_name | String | The name of the ticket's customer. |
| order_id | Int | The ID of the order associated with the ticket. |
| last_reply_name | String | Name of the person who posted the last reply. |
| last_reply_at | String | Date and time of the last reply. |
| reply_cnt | Int | Number of replies posted on the ticket. |
| store_id | Int | The store view the ticket belongs to. |
| created_at | String | Date and time the ticket was created. |
| updated_at | String | Date and time the ticket was last updated. |
| folder | Int | Current folder: 1 = Inbox, 2 = Archive, 3 = Spam. |
| channel | String | Channel through which the ticket was created (e.g. email, contact form, offline chat). |
| channel_data | String | Additional channel-specific data, serialized. |
| third_party_email | String | Email address used when the ticket originates from a third-party channel. |
| cc | Array of String | CC email addresses on the ticket. |
| bcc | Array of String | BCC email addresses on the ticket. |
| merged_ticket_id | Int | ID of the ticket this one was merged into, if applicable. |
Response object — GET /V1/helpdesk/ticket/{code} (TicketGetResponseInterface)
| Attribute | Data Type | Description |
|---|---|---|
| ticket | TicketInterface | The ticket object, described in the table above. |
| messages | Array of MessageItemInterface | All messages on the ticket. See the fields of MessageItemInterface in the Ticket Messages section below. |
| customFields | Array of CustomFieldItemInterface | The ticket's custom field values, each with field_code, name, and field_value. |
Response object — GET /V1/helpdesk/tickets (TicketSearchResultsInterface)
| Attribute | Data Type | Description |
|---|---|---|
| items | Array of TicketInterface | The list of tickets matching the search criteria. |
| search_criteria | SearchCriteria | The search criteria echoed back, per the standard Magento REST convention. |
| total_count | Int | Total number of tickets matching the filters, ignoring pagination. |
Ticket Messages
Requires the Mirasvit_Helpdesk::helpdesk_ticket ACL resource.
| Method | URL | Description |
|---|---|---|
| POST | /V1/helpdesk/ticket/{code}/message | Adds a message to an existing ticket. |
| GET | /V1/helpdesk/ticket/{code}/message | Returns a paginated list of messages for a ticket. |
Request parameters — POST /V1/helpdesk/ticket/{code}/message
| Attribute | Data Type | Description |
|---|---|---|
| code | String | Ticket code identifier, passed in the URL. This field is required. |
| message | String | The message body to add to the ticket. This field is required. |
| type | String | Message type: public or internal. Defaults to public. |
This endpoint returns the updated TicketInterface object (see the Tickets section above).
Response object — MessageItemInterface (items in GET /V1/helpdesk/ticket/{code}/message, and in the messages node of GET /V1/helpdesk/ticket/{code})
| Attribute | Data Type | Description |
|---|---|---|
| message_id | Int | The internal numeric ID of the message. |
| ticket_id | Int | The ID of the ticket the message belongs to. |
| user_id | Int | ID of the admin user (agent) who posted the message, if applicable. |
| customer_id | Int | ID of the customer who posted the message, if applicable. |
| customer_email | String | Email address of the customer who posted the message. |
| customer_name | String | Name of the customer who posted the message. |
| body | String | The message content. |
| body_format | String | Format of the message body (e.g. html, text). |
| type | String | Message type: public or internal. |
| triggered_by | String | Indicates who triggered the message (e.g. customer, admin, system). |
| is_read | Int | Whether the message has been read. |
| created_at | String | Date and time the message was created. |
| updated_at | String | Date and time the message was last updated. |
| user_name | String | Name of the admin user (agent) who posted the message. |
| third_party_email | String | Email address used when the message originates from a third-party channel. |
| third_party_name | String | Name used when the message originates from a third-party channel. |
| attachments | Array of AttachmentMetadataInterface | Attachments on this message. Each item exposes attachment_id, name, type, size, and a downloadable url — a lighter shape than the full Attachment object described in the Attachments section below. |
Ticket Drafts
Requires the Mirasvit_Helpdesk::helpdesk_ticket ACL resource. Drafts let an agent save an in-progress reply that is
visible in the ticket edit page for review before it is sent.
| Method | URL | Description |
|---|---|---|
| PUT | /V1/helpdesk/ticket/{code}/draft | Saves (creates or overwrites) the draft reply for a ticket. |
| GET | /V1/helpdesk/ticket/{code}/draft | Returns the current draft reply for a ticket. |
| DELETE | /V1/helpdesk/ticket/{code}/draft | Deletes the draft reply for a ticket. |
Request parameters — PUT /V1/helpdesk/ticket/{code}/draft
| Attribute | Data Type | Description |
|---|---|---|
| code | String | Ticket code identifier, passed in the URL. This field is required. |
| body | String | The draft message body. This field is required. |
PUT and DELETE return a Boolean. GET returns the draft body as a plain String (empty string if no draft exists).
Statuses
Requires the Mirasvit_Helpdesk::helpdesk_status ACL resource.
| Method | URL | Description |
|---|---|---|
| POST | /V1/helpdesk/status | Creates or updates a helpdesk status. |
| GET | /V1/helpdesk/status/{statusId} | Returns a status by ID. |
| GET | /V1/helpdesk/statuses | Returns a filtered, sorted, paginated list of statuses. |
Request body / response object — StatusInterface
| Attribute | Data Type | Description |
|---|---|---|
| status_id | Int | The ID of the status. Omit when creating a new status. |
| name | String | The display name of the status. |
| code | String | The unique code of the status. |
| color | String | The color associated with the status, used in the admin grid. |
| sort_order | Int | Position of the status relative to others. |
GET /V1/helpdesk/statuses returns a StatusSearchResultsInterface with items (array of StatusInterface), search_criteria, and total_count, following the same shape as the ticket list response above.
Priorities
Requires the Mirasvit_Helpdesk::helpdesk_priority ACL resource.
| Method | URL | Description |
|---|---|---|
| POST | /V1/helpdesk/priority | Creates or updates a helpdesk priority. |
| GET | /V1/helpdesk/priority/{priorityId} | Returns a priority by ID. |
| GET | /V1/helpdesk/priorities | Returns a filtered, sorted, paginated list of priorities. |
Request body / response object — PriorityInterface
| Attribute | Data Type | Description |
|---|---|---|
| priority_id | Int | The ID of the priority. Omit when creating a new priority. |
| name | String | The display name of the priority. |
| color | String | The color associated with the priority, used in the admin grid. |
| sort_order | Int | Position of the priority relative to others. |
GET /V1/helpdesk/priorities returns a PrioritySearchResultsInterface with items (array of PriorityInterface), search_criteria, and total_count.
Departments
Requires the Mirasvit_Helpdesk::helpdesk_department ACL resource. Departments are read-only through this API — there is no save endpoint.
| Method | URL | Description |
|---|---|---|
| GET | /V1/helpdesk/department/{departmentId} | Returns a department by ID. |
| GET | /V1/helpdesk/departments | Returns a filtered, sorted, paginated list of departments. |
Response object — DepartmentInterface
| Attribute | Data Type | Description |
|---|---|---|
| department_id | Int | The ID of the department. |
| name | String | The display name of the department. |
| notification_email | String | Email address notified about activity in the department. |
| sort_order | Int | Position of the department relative to others. |
| is_active | Int | Whether the department is active (1) or disabled (0). |
GET /V1/helpdesk/departments returns a DepartmentSearchResultsInterface with items (array of DepartmentInterface), search_criteria, and total_count.
Tags
Requires the Mirasvit_Helpdesk::helpdesk_ticket ACL resource. Tags are read-only through this API.
| Method | URL | Description |
|---|---|---|
| GET | /V1/helpdesk/tags | Returns a filtered, sorted, paginated list of tags. |
Response object — TagInterface
| Attribute | Data Type | Description |
|---|---|---|
| tag_id | Int | The ID of the tag. |
| name | String | The name of the tag. |
GET /V1/helpdesk/tags returns a TagSearchResultsInterface with items (array of TagInterface), search_criteria, and total_count.
Custom Fields
Requires the Mirasvit_Helpdesk::helpdesk_field ACL resource. Custom field definitions are read-only through this
API; a ticket's custom field values are read and written through the Tickets endpoints above (the customFields
node in a ticket's GET response, and the customFields request parameter of update).
| Method | URL | Description |
|---|---|---|
| GET | /V1/helpdesk/field/{fieldId} | Returns a custom field definition by ID. |
| GET | /V1/helpdesk/fields | Returns a filtered, sorted, paginated list of custom field definitions. |
Response object — FieldInterface
| Attribute | Data Type | Description |
|---|---|---|
| field_id | Int | The ID of the custom field. |
| name | String | The display name of the custom field. |
| code | String | The unique code of the custom field, used as the key in a ticket's customFields map. |
| type | String | The input type of the custom field (e.g. text, select, textarea). |
| description | String | Description/help text of the custom field. |
| values | String | Serialized list of options, for fields of a choice type (select, multiselect, etc.). |
| is_active | Int | Whether the custom field is active (1) or disabled (0). |
| sort_order | Int | Position of the custom field relative to others. |
GET /V1/helpdesk/fields returns a FieldSearchResultsInterface with items (array of FieldInterface), search_criteria, and total_count.
Satisfaction Surveys
Requires the Mirasvit_Helpdesk::helpdesk_ticket ACL resource. Satisfaction survey results are read-only through this API.
| Method | URL | Description |
|---|---|---|
| GET | /V1/helpdesk/satisfaction/{satisfactionId} | Returns a satisfaction survey result by ID. |
| GET | /V1/helpdesk/satisfactions | Returns a filtered, sorted, paginated list of satisfaction survey results. |
Response object — SatisfactionInterface
| Attribute | Data Type | Description |
|---|---|---|
| satisfaction_id | Int | The ID of the survey result. |
| ticket_id | Int | The ID of the ticket the survey was submitted for. |
| message_id | Int | The ID of the message the survey rating was attached to. |
| user_id | Int | ID of the admin user (agent) associated with the rated interaction. |
| customer_id | Int | ID of the customer who submitted the rating. |
| store_id | Int | The store view the rating was submitted from. |
| rate | Int | The numeric satisfaction rating. |
| comment | String | Optional comment left by the customer with the rating. |
| created_at | String | Date and time the rating was created. |
| updated_at | String | Date and time the rating was last updated. |
GET /V1/helpdesk/satisfactions returns a SatisfactionSearchResultsInterface with items (array of SatisfactionInterface), search_criteria, and total_count.
Activities
Requires the Mirasvit_Helpdesk::helpdesk_ticket ACL resource. Activities are a read-only audit trail of actions recorded against helpdesk entities.
| Method | URL | Description |
|---|---|---|
| GET | /V1/helpdesk/activities | Returns a filtered, sorted, paginated list of activity records. |
Response object — ActivityInterface
| Attribute | Data Type | Description |
|---|---|---|
| id | Int | The ID of the activity record. |
| external_id | String | External identifier of the related entity, if applicable. |
| kind | String | The kind/type of the activity. |
| timestamp | String | Date and time the activity occurred. |
| user_id | Int | ID of the admin user (agent) who triggered the activity, if applicable. |
| title | String | Short title of the activity. |
| description | String | Full description of the activity. |
| url | String | URL linking to the related entity, if available. |
| payload | Array | Additional structured data associated with the activity. |
GET /V1/helpdesk/activities returns an ActivitySearchResultsInterface with items (array of ActivityInterface), search_criteria, and total_count.
History
Requires the Mirasvit_Helpdesk::helpdesk_ticket ACL resource. History records the change log of a ticket (status/priority/department changes, assignments, and similar system events) and is read-only through this API.
| Method | URL | Description |
|---|---|---|
| GET | /V1/helpdesk/history | Returns a filtered, sorted, paginated list of ticket history records. |
Response object — HistoryInterface
| Attribute | Data Type | Description |
|---|---|---|
| history_id | Int | The ID of the history record. |
| ticket_id | Int | The ID of the ticket the history record belongs to. |
| triggered_by | String | Indicates who/what triggered the event (e.g. customer, admin, system). |
| name | String | Short name of the event. |
| message | String | Full description of the event. |
| created_at | String | Date and time the event was recorded. |
GET /V1/helpdesk/history returns a HistorySearchResultsInterface with items (array of HistoryInterface), search_criteria, and total_count.
Attachments
Requires the Mirasvit_Helpdesk::helpdesk_ticket ACL resource. Attachments are read-only through this API — files are uploaded via the admin panel or an inbound email, not through this endpoint group.
| Method | URL | Description |
|---|---|---|
| GET | /V1/helpdesk/attachments | Returns a filtered, sorted, paginated list of attachments. |
| GET | /V1/helpdesk/attachment/{attachmentId} | Returns an attachment's metadata by ID. |
| GET | /V1/helpdesk/attachment/{attachmentId}/body | Returns an attachment's content. |
Response object — AttachmentInterface (used by getList and get)
| Attribute | Data Type | Description |
|---|---|---|
| attachment_id | Int | The ID of the attachment. |
| message_id | Int | The ID of the message the attachment is attached to. |
| email_id | Int | The ID of the source email, if the attachment arrived by email. |
| name | String | The file name of the attachment. |
| type | String | The MIME type of the attachment. |
| size | Int | The file size, in bytes. |
| external_id | String | External identifier of the attachment, if set by an integration. |
| storage | String | Storage backend the attachment's content is kept in. |
Response object — AttachmentBodyInterface (returned by getBody)
| Attribute | Data Type | Description |
|---|---|---|
| content | String | Plain text content for text-based files, or base64-encoded content for binary files. |
| encoding | String | Encoding of content (e.g. plain, base64). |
| name | String | The file name of the attachment. |
| type | String | The MIME type of the attachment. |
GET /V1/helpdesk/attachments returns an AttachmentSearchResultsInterface with items (array of AttachmentInterface), search_criteria, and total_count.
Quick Response Templates
Requires the Mirasvit_Helpdesk::helpdesk_ticket ACL resource. Quick response templates are read-only through this API.
| Method | URL | Description |
|---|---|---|
| GET | /V1/helpdesk/template/{templateId} | Returns a quick response template by ID. |
| GET | /V1/helpdesk/templates | Returns a filtered, sorted, paginated list of quick response templates. |
Response object — TemplateInterface
| Attribute | Data Type | Description |
|---|---|---|
| template_id | Int | The ID of the template. |
| name | String | The display name of the template. |
| template | String | The template body/content, including any placeholders. |
| is_active | Int | Whether the template is active (1) or disabled (0). |
| store_ids | Array of Int | The store views the template is available on. |
| created_at | String | Date and time the template was created. |
| updated_at | String | Date and time the template was last updated. |
GET /V1/helpdesk/templates returns a TemplateSearchResultsInterface with items (array of TemplateInterface), search_criteria, and total_count.