Zammad

1. Overview

Zammad is a web-based, open-source helpdesk and customer support system designed to manage customer communication from various channels like email, phone, and social media.

With the GoInsight Zammad node, you can seamlessly integrate your customer support operations into your automated workflows. This allows you to manage the entire lifecycle of key Zammad resources, including:

• Tickets: Create, retrieve, and delete support tickets.
• Users: Manage user accounts, including creation, retrieval, updates, and deletion.
• Groups: Organize your support agents by creating, listing, updating, and deleting groups.
• Organizations: Manage customer organizations within your Zammad instance.

2. Prerequisites

Before using this node, you need to have a valid Zammad account. You may also need administrator or specific permissions to generate the API credentials required for authentication.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Group, Organization, Ticket, and User.

Operation Details

Create a Group

Creates a new group in Zammad for organizing tickets and agents.

When to use:

• Set up new team or department groups
• Organize ticket routing by group
• Configure group-specific settings

Key points:

• Group name must be unique
• Assignment timeout controls auto-reassignment (0 = disabled)
• Follow-up setting controls if closed tickets can be reopened
• Active status controls if group accepts new tickets

[!] Important:

Inactive groups cannot receive new ticket assignments but existing tickets remain accessible.

[!] Idempotency:

Zammad does not enforce unique group names. Duplicate names will create separate groups. Use 'Get Many Groups' to check for existing groups with the same name before creating.

Don't use when:

• You want to update an existing group (use Update a Group)
• You want to list existing groups (use Get Many Groups)

Input Parameters:

• Name: Group name (must be unique within the Zammad instance). Used for ticket routing and agent assignment. Example: "Technical Support"

Options:

• Active: Whether the group is active. Inactive groups cannot receive new ticket assignments but existing tickets remain accessible. Set to false to disable without deleting.
• AssignmentTimeout: Assignment timeout in minutes (0 means no timeout)
• FollowUpPossible: Whether follow-up is possible: yes or no
• Note: Group note/description for internal reference. Visible to admins in Zammad group settings. Example: "Handles all billing and payment inquiries"
• Confirm: Set to true to execute the write operation. When false, the action validates parameters only and returns without making changes (dry-run mode). Default: true

Output:

• Group (object): Business data object containing the group details. Structure: Complete API response with all fields (id, name, active, assignment_timeout, follow_up_possible, note, created_at, updated_at). Returns empty object {} if operation failed (check ErrorMessage for reason).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Delete a Group

Deletes a group from Zammad. This action is idempotent and cannot be undone.

When to use:

• Remove a group that is no longer needed
• Clean up test or temporary groups

Key points:

• Idempotent: deleting an already-deleted group succeeds with a warning
• Safe to retry on timeout without causing errors
• GroupId can be obtained from Get Many Groups action
• Affected tickets will lose group assignment; users will lose group membership

[!] Important: Verify no active tickets are assigned to this group before deletion.

Don't use when:

• You only want to deactivate the group (use Update a Group with Active=false)
• The group still has active tickets assigned

Input Parameters:

• GroupId: Unique identifier of the group to delete. Can be obtained from Get Many Groups action or Zammad web interface. Deleting a non-existent group succeeds (idempotent). Example: 42

Output:

• DeletedGroup (object): Business data object containing the deletion result. Structure: {"deleted": true, "groupId": int} on success, empty object {} if operation failed (check ErrorMessage for reason). Idempotent: returns success even if group was already deleted.
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Groups

Retrieves a paginated list of groups from Zammad.

When to use:

• List all available groups
• Check group settings (assignment timeout, follow-up rules)
• Get group IDs for creating or assigning tickets

Key points:

• Returns groups wrapped in object with pagination metadata
• Pagination: use Limit and Offset, check has_more for next page
• Each group includes id, name, active status, and configuration
• Default returns up to 50 groups per request

Don't use when:

• You know the exact Group ID (use Get a Group for faster single retrieval)

Options:

• Limit: Maximum number of groups to retrieve per page. Must be a positive integer. Recommended range: 1-100. Default: 50.
• Offset: Number of groups to skip for pagination. Used for fetching subsequent pages. Example: Page 1 uses Offset=0, Page 2 uses Offset=50 (when Limit=50). Default: 0.

Output:

