HaloPSA

1. Overview

HaloPSA is a comprehensive Professional Services Automation (PSA) platform designed for Managed Service Providers (MSPs) and IT service desks. It centralizes operations, including service desk management, project management, billing, and customer relationship management.

With the GoInsight Halopsa node, you can seamlessly integrate your service management tasks into automated workflows. This allows you to manage the entire lifecycle of key resources within HaloPSA directly from your workflows, including:

• Client Management: Create, retrieve, update, and delete client records.
• Site Management: Manage sites associated with clients, including creation, retrieval, updates, and deletion.
• Ticket Handling: Automate the creation, retrieval, updating, and deletion of service tickets.
• User Administration: Manage user accounts, including creating, finding, updating, and deleting them.

2. Prerequisites

Before using this node, you must have a valid Halopsa account. You may also need administrative privileges or specific API permissions within your HaloPSA instance to generate and manage the necessary credentials 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 the following core resources: Client, Site, Ticket, and User.

Operation Details

Create a Client

Creates a new client record in HaloPSA.

When to use:

• Create a new customer account
• Onboard VIP clients
• Create branch or subsidiary clients

Key points:

• Uses OAuth2 Client Credentials authentication
• Supports on-premise and Halo-hosted deployments
• Request body is an array with one client object
• AdditionalFields supports extended properties and numeric IDs

Input Parameters:

• Name: Client name to be created. This is the primary identifier for the client in HaloPSA. Required field. Example: "Acme Corporation"

Options:

• Inactive: Account status switch. false = active account (default), true = suspended account. Keep false in normal cases; set true only when you need to suspend the client.
• Notes: Additional notes or description for the client
• IsVip: Whether the client is a VIP customer. VIP clients receive: higher priority in ticket queue, faster response time SLA, and access to premium support features. Default: false. Set to true for high-value customers requiring priority service.
• Website: Client website URL. Must include protocol (http:// or https://). Valid formats: https://www.acme-corp.com, http://acme.com/about, http://legacy-system.local. Invalid formats: www.acme.com (missing protocol), acme.com (missing protocol). Examples: "https://www.acme-corp.com" or "http://legacy-system.local".
• Email: Primary contact email address for the client. Used for ticket notifications and client communications. Example: "contact@acme-corp.com". Note: If email is also provided in AdditionalFields, this explicit Email parameter takes precedence.
• Phone: Primary contact phone number for the client. Include country/area code when possible. Example: "+1 415 555 0123". Note: If phone is also provided in AdditionalFields, this explicit Phone parameter takes precedence.
• AdditionalFields: Advanced option for extra client properties not exposed as direct inputs. Most users can leave this empty. Common fields: - toplevel_id (number): Parent client ID for branch/subsidiary setup - default_currency_code (number): Billing currency ID (for example 1=USD, 2=EUR, 3=GBP) - taxable (boolean): Taxable flag - pritech (number): Primary technician ID - sectech (number): Secondary technician ID - accountsid (string): External accounting system reference. Type rules: - Many extended fields require numeric IDs, not names. - Get parent client ID via Get_Many_Clients. - Confirm final field list and IDs in your HaloPSA Swagger endpoint. Example: {"toplevel_id": 15, "default_currency_code": 1, "taxable": true}

Output:

• Client (object): Business data object containing the created client details. Core fields: - id (number): Client unique identifier - name (string): Client name - inactive (boolean): Account status - is_vip (boolean): VIP status - website (string): Website URL - email (string): Primary contact email - phone (string): Primary contact phone - created_at (string): Creation timestamp (ISO 8601). Nested field site_update (array): Auto-created or existing site records linked to this client. Each item may include id, name, client_id, and optional fields such as address, phone, main_contact when configured. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 Client

Permanently deletes a client record from HaloPSA by client ID.

When to use:

• Remove obsolete or duplicate client records
• Clean up test data from the system
• Decommission clients that are no longer active

Key points:

• Id parameter is required (must be a positive integer)
• Client ID can be obtained from Get Many Clients action
• Requires OAuth2 authentication with admin permissions

DANGER - This operation CANNOT BE UNDONE:

• Permanently deletes the client record from HaloPSA
• Associated data handling:
  • Sites: May be orphaned or deleted (depends on configuration)
  • Tickets: May remain but lose client association
  • Contacts: May be orphaned or deleted
  • Behavior depends on your HaloPSA system settings
• Verify the correct Client ID before execution
• Consider backing up or reassigning records before deletion
• Contact administrator if unsure about cascade behavior

Next steps:

Verify deletion by calling Get a Client with same ID (should return 404).

Input Parameters:

• Id: Client ID to be deleted. Must be a positive integer. How to get Client ID: - Call Get Many Clients or Get a Client action to query - Check the client list in HaloPSA admin dashboard. Example: 123. ⚠️ WARNING: This operation permanently deletes the client and CANNOT BE UNDONE.

Output:

• DeleteResult (object): Deletion operation result object with the following structure: { "success": boolean, // Whether the deletion was successful "deleted_id": number // The ID of the deleted client (0 if failed) } Success scenario: {"success": true, "deleted_id": 123} Failure scenario (e.g., client not found): {"success": false, "deleted_id": 0} Note: Even when operation fails, this object maintains its structure with success=false and deleted_id=0. When StatusCode is 200 but ErrorMessage is not empty, check DeleteResult.success and ErrorMessage for failure details.
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA API. 0 if request did not reach the API (local validation error or network error). Use for debugging.
• 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. Contains specific error reason when operation failed (e.g., 'Client with ID 123 not found').

Get Many Clients

Retrieves a paginated list of clients from HaloPSA with filtering and search capabilities.

When to use:

• List all clients in your HaloPSA account
• Search for specific clients by name, email, or contact info
• Filter clients by active/inactive status
• Export client data for reporting or analysis

Key points:

• Requires OAuth2 credentials (ClientId, ClientSecret, AuthUrl, ResourceApiUrl)
• Search uses partial match across client name, email, and contact fields
• Filter by status: set IncludeActive=true and IncludeInactive=false to get only active clients (default behavior)
• Pagination: use PageNo and PageSize to retrieve large datasets (max 100 per page recommended)
• Returns client objects with id, name, is_active, client_type, email, phone, and timestamps
• Set Count parameter to limit total results returned

Important:

If both IncludeActive and IncludeInactive are false, the API returns an empty list.

Options:

• Count: Limit the number of clients returned
• PageNo: Current page number for pagination
• PageSize: Number of records per page
• Paginate: Whether to enable pagination
• Search: Search keyword to filter clients. Searches across client name, email, and contact information. Uses partial match (contains). Leave empty to return all clients. Example: 'Acme' will match 'Acme Corp', 'Acme Industries', etc.
• IncludeActive: Include active clients in results. Default: true. Note: If both IncludeActive and IncludeInactive are false, the API will return an empty list.
• IncludeInactive: Include inactive clients in results. Default: false. Note: If both IncludeActive and IncludeInactive are false, the API will return an empty list.

Output:

• Clients (object): Business data object containing client list and metadata. Structure: {"clients": [{client objects}], "record_count": number}. Each client object contains: id (unique identifier), name (client/company name), is_active (status), client_type, email, phone, created_date, last_modified. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 Client

Retrieves detailed information of a client from HaloPSA by client ID.

When to use:

• Get complete details of a specific clien
• Verify client information before performing operations
• Check client status (active/inactive, VIP status)

Key points:

• Id parameter is required (must be a positive integer)
• Client ID can be obtained from Get Many Clients or Search Clients actions
• Requires OAuth2 authentication with read permissions
• Returns complete client object with all available fields

Important notes:

• Returns 404 error if client ID does not exist
• Inactive clients are still retrievable (check inactive field)
• VIP status is indicated by is_vip field

Next steps:

Use the returned Client object fields (id, name, is_vip, etc.) in downstream workflow nodes.

Input Parameters:

• Id: Client ID to retrieve information. Must be a positive integer. How to get Client ID: - Call Get Many Clients action (returns a list of clients with their IDs) - Call Search Clients action (search by name or other criteria) - Check HaloPSA web interface (visible in client detail page URL). Example: 12345

Output:

• Client (object): Client detailed information object, including: - id (int): Client unique identifier - name (str): Client name - inactive (bool): Account status, false=active, true=inactive - is_vip (bool): VIP status - notes (str): Notes and remarks - website (str): Website URL - phone (str): Contact phone number - email (str): Contact email address - toplevel_id (int): Top-level organization ID - client_to_invoice (str): Invoicing entity name
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA API. 0 if request did not reach the API (local validation error or network error). Use for debugging.
• 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. Contains specific error reason when operation failed (e.g., 'Client with ID 12345 not found').

Update a Client

Updates an existing HaloPSA client.

When to use:

• Update client name, status, notes, VIP flag, or website.
• Apply a partial update without resubmitting unchanged fields.
• Check the updated client in later HaloPSA steps.

Key points:

• Id is required; only provided fields are updated.
• Updatable fields: Name, Inactive, Notes, IsVip, Website.
• Leave Inactive and IsVip empty to keep current values.
• Phone and email are read-only here; use Update a Site or Update a User when applicable.
• Required permissions/scopes: admin, edit:tickets, edit:customers.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

No updatable fields = StatusCode -1.

Next:

Use Client.id with Get a Client to verify the latest values, or with Update a Client for another partial update.

Input Parameters:

• Id: Client ID to update. Must be a positive integer. How to get Client ID: - Call Get Many Clients or Get a Client action to query - Check the client list in HaloPSA admin dashboard - View client detail page URL in HaloPSA web interface. Example: 12345

Options:

• Name: Client name to update. Leave empty to keep the current value. Example: "Acme Corporation"
• Inactive: Client account status. Set true to mark the client inactive, or false to mark it active. Leave empty to keep the current value.
• Notes: Additional notes for the client. Leave empty to keep the current value. Example: "Updated VIP status and account notes"
• IsVip: VIP flag for the client. Set true or false to update the VIP status. Leave empty to keep the current value.
• Website: Client website URL. Leave empty to keep the current value. Example: "https://www.acme-corp.com"

Output:

• Client (object): Business data object containing the updated client details. Updatable fields (via this action): - name (string): Client name - inactive (bool): Account status - notes (string): Additional notes - is_vip (bool): VIP status - website (string): Website URL. Read-only fields (returned by API): - id (int): Client ID - toplevel_id (int): Top-level organization ID - client_to_invoice (string): Invoicing name - phone (string): Contact phone returned by API - email (string): Contact email returned by API. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 Site

Creates a HaloPSA site.

When to use:

• Add a new location to an existing client.
• Create a site before assigning users or tickets.
• Reuse the returned site in later HaloPSA actions.

Key points:

• Name and SiteClientId are required.
• DuplicateCheckFields defaults to ["name", "client_id"].
• BlockIfDuplicate defaults to true; set false only for intentional duplicates.
• MaincontactName, Notes, and Phonenumber are optional.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Required permissions/scopes: admin, edit:tickets, edit:customers. This action creates data immediately. If BlockIfDuplicate=true and a duplicate is found, the action returns the existing Site instead of creating a new record.

Next:

Use Site.id with Get a Site to confirm the record. Use Site.client_id with Get a Client for parent details.

Input Parameters:

• Name: Site name to be created
• SiteClientId: Client ID that this site belongs to. The client must exist in HaloPSA before creating a site. How to get Client ID: - Call Get Many Clients or Get a Client action to query - Check the client list in HaloPSA admin dashboard. Example: 123

Options:

• MaincontactName: Main contact person name
• Notes: Additional notes or description for the site
• Phonenumber: Contact phone number. Supports international format with country code. Examples: - International: "+44-20-7123-4567" - US format: "+1-555-0100" - Local: "020-7123-4567"
• BlockIfDuplicate: Whether to stop creation when a duplicate site is found. Default: true. Set false to create the site even if DuplicateCheckFields finds an existing match. Example: true
• DuplicateCheckFields: Fields to check for duplicates before creating the site. Default: ["name", "client_id"] prevents duplicate site names within the same client. Set to empty array [] to disable duplicate checking. Example: ["name", "client_id"]

Output:

• Site (object): Created site object containing the following core fields: - id (number): Unique site identifier - name (string): Site name - client_id (number): Associated client ID - maincontact_name (string): Main contact person name - notes (string): Site notes or description - phonenumber (string): Contact phone number - postcode (string): Postal code - inactive (boolean): Whether the site is inactive. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 Site

Permanently deletes a HaloPSA site by ID.

When to use:

• Remove a duplicate, test, or retired site record.
• Delete a site only after confirming it should no longer exist.
• Run a controlled cleanup for one site.

Key points:

• Id is required and must be a positive integer.
• Get the site ID from Get Many Sites, Get a Site, the HaloPSA admin panel, or the URL.
• Required permissions/scopes: admin, edit:tickets, edit:customers.
• Do not use for bulk cleanup or when the site may still have active tickets or assets.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

This operation cannot be undone. Example failure: missing Site ID 12345 returns DeletedSite.success=false and ErrorMessage='Site with ID 12345 not found.'

Next:

Use DeletedSite.deleted_id with Get a Site to confirm the site is no longer available.

Input Parameters:

• Id: Site ID to delete. Must be a positive integer. How to get Site ID: - Call Get Many Sites action to list sites - Call Get a Site action when you already know a related site reference - Check the HaloPSA admin dashboard or site detail URL. Example: 12345

Output:

• DeletedSite (object): Delete result object. Core fields: - success (bool): Whether the deletion succeeded - deleted_id (int): The target site ID. On API, business, or network failure, returns success=false and echoes the requested site ID in deleted_id. Returns empty object {} only when the request stops at local parameter validation.
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 Sites

Retrieves a list of sites from HaloPSA with pagination and filtering support.

When to use:

• List all sites in your HaloPSA instance
• Search sites by name or keyword
• Filter sites by active/inactive status
• Get sites for specific client
• Export site data for reporting

Key points:

• Pagination: Count (total limit), PageSize (per page), PageNo (page number)
• Filter by active/inactive sites
• Search by site name
• All parameters have default values
• Returns site details: id, name, client info, contact details

Options:

• Count: Maximum total records to return (across all pages). Use this to limit the overall result set. Example: Set to 50 to get at most 50 sites total, regardless of pagination. Different from PageSize which controls records per page.
• PageNo: Current page number (starts from 1). Use with PageSize to retrieve specific pages. Example: PageNo=2 with PageSize=100 returns sites 101-200.
• PageSize: Number of records per page. Controls how many sites are returned in each API call. Example: PageSize=100 means each page contains up to 100 sites. Use with PageNo to navigate through results.
• Paginate: Whether to enable pagination. - true (default): Returns results in pages (controlled by PageSize). Use PageNo to navigate through pages. Recommended for large datasets. - false: Returns all matching records in one request (ignores PageSize and PageNo). May be slow if there are many sites. Use only when you need the complete dataset at once.
• Search: Search keyword to filter sites
• IncludeActive: Whether to include active sites in results. Active sites are currently operational and can be assigned to tickets. Default: true (include active sites).
• IncludeInactive: Whether to include inactive sites in results. Inactive sites are closed or archived and typically cannot be assigned to new tickets. Default: false (exclude inactive sites).

Output:

• Sites (object): [Object Structure] Sites data object containing: - sites (array): List of site objects, each with id, name, client_id, client_name, is_active, address, phone, main_contact - record_count (number): Total number of records matching the filter. Access paths: - First site: Sites.sites[0] - Total count: Sites.record_count. Returns empty object {} if operation failed.
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 Site

Retrieves detailed information of a specific site from HaloPSA.

When to use:

• Get complete site details by site ID
• Retrieve site contact information and phone number
• Check site status (active/inactive)
• View site address and client association

Key points:

• Id parameter is required (must be a positive integer)
• Returns complete site details including client information
• Uses OAuth2 Client Credentials authentication
• Business errors return StatusCode 200, check ErrorMessage and OriginalStatusCode

Next steps:

Use the site information to update records or display in your application.

Input Parameters:

• Id: Site ID to retrieve information. Must be a positive integer. How to get Site ID: - Call Get Many Sites action to query all sites - Call Get a Client action (sites are listed under client) - Check the site list in HaloPSA admin dashboard - View site detail page URL in HaloPSA web interface. Example: 456

Output:

• Site (object): Business data object containing the site details. Core fields include id, name, client_id, clientsite_name, maincontact_name, notes, phonenumber, inactive, address1, and postcode. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA API. 0 if request did not reach the API (local validation error or network error). Use for debugging.
• 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. Contains specific error reason when operation failed (e.g., 'Site with ID 456 not found').

Update a Site

Updates an existing site in HaloPSA by site ID.

When to use:

• Correct or rename an existing site
• Re-assign a site to another client
• Update contact person, notes, or phone number

Key points:

• Id is required; other fields are optional
• Uses OAuth2 authentication
• Returns complete updated site object on success

Update strategy (PATCH-like):

• String fields (Name, MaincontactName, Notes, Phonenumber): updated only when non-empty values are provided
• SiteClientId: updated only when value is greater than 0
• Fields not provided keep their existing values

Input Parameters:

• Id: Site ID to update. Must be a positive integer. You can obtain Site IDs from: - Get Many Sites action - Search Sites action - HaloPSA site detail URL. Example: 456

Options:

• Name: Site name to update
• SiteClientId: Client ID to associate with the site
• MaincontactName: Main contact name
• Notes: Additional notes or description for the site
• Phonenumber: Contact phone number

Output:

• Site (object): Updated site information object, including: - id (int): Site unique identifier - name (str): Site name - client_id (int): Associated client ID - maincontact_name (str): Main contact name - notes (str): Site notes - phonenumber (str): Contact phone number - clientsite_name (str): Combined client-site display name - inactive (bool): Whether site is inactive. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 HaloPSA ticket and returns the created record.

When to use:

• Log a new incident, service request, or problem ticket in HaloPSA.
• Create a ticket with assignment, requester, priority, or schedule fields.
• Pass the created ticket to follow-up ticket actions.

Key points:

• TickettypeId, Summary, and Details are required.
• AgentId, PriorityId, CategoryId, and UserId are optional inputs.
• Provide site_id, startdate, targetdate, or custom fields through AdditionalFields.
• Required permissions/scopes: admin, edit:tickets, edit:customers.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Ticket creation writes data immediately. Verify TickettypeId and any related IDs before execution.

Next:

Use Ticket.id with Get a Ticket to confirm full details, or with Update a Ticket to modify the new ticket.

Input Parameters:

• TickettypeId: Ticket type ID. Common types: 1-Incident (urgent faults), 2-Change Request (planned changes), 3-Service Request (standard service), 4-Problem (root cause analysis), 16-Leaver Request, 17-New Starter Request.
• Summary: Short summary of the issue or request. Example: "Laptop screen flickering issue"
• Details: Detailed description including symptoms, scope, and context. Example: "User reports intermittent screen flicker when opening multiple applications. Issue started 2 days ago. Laptop model: Dell XPS 15."

Options:

• AgentId: Assigned technician ID for this ticket. You can obtain IDs from Get Many Users action or the HaloPSA admin panel. Leave empty for auto-assignment by HaloPSA rules. Example: 42
• PriorityId: Priority ID for urgency routing. You can obtain IDs from your HaloPSA priority configuration or the admin panel. Leave empty to use the default priority logic. Example: 3
• CategoryId: Category ID for classification, such as Hardware, Software, or Network categories. You can obtain IDs from HaloPSA ticket category settings or the admin panel. Leave empty to use the default category. Example: 12
• UserId: Reporter user ID associated with this ticket. You can obtain IDs from Get Many Users action or the HaloPSA admin panel. Optional but recommended for end-user tracking. Example: 105
• AdditionalFields: Additional ticket fields (key-value pairs). Use this for less common fields or fields moved out of the main input list. Common additional fields: - site_id (number): Site ID for multi-site organizations. Obtain from Get Many Sites action or the HaloPSA admin panel. - startdate (string): Ticket start datetime in ISO 8601 format (e.g., "2025-01-15T10:00:00Z") - targetdate (string): Target completion datetime in ISO 8601 format (e.g., "2025-01-17T18:00:00Z") - tags (string): Comma-separated tags - Custom fields defined in your HaloPSA instance. Example: {"site_id": 15, "startdate": "2025-01-15T10:00:00Z", "targetdate": "2025-01-17T18:00:00Z", "tags": "urgent,hardware"}

Output:

• Ticket (object): Business data object containing the created ticket details. Core fields: - id (int): Ticket unique identifier - summary (string): Ticket summary - details (string): Detailed description - tickettype_id (int): Ticket type ID - tickettype_name (string): Ticket type name - agent_id (int): Assigned agent ID - agent_name (string): Agent name - status_id (int): Status ID - status_name (string): Status name - priority_id (int): Priority ID - priority_name (string): Priority name - user_id (int): Reporter user ID - site_id (int): Site ID - startdate (string): Start datetime (ISO 8601) - targetdate (string): Target datetime (ISO 8601) - dateoccurred (string): Creation datetime (ISO 8601). Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 HaloPSA by ticket ID.

When to use:

• Remove invalid or duplicate tickets
• Clean up test tickets from production workspace
• Delete tickets that should not be retained

Key points:

• This operation is irreversible and cannot be undone
• Id must be a positive integer from search/list/get actions
• Uses OAuth2 authentication for both on-premise and Halo-hosted deployments

Input Parameters:

• Id: Ticket ID to delete. You can obtain Ticket IDs from: - Search Tickets action (search by keywords) - Get Many Tickets action (list all tickets) - HaloPSA web interface URL (e.g., https://your-instance.halopsa.com/tickets/12345). [!] WARNING: This deletion is permanent and cannot be undone. Verify the correct ID before proceeding. Example: 12345

Output:

• DeletedTicket (object): Deletion result object with the following structure: { "success": boolean, // Whether deletion succeeded "deleted_id": number // Ticket ID targeted by this delete request } Success example: {"success": true, "deleted_id": 12345} Failure example: {"success": false, "deleted_id": 12345} When StatusCode is 200 but ErrorMessage is not empty, treat it as a business failure and check this object together with ErrorMessage.
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 HaloPSA with filtering and search capabilities.

When to use:

• List all support tickets in your HaloPSA account
• Search for specific tickets by summary or details
• Filter tickets by active/inactive status
• Export ticket data for reporting or analysis

Key points:

• Requires OAuth2 credentials (ClientId, ClientSecret, AuthUrl, ResourceApiUrl)
• Search uses partial match across ticket summary and details
• Filter by status: IncludeActive=true for open tickets, IncludeInactive=true for closed tickets
• Pagination: use PageNo and PageSize to retrieve large datasets (max 100 per page)
• Count parameter limits total results across all pages
• Returns ticket objects with id, summary, details, status_id, priority_id, user_name, site_name, and timestamps

Important:

If both IncludeActive and IncludeInactive are false, the API returns an empty list.

Options:

• Count: Total limit of tickets to return across all pages. Example: Count=50 means return at most 50 tickets in total, regardless of pagination. Default: 50. Note: This is different from PageSize (records per page).
• PageNo: Current page number for pagination
• PageSize: Number of records per page. Example: PageSize=100 means each page contains up to 100 tickets. Default: 100. Note: Total returned tickets are limited by Count parameter.
• Paginate: Whether to enable pagination
• Search: Search keyword to filter tickets. Searches across ticket summary and details. Uses partial match (contains). Supports simple keywords (e.g., 'email issue') or multiple keywords separated by spaces. Leave empty to return all tickets. Example: 'email access'
• IncludeActive: Include active (open/in-progress) tickets in results. Active tickets are those not yet closed or resolved. Default: true. Note: If both IncludeActive and IncludeInactive are false, the API will return an empty list.
• IncludeInactive: Include inactive (closed/resolved) tickets in results. Inactive tickets are those marked as completed or archived. Default: false. Note: If both IncludeActive and IncludeInactive are false, the API will return an empty list.

Output:

• Tickets (object): Business data object containing ticket list and metadata. Structure: {"tickets": [{ticket objects}], "record_count": number}. Each ticket object contains: id (unique identifier), summary (ticket title), details (description), status_id (current status), priority_id (priority level), user_name (requester), site_name (location), dateoccurred (creation time), category_1/category_2 (categories). Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 detailed information for a specific ticket by ID from HaloPSA.

When to use:

• Get ticket details (status, priority, assignment) before updating
• Check ticket progress or resolution status
• Look up ticket requester, agent, or site information

Key points:

• Returns ticket with all fields (summary, details, status, priority, agent_id, dates)
• Id must be a positive integer obtained from Search Tickets or Get Many Tickets
• Returns empty object {} if ticket not found (check ErrorMessage)

Input Parameters:

• Id: Ticket ID to retrieve detailed information. Must be a positive integer (e.g., 12345). You can obtain Ticket IDs from: - Search Tickets action (search by keywords) - Get Many Tickets action (list all tickets) - HaloPSA web interface URL (e.g., https://your-instance.halopsa.com/tickets/12345)

Output:

• Ticket (object): Ticket detailed information object, including: - id (int): Ticket unique identifier - summary (str): Ticket title/summary - details (str): Detailed description - status (str): Current status (e.g., Open, In Progress, Closed) - priority (object): Priority info with id and name - agent_id (int): Assigned agent ID - tickettype_id (int): Ticket type ID - startdate (str): Start date (ISO 8601) - targetdate (str): Target resolution date - user_name (str): Requester name - site_name (str): Site/location name. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 Ticket

Updates an existing HaloPSA ticket.

When to use:

• Change ticket type, assignment, summary, details, or ticket dates.
• Update non-core ticket fields through AdditionalFields.
• Keep unchanged fields untouched while changing only selected values.

Key points:

• Update strategy: only filled fields are changed; empty fields keep current values.
• Id is required; all other direct inputs are optional.
• Use AdditionalFields for fields such as priority_id, status_id, category_id, team_id, slaresponse, or slafix.
• Required permissions/scopes: admin, edit:tickets, edit:customers.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

No update field = StatusCode -1.

Next:

Use Ticket.id with Get a Ticket to verify the latest values, or with Update a Ticket for another partial update.

Input Parameters:

• Id: Ticket ID to update. Must be a positive integer. You can obtain Ticket IDs from: - Search Tickets action (search by keywords) - Get Many Tickets action (list all tickets) - HaloPSA web interface URL (e.g., https://your-instance.halopsa.com/tickets/12345). Example: 12345

Options:

• TickettypeId: Ticket type ID (this controls how HaloPSA routes and handles the ticket). Common types: - Incident (1): Unexpected fault or service interruption, such as a network outage or system crash - Service Request (3): Standard request, such as a password reset or access request - Change Request (2): Planned system change, such as a software upgrade or configuration update - Problem (4): Root cause investigation for recurring incidents. Leave empty to keep current ticket type.
• Summary: Ticket summary to update. Leave empty to keep current value.
• Details: Ticket detailed description to update. Leave empty to keep current value.
• AgentId: Assigned agent or technician ID. You can obtain IDs from Get Many Users action or the HaloPSA admin panel. Leave empty to keep current assignment. Example: 67
• Startdate: Start date in ISO 8601 format. Must include both date and time. Format: YYYY-MM-DDTHH:MM:SS. Example: 2025-10-30T10:00:00. Leave empty to keep current value.
• Targetdate: Target date in ISO 8601 format. Must include both date and time. Format: YYYY-MM-DDTHH:MM:SS. Example: 2025-11-05T18:00:00. Leave empty to keep current value.
• AdditionalFields: Additional ticket fields (key-value pairs) for non-core updates. Common fields: - priority_id (number): Priority ID - status_id (number): Status ID - category_id (number): Category ID - team_id (number): Team ID - slaresponse (string): SLA response target - slafix (string): SLA fix target. Leave empty to keep current values. Example: {"priority_id": 2, "status_id": 5, "team_id": 10}

Output:

• Ticket (object): Updated ticket information object, including: - id (int): Ticket unique identifier - summary (str): Ticket title or summary - details (str): Detailed description - status (str): Current status, such as "Open", "In Progress", or "Closed" - priority (object): Priority information with common fields id (int) and name (str) - agent_id (int): Assigned agent ID - tickettype_id (int): Ticket type ID - startdate (str): Start date in ISO 8601 format - targetdate (str): Target resolution date in ISO 8601 format - user_name (str): Requester name - site_name (str): Site or location name. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 account in HaloPSA with site assignment and optional password.

When to use:

• Add new employees to the system
• Create user accounts for ticket management
• Set up users with site access

Key points:

• Name and SiteId are required
• Password must meet complexity rules (8+ chars, mixed case, numbers/symbols)
• User is active by default (Inactive=false)
• Site ID determines organization site assignment

Important notes:

• No welcome email sent by default
• New users have no permissions, admin must assign roles
• Password stored encrypted, cannot be viewed after creation

Next steps:

Use Update a User action to modify user information or reassign sites.

Input Parameters:

• Name: User name (required). Can be full name or first name. Naming suggestions: - Western names: Name='John', Surname='Doe' - Chinese names: Name='Zhang San' or Name='San', Surname='Zhang' - Single name: Fill Name only, leave Surname empty. Example: "John Doe" or "Zhang San"
• SiteId: Associated site ID. Used to assign the user to a specific organization site. How to get Site ID: - Call Get Many Sites or Get a Site action to query - If your organization has only one site, Site ID is usually 1 - Check the site list in HaloPSA admin dashboard. Example: 1

Options:

• Emailaddress: User email address
• Surname: User surname
• Notes: Additional notes or description for the user
• Password: User login password (optional). If not provided, user cannot login and admin must reset password. Password rules: - At least 8 characters - Must contain uppercase letters (A-Z) - Must contain lowercase letters (a-z) - Must contain numbers or symbols (0-9 or !@#$%^&*). Examples: SecureP@ss123, MyP@ssw0rd! [!] Important: Password is stored encrypted and cannot be viewed after creation.
• Inactive: User status setting. - false (default): Activate user, can login and use system normally - true: Deactivate user, cannot login but historical data is preserved. Usually keep default value false, only set to true when creating temporarily disabled accounts.

Output:

• User (object): Created user object containing the following core fields: - id (number): User unique identifier - name (string): User name - surname (string): User surname - site_id (number): Associated site ID - emailaddress (string): Email address - notes (string): Notes information - inactive (boolean): Whether deactivated (false=active, true=deactivated) - is_vip (boolean): Whether VIP user. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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

⚠️ WARNING: Permanently deletes a user record from HaloPSA. This operation CANNOT BE UNDONE.

When to use:

• Remove a user who has left the organization
• Clean up test or duplicate user records
• Permanently delete a user account (consider using Update_a_User with Inactive=true to disable instead)

Key points:

• ⚠️ IRREVERSIBLE: Deleted users cannot be recovered
• Verify the correct User ID before execution (use Get_a_User to confirm)
• Consider disabling (Inactive=true) instead of deleting to preserve data
• HaloPSA may return HTTP 500 with empty body on successful deletion (known API behavior, handled correctly)

Input Parameters:

• Id: User ID to be deleted. Must be a positive integer. You can obtain User IDs by calling Get Many Users or Get a User action. Example: 12345

Output:

• DeletedUser (object): The deleted user information. Contains the deletion result with the following structure: - id (integer): The ID of the deleted user - deleted (boolean): Whether the user was successfully deleted. Returns empty object {} on failure.
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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). Note: HaloPSA may return HTTP 500 with empty body on successful deletion (this is a known API behavior, handled correctly).
• ErrorMessage (string): Error details if any, empty string otherwise.

Get Many Users

Retrieve multiple users from HaloPSA with pagination and filtering support.

When to use:

• Get a list of users with specific criteria (active/inactive status, search terms)
• Retrieve users in pages for large datasets
• Search users by name, email, or username

Key points:

• Requires OAuth2 authentication (client_id, client_secret, auth_url, resource_api_url)
• At least one of IncludeActive or IncludeInactive must be true
• Use Paginate=true for large datasets to avoid timeouts
• Search works across multiple user fields simultaneously

Options:

• Count: Maximum total records to return (across all pages). Use this to limit the overall result set. Example: Set to 50 to get at most 50 users total, regardless of pagination. Different from PageSize which controls records per page.
• PageNo: Current page number (starts from 1). Use with PageSize to retrieve specific pages. Example: PageNo=2 with PageSize=100 returns users 101-200.
• PageSize: Number of records per page. Controls how many users are returned in each API call. Example: PageSize=100 means each page contains up to 100 users. Use with PageNo to navigate through results.
• Paginate: Whether to enable pagination. - true (default): Returns results in pages (controlled by PageSize). Use PageNo to navigate through pages. Recommended for large datasets. - false: Returns all matching records in one request (ignores PageSize and PageNo). May be slow if there are many users. Use only when you need the complete dataset at once.
• Search: Search keyword to filter users. Searches across name, email, username and other user fields. Example: 'john' finds users with 'john' in name or email.
• IncludeActive: Include active users in results. Active users can log in and be assigned to tickets. At least one of IncludeActive or IncludeInactive must be true, otherwise returns empty result.
• IncludeInactive: Include inactive users in results. Inactive users cannot log in and typically cannot be assigned to new tickets. At least one of IncludeActive or IncludeInactive must be true, otherwise returns empty result.

Output:

• Users (object): [Object Structure] Users data object containing: - users (array): List of user objects, each with id, name, email, username, is_active, site_id, site_name, role, department, phone - record_count (number): Total number of records matching the filter. Access paths: - First user: Users.users[0] - Total count: Users.record_count. Returns empty object {} if operation failed.
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 for a specific user by ID from HaloPSA.

When to use:

• Get user details before updating
• Verify user site assignment and status
• Look up user email or contact info

Key points:

• Returns user with all fields (name, surname, email, site_id, inactive)
• Id must be a positive integer obtained from Get Many Users
• Returns empty object {} if user not found (check ErrorMessage)

Input Parameters:

• Id: User ID to retrieve information. You can obtain User IDs through Get Many Users action. If you know the user's email, you can search by email first to get the ID. Example: 123

Output:

• User (object): User detailed information object, including: - id (int): User ID - name (str): User first name - surname (str): User last name - emailaddress (str): Email address - site_id (int): Associated site ID - notes (str): User notes - inactive (bool): Whether the user is inactive - ... other fields returned by HaloPSA API. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 HaloPSA user and returns the updated record.

When to use:

• Change a user's profile fields such as name, email, site, notes, or password.
• Disable or re-enable a user account.
• Continue downstream actions with the updated user object.

Key points:

• Id is required; other fields are optional and only provided fields are sent.
• Leave Inactive empty to keep the current account status.
• Password changes must satisfy HaloPSA password policy.

[!] Important:

StatusCode -1 = parameter validation error. StatusCode 200 + empty ErrorMessage = success. StatusCode 200 + non-empty ErrorMessage = business/API error. StatusCode 500 = network/system error and is safe to retry.

Required permissions/scopes: admin, edit:tickets, edit:customers. Inactive=true disables login, so confirm the target user before changing access.

Next:

Use User.id with Get a User to confirm the latest profile. Use User.site_id with Get a Site if you need site details.

Input Parameters:

• Id: User ID to update. Can be obtained from Get Many Users or Get a User action. Example: 12345

Options:

• Name: User first name to update. Leave empty to keep current value. Example: "John"
• Surname: User last name to update. Leave empty to keep current value. Example: "Doe"
• SiteId: Site ID (organization location identifier) to reassign. Can be obtained from Get Many Sites action. Leave empty (0) to keep current site. Example: 101
• Emailaddress: User email address to update. Leave empty to keep current value. Example: "john.doe@company.com"
• Notes: Notes or remarks to update. Supports plain text. Leave empty to keep current value. Example: "Updated contact information for sales team"
• Password: User password to update. Must meet complexity rules: 8+ characters, mixed case, numbers or symbols. Leave empty to keep current password. Example: "NewSecureP@ss123"
• Inactive: User account status. false = active (can login), true = disabled (cannot login, data preserved). Leave empty to keep the current status. Only set to true when you need to disable the user account.

Output:

• User (object): Updated user information object. Core fields may include: - id (int): User ID - username (str): Login username - name (str): User first name - surname (str): User last name - emailaddress (str): Email address - site_id (int): Associated site ID - site_name (str): Site name - organisation_id (int): Parent organization ID - organisation_name (str): Parent organization name - department_id (int): Department ID - department_name (str): Department name - inactive (bool): Whether the account is disabled - is_important_contact (bool): Important contact flag - is_vip (bool): VIP flag - notes (str): User notes - colour (str): UI color code - created (str): Creation time in ISO 8601 format - modified (str): Last modification time in ISO 8601 format. See https://halopsa.com/api/users for additional HaloPSA user fields. Returns empty object {} if operation failed (check ErrorMessage for reason).
• OriginalStatusCode (number): The original HTTP status code returned by HaloPSA 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 incident ticket in HaloPSA whenever the workflow is triggered.

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

Step-by-Step Guide

1. Add the Tool Node:
   • In the workflow canvas, click the + button to add a new node.
   • In the pop-up panel, select the "Tools" tab.
   • Find and select "Halopsa" from the list of tools.
   • In the list of supported operations for Halopsa, click on "Create a Ticket". This will 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 Configuration: At the top of the panel, find the credentials field. Click the dropdown menu and select the Halopsa credential you have already configured.
   • Parameter Configuration: Fill in the required input parameters for creating a ticket.
   • TickettypeId: Select "Incident" from the dropdown list, or enter the numerical ID 1.
   • Summary: Enter a concise title for the ticket, for example, "Network printer is offline".
   • Details: Provide a more detailed description of the issue, such as "The main office printer on the 2nd floor is not responding to pings and cannot be accessed from any workstation."
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 executed, it will create a new incident ticket in your HaloPSA instance with the specified details.

6. FAQs

Q: I'm receiving a 401 Unauthorized error. What could be the cause?

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

• Correct Credentials: Ensure that the Client ID, Client Secret, and other details entered for your Halopsa credential in GoInsight are correct.
• Permissions: Verify that the API key or user associated with the credentials has the necessary permissions within HaloPSA to perform the requested action (e.g., create tickets, read clients).

Q: Why did my 'Create a User' action fail without a clear error message?

A: When creating a user, there are a few common silent failure points. Please verify the following:

• Valid SiteId: The SiteId you provided must correspond to an existing site in HaloPSA. An invalid ID will cause the request to fail.
• Password Complexity: If you are setting a password, ensure it meets HaloPSA's complexity requirements (e.g., minimum length, character types).
• Unique Email: The email address for the new user might already be in use within your HaloPSA instance.

7. Official Documentation

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