> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FreshService ITSM

*This is the Freshservice **ITSM** integration: it logs Lumos access-request tickets to Freshservice and syncs user and entitlement information, but does not manage access. To create, deactivate, and delete Freshservice agents and manage their roles from Lumos, use [Freshservice Provisioning](/integrations/library/freshservice/freshservice-provisioning) instead. ITSM ticket logging is configured separately in your Lumos ITSM settings.*

## After this article

You will be able to connect Freshservice to Lumos, sync agents and their roles, track agent activity, and have Lumos log a ticket in Freshservice each time someone requests access to an app in the AppStore.

## Required plan and roles

* **Plan:** there is no minimum plan needed to connect the Freshservice integration.
* **Freshservice role:** the connecting user must be an **Account Admin** with access to the admin console. To confirm: **Settings → User Management → Roles** → under **Admin roles**, check you are listed as an agent for the **Account Admin** role.
* **Scopes** used by the integration:
  * `Default` (required): access to the endpoints documented in the Freshservice API
  * `agents.manage` (required): manage access to users and entitlements
  * `agents.roles.view` (required): view user roles
* **Permission scoping:** this integration syncs user and entitlement information and logs tickets. It does not create, update, or delete access. Provisioning is handled by the separate [Freshservice Provisioning](/integrations/library/freshservice/freshservice-provisioning) integration.

## Instructions

**Phase 1: Gather credentials in Freshservice**

1. Log in to Freshservice as an Account Admin.
2. Note your **domain name**: the part of your Freshservice URL before `freshservice.com` (for `https://companyname.freshservice.com`, the domain is `companyname`).
3. Find your **API Key**: open the Admin Panel, click your avatar in the top right, then click **Profile Settings**. The API Key is on the right-hand panel (you may need an additional confirmation step to copy it).

**Phase 2: Connect in Lumos**

1. Find the Freshservice card in your Lumos integrations (reconnect an existing card or add a new one).
2. Enter the domain name in the **Domain Name** field and paste your API key into the **API Key** field.
3. Click **Connect Freshservice**.

**Phase 3: Configure ITSM logging (optional)**

Set up ITSM logging so Lumos logs a ticket to Freshservice each time someone requests access to an app in the AppStore.

1. Go to your Lumos **ITSM settings**.
2. Choose **Freshservice** in the dropdown and click **Connect**.
3. Choose the sync you want to configure.
4. Specify the **Project**, **Request Type**, and **Resolve With** values:
   * **Project** maps to your Freshservice Groups.
   * **Request Type** shows the choices available for the **Category** ticket field.
   * **Resolve With** shows the choices available for the **Status** ticket field.
5. Click **Save**.

| Workflow action | Description |
| - | - |
| Create a ticket | When access is requested in the AppStore, Lumos creates a ticket in your configured Freshservice Group and Category, with Subject and Description per the ITSM Notification Reference, Status set to Open, Priority set to Medium, and Email set to the employee for whom access is requested |
| Comment on a ticket | When an access-request task is assigned or completed, Lumos adds a comment noting who made the decision |
| Resolve a ticket | When the access request completes, Lumos resolves the ticket, setting the Status to your configured **Resolve With** value |

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Connection fails with a valid API key:** Check the **Domain Name** field contains only the subdomain (e.g. `companyname`), not the full URL, and confirm the key was copied from **Profile Settings** of an Account Admin.

**Closing a Freshservice ticket doesn't complete the Lumos task:** Expected behavior. The Freshservice ITSM integration is one-directional (Lumos to Freshservice). Lumos creates the ticket, comments as the request progresses, and resolves it when the Lumos request completes, but status changes made in Freshservice do not flow back to Lumos. Native inbound/bidirectional status sync exists for Jira but not yet for Freshservice (on the roadmap). As a workaround today, you can use the Lumos public Tasks API to complete the matching task when a Freshservice ticket closes: `GET /tasks` (filtered by category/product\_area/status, with `show_all_tasks=true` using an admin token) to find the task by `target_user.email` plus app, then `POST /tasks/{task_id}/complete` (204 on success). Some caveats apply. The Lumos request UUID is not stamped on the Freshservice ticket, so correlation must parse requester email and app from the ticket body. Matching is ambiguous if a user has multiple open requests for the same app. Completing an already-complete task returns a 400 (`No available action transitions this task to COMPLETED`), so check status first.