• Groups (object): Business data object containing the groups list and pagination metadata. Structure: groups (array of group objects with id, name, active, assignment_timeout, follow_up_possible, note, created_at, updated_at) and pagination (limit, offset, count, has_more). Returns empty object {} if operation failed. Core fields: id (int), name (string), active (bool), assignment_timeout (int), follow_up_possible (string), note (string), created_at (string, ISO 8601), updated_at (string, ISO 8601).
• Summary (string): One-line summary of the result for Agent context efficiency. Includes count, pagination status, and next-page hint. Empty string on failure.
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get a Group

Retrieves complete information for a specific Zammad group by ID.

When to use:

• Fetch a group's configuration before updating tickets or routing rules
• Validate whether a group is active and supports follow-up behavior
• Inspect group metadata for admin audits or troubleshooting

Key points:

• Uses GET /api/v1/groups/{group_id} with token authentication
• Returns the full upstream group object without field filtering
• StatusCode follows unified rule (-1/200/500); check OriginalStatusCode for upstream HTTP result

Don't use when:

• You don't know the Group ID (use Get Many Groups to search first)

Input Parameters:

• GroupId: Group ID to retrieve. You can get Group IDs by calling Get Many Groups action or from the Zammad admin interface (Admin > Manage > Groups). Example: 1

Output:

• Group (object): Group information object containing: id (number) - Group unique identifier; name (string) - Group display name; active (boolean) - Whether the group is active; assignment_timeout (number|null) - Assignment timeout in minutes; follow_up_possible (string) - Whether follow-up is possible; follow_up_assignment (boolean) - Whether follow-up should be assigned; email_address_id (number|null); signature_id (number|null); note (string) - Group description or notes; created_at (string, ISO 8601); updated_at (string, ISO 8601); created_by_id (number); updated_by_id (number). Returns empty object {} if operation failed (check ErrorMessage for reason). Core fields: id (int), name (string), active (bool), assignment_timeout (int), follow_up_possible (string), note (string), created_at (string, ISO 8601), updated_at (string, ISO 8601).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Update a Group

Updates an existing group's configuration in Zammad.

When to use:

• Change group name, active status, or assignment rules
• Update follow-up settings or group notes
• Enable/disable a group without deleting it

Key points:

• Incremental update (PUT): only provided fields are updated, others keep original values
• GroupId is required, can be obtained from Get Many Groups action
• Returns the complete updated group object
• FollowUpPossible: "yes" (allow reopen) or "no" (create new ticket)
• AssignmentTimeout: minutes before auto-reassign, 0 to disable

Don't use when:

• You want to create a new group (use Create a Group)
• You want to delete a group (use Delete a Group)

Input Parameters:

• GroupId: Group ID to update. Can be obtained from Get Many Groups action or Zammad web interface (visible in group URL). Example: 5

Options:

• Name: Group name (must be unique within the Zammad instance). Leave empty to keep current name unchanged. Example: "Technical Support"
• Active: Whether the group is active. Inactive groups cannot receive new ticket assignments but existing tickets remain accessible. Set to false to disable without deleting.
• AssignmentTimeout: Assignment timeout in minutes. Controls how long a ticket can remain assigned before auto-reassignment. 0 = no timeout (disabled). Example: 30
• FollowUpPossible: Whether follow-up is possible after ticket is closed. "yes": allow reopening by replying. "no": create new ticket instead.
• Note: Group note/description for internal reference. Visible to admins in Zammad group settings. Leave empty to keep unchanged. Example: "Handles all billing inquiries"
• Confirm: Set to true to execute the write operation. When false, the action validates parameters only and returns without making changes (dry-run mode). Default: true

Output:

• Group (object): Updated group information object containing: id (int), name (str), active (bool), assignment_timeout (int), follow_up_possible (str: yes/no), note (str), created_at (str), updated_at (str). Returns empty object {} if operation failed.
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Create an Organization

Create a new organization in Zammad.

When to use:

• Register a new company or team in your Zammad helpdesk
• Set up domain-based customer assignment
• Organize customers into groups for shared ticket visibility

Key points:

• Name is the only required field
• Shared=true (default) lets members see each other's tickets
• Domain enables auto-assignment of new users by email domain
• Returns the complete organization object with id

[!] Important:

Zammad does not enforce unique names. Creating with the same name produces duplicates. Verify existence first using search if needed.

Next:

After creating, use "Get Many Organizations" to find by name or "Update an Organization" to modify details.

Don't use when:

• The organization may already exist (search with Get Many Organizations first)
• You want to update org info (use Update an Organization)

Input Parameters:

• Name: The name of the organization to create. Must be a non-empty string. This is the primary display name visible in the Zammad UI. Example: "Acme Corporation"

Options:

• Shared: Whether the organization is shared. When true (default), all customers in this organization can see each other's tickets. Set to false for VIP organizations that need ticket privacy. Example: true
• Domain: The email domain associated with this organization (e.g., "acme.com"). When set, new users with matching email domains are automatically assigned to this organization. Leave empty if not needed. Example: "acme.com"
• Note: Internal note or description for this organization. Supports plain text. Used for additional context visible to agents. Example: "Enterprise customer from Q1 onboarding"
• Confirm: Set to true to execute the write operation. When false, the action validates parameters only and returns without making changes (dry-run mode). Default: true

Output:

• Organization (object): Business data object containing the created organization details. Structure: Complete Zammad API response with all fields (id, name, shared, domain, domain_assignment, note, active, member_ids, created_by_id, updated_by_id, created_at, updated_at). Returns empty object {} if operation failed (check ErrorMessage for reason).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Delete an Organization

Permanently deletes an organization from Zammad. This action cannot be undone.

When to use:

• Remove an organization that is no longer needed
• Clean up test or duplicate organization records

Key points:

• Deletion is permanent and irreversible
• Associated tickets and users are NOT deleted but lose organization association
• Use Get Many Organizations to find the OrganizationId before deleting
• Verify no critical active tickets or users are associated before deletion
• Idempotent: returns success if organization already deleted (404 treated as successful deletion)

Don't use when:

• You only want to deactivate the organization
• The organization has active members

Input Parameters:

• OrganizationId: Organization ID to delete. Must be a positive integer. Obtain via Get Many Organizations action, or from the Zammad admin panel URL (e.g., /organizations/42).

[!] Important: Associated tickets and users will NOT be deleted but will lose their organization association.

Example: 42

Output:

• DeletedOrganization (object): Business data object containing the deletion result. Structure: {"deleted": true, "organizationId": int} on success, empty object {} if operation failed (check ErrorMessage for reason).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Organizations

Retrieves a paginated list of organizations from Zammad with optional search.

When to use:

• List organizations for downstream ticket or user assignment workflows
• Search organizations by name/domain before selecting a target record
• Iterate through organization pages in batch synchronization jobs

Key points:

• Uses GET /api/v1/organizations with limit, offset, and optional search
• Returns full upstream organization payload without field filtering
• Includes pagination hints (returned_count, has_more) and unified status outputs

Don't use when:

• You know the exact Organization ID (use Get an Organization)

Options:

• Limit: Maximum number of organizations to retrieve per page. Default: 50. Recommended range: 1-100. Use smaller values (10-20) for UI display and larger values (50-100) for batch processing. If you need all organizations, use pagination by increasing Offset by Limit in each call until has_more=false.
• Offset: Number of organizations to skip for pagination. Default: 0 (start from the first record). For example, to get the second page with Limit=50, set Offset=50; to get the third page, set Offset=100. Use with Limit for page-by-page retrieval.
• Search: Search keyword to filter organizations by name or domain. Supports partial matching (case-insensitive). Example: "Acme" will match "Acme Corp", "ACME Inc", etc. Leave empty to retrieve all organizations.

Output:

• Organizations (object): Business data object containing organization list results. Structure: {"organizations": , "pagination": {"limit": number, "offset": number, "returned_count": number, "has_more": boolean}}. The organizations payload preserves all fields returned by Zammad without filtering. Returns empty object {} if operation failed (check ErrorMessage for reason). Core fields: id (int), name (string), shared (bool), domain (string), domain_assignment (bool), active (bool), note (string), member_ids (array of int), created_at (string, ISO 8601), updated_at (string, ISO 8601).
• Summary (string): One-line summary of the result for Agent context efficiency. Includes count, pagination status, and next-page hint. Empty string on failure.
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get an Organization

Retrieves complete information for a specific organization by ID.

When to use:

• Get organization details before updating
• Check organization domain and shared status
• Verify organization exists before assigning to tickets

Key points:

• OrganizationId is required and must be a positive integer
• Use Get Many Organizations to find organization IDs
• Returns full organization object (id, name, shared, domain, note, active, timestamps)

Don't use when:

• You don't know the Organization ID (use Get Many Organizations to search)

Input Parameters:

• OrganizationId: Organization ID to retrieve. This is a unique numeric identifier assigned by Zammad. You can obtain Organization IDs by:
• Using Get Many Organizations action to list all organizations
• Checking the organization field in ticket or user objects

Example: 123

Output:

• Organization (object): Business data object containing the organization details. Structure: Complete API response with all fields (id, name, shared, domain, note, active, created_at, updated_at, created_by_id, updated_by_id, etc.). Returns empty object {} if operation failed. Core fields: id (int), name (string), shared (bool), domain (string), domain_assignment (bool), active (bool), note (string), member_ids (array of int), created_at (string, ISO 8601), updated_at (string, ISO 8601).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Update an Organization

Updates an existing organization in Zammad by ID. Only provided fields are updated; omitted optional text fields retain current values.

When to use:

• Rename an organization or adjust organization-level sharing settings
• Maintain organization domain and notes used in ticket/user workflows
• Correct organization metadata during admin maintenance

Key points:

• Uses PUT /api/v1/organizations/{organization_id} with token authentication
• Returns the full updated organization object without field filtering
• Only non-empty Name/Domain/Note are sent; Shared is always sent
• StatusCode follows unified rule (-1/200/500); check OriginalStatusCode for upstream HTTP result

Don't use when:

• You want to create a new organization (use Create an Organization)
• You want to delete an organization (use Delete an Organization)

Input Parameters:

• OrganizationId: Organization ID to update. This is the unique identifier of the organization in Zammad. You can obtain organization IDs through Get Many Organizations action. Example: 123

Options:

• Name: Organization name. Example: "Acme Corporation". Leave empty to keep the current name unchanged.
• Shared: Whether the organization is shared among multiple users. When true, all users can access this organization's data. When false, only permitted users have access. Default: true
• Domain: Organization domain (e.g., company website domain). Format: plain domain name without protocol or path. Example: "acme.com" (not "https://acme.com" or "acme.com/path"). Leave empty to keep unchanged.
• Note: Organization description or internal notes. Example: "Main customer organization for enterprise accounts". Leave empty to keep unchanged.
• Confirm: Set to true to execute the write operation. When false, the action validates parameters only and returns without making changes (dry-run mode). Default: true

Output:

• Organization (object): Business data object containing updated organization details returned by Zammad. Core fields include: id (number), name (string), shared (boolean), domain (string), note (string), active (boolean), created_at (string, ISO 8601), updated_at (string, ISO 8601), created_by_id (number), updated_by_id (number). Returns empty object {} if operation failed (check ErrorMessage for reason).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Create a Ticket

Creates a new support ticket in Zammad with customer information and initial article.

When to use:

• Create customer support tickets
• Log incoming requests or issues
• Initialize ticket workflows

Key points:

• Requires valid GroupId and CustomerId (use Get Groups/Customers to find IDs)
• Article is the first message/note in the ticket
• Priority: 1=low, 2=normal, 3=high, 4=urgent
• State: 1=new, 2=open, 3=pending reminder, 4=pending close, 5=closed

[!] Important:

The API token's user must have 'ticket.agent' or 'admin' role and access to the specified group.

[!] Idempotency:

Each call creates a new ticket regardless of identical content. There is no built-in duplicate detection. Callers should track ticket numbers or use title-based search via 'Get Many Tickets' to avoid duplicates.

Don't use when:

• You want to update an existing ticket's status or priority
• You only need to add a note to an existing ticket

Input Parameters:

• Title: Ticket title/subject. Brief description of the issue or request that will be displayed in the ticket list. Example: 'Email delivery failure', 'Password reset request'
• GroupId: Group ID to assign the ticket to. Determines which team will handle this ticket. Use 'Get Many Groups' action to find available group IDs. Example: 1 (for 'Users' group), 2 (for 'Support' group)
• CustomerId: Customer/user ID who created the ticket. This identifies the ticket requester in Zammad. Use 'Get Many Users' action to find customer IDs. Example: 5 (customer user ID)
• ArticleSubject: Subject of the first article/message in the ticket. This is the initial communication subject line. Example: 'Initial report', 'Customer inquiry about email issues'
• ArticleBody: Body/content of the first article/message. This is the detailed description of the issue or request. Supports plain text or HTML format. Example: 'Customer reports that emails are not being delivered since yesterday.'

Options:

• PriorityId: Priority level of the ticket. Determines urgency and handling order. Values: 1 (low priority), 2 (normal priority, default), 3 (high priority), 4 (urgent). Default: 2. Example: 2
• StateId: Initial state of the ticket. Determines the ticket's workflow status. Values: 1 (new, default), 2 (open), 3 (pending reminder), 4 (pending close), 5 (closed), 6 (merged). Default: 1. Example: 1
• AdditionalFields: Additional fields for extended ticket/article configuration (key-value pairs). Supported fields: article_type (string) - Communication channel type, options: email (default), note, phone, chat, web, sms, twitter status, twitter direct-message, facebook feed post, facebook feed comment; article_internal (bool) - Whether the article is internal (only visible to agents), default false. Example: {"article_type": "note", "article_internal": true}
• Confirm: Set to true to execute the write operation. When false, the action validates parameters only and returns without making changes (dry-run mode). Default: true

Output:

• Ticket (object): Business data object containing the ticket details. Structure: Complete API response with all fields (id, title, group_id, customer_id, state_id, priority_id, article, created_at, updated_at). Returns empty object {} if operation failed (check ErrorMessage for reason).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Delete a Ticket

Permanently deletes a ticket from Zammad by ticket ID.

When to use:

• Remove invalid or duplicate tickets created by mistake
• Clean up temporary or test tickets in controlled environments
• Execute administrative data cleanup workflows

Key points:

• Uses DELETE /api/v1/tickets/{ticket_id} with token authentication
• Deletion is irreversible; consider closing tickets instead when audit history is required
• Returns DeletedTicket object with deletion status and ticket ID on success
• Idempotent: returns success if ticket already deleted (404 treated as successful deletion)
• StatusCode follows unified rule (-1/200/500); check OriginalStatusCode for upstream HTTP result

Don't use when:

• You want to close a ticket (update state to closed instead)
• You need to preserve ticket history for audit

Input Parameters:

• TicketId: Ticket ID to delete (positive integer). You can get ticket IDs from Get Many Tickets, Get a Ticket, or Create a Ticket actions. Example: 123. Deletion is irreversible.

Output:

• DeletedTicket (object): Business data object containing ticket deletion result. On success, includes deleted (boolean), ticket_id (number), and upstream_response (full API response body when upstream returns content). Returns empty object {} if operation failed (check ErrorMessage for reason).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Tickets

Retrieves a paginated list of tickets from Zammad with optional state and priority filtering.

When to use:

• List all tickets in the system
• Filter tickets by state (new, open, closed)
• Filter tickets by priority level

Key points:

• Use Limit and Offset for pagination (check has_more in meta for next page)
• State values: "new", "open", "pending reminder", "pending close", "closed"
• Priority values: "1 low", "2 normal", "3 high"
• Returns tickets wrapped in object with pagination metadata

Don't use when:

• You know the exact Ticket ID (use Get a Ticket)
• You need full-text search across ticket content

Options:

• Limit: Maximum number of tickets to retrieve per page. Must be a positive integer.

Example: 50

• Offset: Number of tickets to skip for pagination. Used to retrieve subsequent pages.

Example: To get the second page with 50 tickets per page, set Offset=50.

Default: 0 (start from the first ticket)

• State: Filter tickets by state. Common values:
• "new": Newly created tickets
• "open": Tickets being processed
• "pending reminder": Awaiting reminder
• "pending close": Awaiting closure
• "closed": Completed tickets

Leave empty to retrieve all states. Example: "open"

• Priority: Filter tickets by priority. Zammad uses priority names:
• "1 low": Low priority
• "2 normal": Normal priority (default)
• "3 high": High priority

Leave empty to retrieve all priorities. Example: "2 normal"

Output:

• Tickets (object): Business data object containing the tickets list and pagination metadata. Structure: {"tickets": [{id, title, group_id, customer_id, state_id, priority_id, created_at, updated_at, ...}], "meta": {limit, offset, count, has_more}}. Returns empty object {} if operation failed. Core fields: id (int), number (string), title (string), group_id (int), customer_id (int), owner_id (int), state_id (int), priority_id (int), article_count (int), created_at (string, ISO 8601), updated_at (string, ISO 8601).
• Summary (string): One-line summary of the result for Agent context efficiency. Includes count, pagination status, and next-page hint. Empty string on failure.
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get a Ticket

Retrieves complete information for a specific ticket by ID.

When to use:

• Get ticket details before updating or responding
• Check ticket status, priority, and assignment
• Verify ticket existence after creation

Key points:

• Returns full ticket object (title, state, priority, group, customer, timestamps)
• TicketId can be obtained from Get Many Tickets or Create a Ticket actions
• State IDs: 1=new, 2=open, 3=pending reminder, 4=closed, 5=merged
• Priority IDs: 1=low, 2=normal, 3=high

Don't use when:

• You need multiple tickets (use Get Many Tickets with filters)
• You don't know the Ticket ID (use Get Many Tickets to search)

Input Parameters:

• TicketId: Unique identifier of the ticket to retrieve. Can be obtained from Get Many Tickets or Create a Ticket actions. Example: 12345

Output:

• Ticket (object): Ticket information object containing: id (int), title (str), group_id (int), customer_id (int), state_id (int: 1=new, 2=open, 3=pending, 4=closed), priority_id (int: 1=low, 2=normal, 3=high), owner_id (int), created_at (str), updated_at (str), article_count (int), and other Zammad ticket fields. Returns empty object {} if operation failed. Core fields: id (int), number (string), title (string), group_id (int), customer_id (int), owner_id (int), state_id (int), priority_id (int), article_count (int), created_at (string, ISO 8601), updated_at (string, ISO 8601).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Create a User

Creates a new user in Zammad with the specified account information.

When to use:

• Onboard a new agent or customer into Zammad
• Provision user accounts programmatically
• Sync users from external systems to Zammad

Key points:

• Email must be unique across the Zammad instance
• Password is required for local authentication
• Common role IDs: 1 (Admin), 2 (Agent), 3 (Customer). Refer to Zammad admin panel for custom roles
• If a user with the same email exists, the existing user is returned

[!] Important:

This action checks for existing users by email before creating. If a match is found, the existing user is returned without creating a duplicate. This makes the action safe for retry operations.

Next:

After creating a user, use Update a User to modify roles or status, or Create a Ticket to assign tickets to this user.

Don't use when:

• The user already exists (check with Get Many Users first)
• You want to update user info (use Update a User)

Input Parameters:

• Firstname: User's first name. Used as the display name in Zammad. Example: "John"
• Lastname: User's last name. Combined with Firstname to form the full display name. Example: "Doe"
• Email: User's email address (must be unique)
• Password: User's login password. Required when creating a local account. Must meet Zammad's password policy (minimum 6 characters recommended). Example: "SecurePass123!"

Options:

• RoleIds: List of role IDs to assign to the user. Use Zammad admin panel to find available role IDs. Common roles: 1 (Admin), 2 (Agent), 3 (Customer). Example: [1, 2]
• Active: Whether the user is active. true = active (can log in), false = deactivated. Defaults to true.
• Confirm: Set to true to execute the write operation. When false, the action validates parameters only and returns without making changes (dry-run mode). Default: true

Output:

• User (object): Business data object containing the created user details. Core fields: id (int), firstname (str), lastname (str), email (str), active (bool), role_ids (list), created_at (str), updated_at (str). Returns empty object {} if operation failed (check ErrorMessage for reason).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Delete a User

Permanently deletes a user from Zammad. This action cannot be undone.

When to use:

• Remove a user account that is no longer needed
• Clean up test or duplicate user accounts

Key points:

• Deletion is permanent; historical tickets remain but show as deleted user
• System admin account (ID=1) typically cannot be deleted
• Use Update User (active=false) to deactivate instead of deleting
• Use Get Many Users to find the UserId before deleting
• Idempotent: returns success if user already deleted (404 treated as successful deletion)

Don't use when:

• You only want to deactivate the user (use Update a User with Active=false)
• The user has active tickets

Input Parameters:

• UserId: User ID to delete. Must be a positive integer. Obtain via Get Many Users action.

[!] Important: System admin account (ID=1) typically cannot be deleted. Consider using Update User to deactivate instead.

Example: 42

Output:

• DeletedUser (object): Business data object containing the deletion result. Structure: {"deleted": true, "userId": int} on success, empty object {} if operation failed (check ErrorMessage for reason).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Current User

Retrieves the current authenticated user profile from Zammad.

When to use:

• Verify which user account the current token belongs to
• Fetch user identity fields before downstream ticket/user workflows
• Validate token permissions during troubleshooting

Key points:

• Uses GET /api/v1/users/me with token authentication
• Returns the full upstream user object without field filtering
• StatusCode follows unified rule (-1/200/500); check OriginalStatusCode for upstream HTTP result

Don't use when:

• You need a specific user by ID (use Get a User)
• You need to list multiple users (use Get Many Users)

Output:

• User (object): Business data object containing the current user details. Structure: API full response object with all returned fields (id, firstname, lastname, email, login, active, role_ids, organization_id, created_at, updated_at, etc.). Returns empty object {} if operation failed (check ErrorMessage for reason). Core fields: id (int), login (string), firstname (string), lastname (string), email (string), active (bool), role_ids (array of int), organization_id (int), created_at (string, ISO 8601), updated_at (string, ISO 8601).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Users

Retrieves a paginated list of users from Zammad with optional search.

When to use:

• List users for assignment, routing, or approval workflows
• Search users by name, email, or login before selecting a target account
• Iterate through user pages in synchronization or audit jobs

Key points:

• Uses GET /api/v1/users with limit, offset, and optional search
• Returns full upstream user payload without field filtering
• Includes pagination hints (returned_count, has_more) and unified status outputs

Don't use when:

• You know the exact User ID (use Get a User)
• You need the current authenticated user (use Get Current User)

Options:

• Limit: Maximum number of users to retrieve per page. For example, set to 50 to get 50 users at a time. Default: 50.
• Offset: Number of users to skip for pagination. Used for fetching subsequent pages. For example: Page 1 uses Offset=0, Page 2 uses Offset=50 (assuming Limit=50), Page 3 uses Offset=100. Default: 0.
• Search: Search keyword to filter users by firstname, lastname, email, or login. Supports partial matching (case-insensitive). For example: 'john' will match users with firstname 'John', lastname 'Johnson', email 'john.doe@example.com', or login 'john.doe'. Leave empty to retrieve all users without filtering. Example: 'john'.

Output:

• Users (object): Business data object containing user list results. Structure: {"users": , "pagination": {"limit": number, "offset": number, "returned_count": number, "has_more": boolean}}. The users payload preserves all fields returned by Zammad without filtering. Returns empty object {} if operation failed (check ErrorMessage for reason). Core fields: id (int), login (string), firstname (string), lastname (string), email (string), active (bool), role_ids (array of int), organization_id (int), created_at (string, ISO 8601), updated_at (string, ISO 8601).
• Summary (string): One-line summary of the result for Agent context efficiency. Includes count, pagination status, and next-page hint. Empty string on failure.
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get a User

Retrieves detailed information about a specific user in Zammad by ID.

When to use:

• Get full user details before updating user profile
• Check user roles, permissions, and active status
• Verify user email and contact information

Key points:

• UserId is required, get it from Get Many Users
• Returns complete user object with all fields (id, firstname, lastname, email, role_ids, active, etc.)
• User must have appropriate permissions to view other user profiles

Don't use when:

• You don't know the User ID (use Get Many Users with search parameter)
• You need the currently authenticated user (use Get Current User)

Input Parameters:

• UserId: The unique identifier of the user to retrieve (required, positive integer).

How to get User ID:

• Use Get Many Users action to find users by criteria or list all users
• Copy from Zammad UI: User Profile -> URL contains user ID

Example: 42

Output:

• User (object): Business data object containing the user details. Structure: API's full response object with all fields (id, firstname, lastname, email, role_ids, active, created_at, updated_at, etc.). Returns empty object {} if operation failed (check ErrorMessage for reason). Core fields: id (int), login (string), firstname (string), lastname (string), email (string), active (bool), role_ids (array of int), organization_id (int), created_at (string, ISO 8601), updated_at (string, ISO 8601).
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

Update a User

Updates an existing user in Zammad. Only provided fields are updated; omitted fields retain their current values.

When to use:

• Update user profile (name, email)
• Change user role assignments
• Enable or disable user access
• Reset user password

Key points:

• Only fields with values are updated (partial update semantics)
• RoleIds replaces all current roles when provided
• Use Get Many Users to find the UserId
• Email must be unique across all users (422 error if duplicate)

Don't use when:

• You want to create a new user (use Create a User)
• You want to delete a user (use Delete a User)

Input Parameters:

• UserId: User ID to update. Obtain via Get Many Users action.

Example: 123

Options:

• Firstname: User's first name. Leave empty to keep the current value.

Example: "John"

• Lastname: User's last name. Leave empty to keep the current value.

Example: "Doe"

• Email: User's email address. Must be a valid email format. Used for login and notifications. If the email already exists for another user, the update will fail with a 422 error. Leave empty to keep the current value.

Example: "john.doe@example.com"

• RoleIds: List of role IDs to assign to the user. Each role ID must be a positive integer. Common role IDs:
• 1: Admin
• 2: Agent
• 3: Customer

Leave empty to keep the current roles. Example: [1, 2]

• Active: Whether the user is active. Set to false to disable login access without deleting data. Inactive users cannot log in but their tickets and history remain intact.

Default: true

• Password: User's new password. Use this to reset or update the user's password. After updating, the user must use the new password to log in. Leave empty to keep the current password.

Example: "NewSecureP@ss123"

• Confirm: Set to true to execute the write operation. When false, the action validates parameters only and returns without making changes (dry-run mode). Default: true

Output:

• User (object): Business data object containing the updated user details. Structure: Complete API response with all fields (id, firstname, lastname, email, active, role_ids, login, organization_id, phone, created_at, updated_at, etc.). Returns empty object {} if operation failed.
• Hint (string): Actionable next-step guidance for the Agent when an error occurs. Empty string on success. Starts with a verb (e.g., Retry, Re-authorize, Verify).
• Retryable (bool): Whether the Agent should retry with identical parameters. true for transient errors (timeout, rate limit), false for permanent errors (auth, validation, not found).
• OriginalStatusCode (number): The original HTTP status code returned by Zammad API. 0 if request did not reach the API (local validation error or network error).
• StatusCode (number): Operation status code. -1 for parameter validation error, 200 for request completed (check ErrorMessage for business errors), 500 for network/system errors (Agent may retry).
• ErrorMessage (string): Error details if any, empty string otherwise.

5. Example Usage

This section will guide you through creating a simple workflow to automatically create a new ticket in Zammad whenever the workflow is triggered.

The workflow will consist of three nodes: Start -> Zammad: Create a Ticket -> Answer.

1. Add the Zammad Node

• In your workflow canvas, click the + button to add a new node.
• Select the "Tool" tab in the pop-up panel.
• Find and select "Zammad" from the list of tools.
• From the list of supported operations for Zammad, click on "Create a Ticket" to add the node to your canvas.

2. Configure the Node

• Click on the newly added "Create a Ticket" node to open its configuration panel on the right.
• Credentials: In the "Credentials" field, click the dropdown menu and select your pre-configured Zammad credentials.
• Parameters: Fill in the required input parameters for creating a ticket.
  • Title: Enter a title for the new ticket, for example, New Customer Inquiry.
  • GroupId: Provide the numerical ID of the group you want to assign this ticket to. For instance, 1 for the "Users" group.
  • CustomerId: Enter the numerical ID of the customer who is reporting the issue. For example, 3.
  • ArticleSubject: Provide a subject for the initial article (message) of the ticket, such as Details of the inquiry.
  • ArticleBody: Write the main content of the ticket. For example, The customer reported an issue with their recent order..

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
• Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
• After a successful execution, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the ticket was created successfully.

After completing these steps, your workflow is fully configured. When run, it will create a new ticket in your Zammad instance with the specified details.

6. FAQs

Q: Why am I getting a 401 Unauthorized error?

A: This error typically indicates an issue with your credentials. Please check the following:

• Ensure your API token is correct and has not expired.
• Verify that the user associated with the API token has the necessary permissions in Zammad to perform the requested action (e.g., create tickets, manage users).

Q: How do I find the GroupId, CustomerId, or PriorityId?

A: These are numerical IDs specific to your Zammad instance. You can find them in a couple of ways:

• From the Zammad UI: Navigate to the specific item (e.g., a group or a user) in your Zammad dashboard. The ID is often visible in the URL of your browser.
• Using GoInsight: You can use the Get Many Groups or Get Many Users operations in a preceding step of your workflow to fetch a list of available resources and their corresponding IDs. You can then use the output of that node to dynamically provide the ID to the next node.

Q: My 'Create a Ticket' action is failing without a clear error. What should I check?

A: First, ensure all required fields (Title, GroupId, CustomerId, ArticleSubject, ArticleBody) are filled with valid data. A common issue is providing a GroupId or CustomerId that does not exist in your Zammad instance. Double-check that these IDs are correct and correspond to active groups and users.

7. Official Documentation

For more in-depth information about the Zammad API and its capabilities, please refer to the Zammad Official API Documentation.