Freshservice Import

Set up your API key

Create a dedicated integration agent with only the access the import needs, use its API key, and deactivate it when the load is done.

Why a separate agent

A Freshservice API key can do everything its agent can. If you paste your own key, and you're an administrator, the import could do anything you can. A dedicated agent with a narrow role limits what a mistake, or a leaked key, could ever touch.

Set it up

You need to be a Freshservice admin to do this. Menu names may differ slightly between Freshservice plans.

  1. Create a role. In Freshservice go to Admin → User Management → Roles → New Role, choose an agent role, and name it something like Bulk import. Give it only the permissions for the import types you'll run (see the table below), and leave everything else off.
  2. Create the agent. Go to Admin → User Management → Agents → New Agent. Use an address you control, such as bulk-import@yourcompany.com. Give it the role you just made, with the scope Across all groups in the service desk, so it can work on every ticket in the sheet. An agent normally uses a Freshservice licence while it's active.
  3. Add it to the right workspace if you use more than one, so the import can see that workspace's ticket form and catalog.
  4. Get its API key. Sign in to Freshservice as that agent (use a private browser window), open Profile settings, and copy the API key.
  5. Paste it into the tool and click Test connection & load workspaces. Then fetch the form or service item. If either gives a permission error, see Fix a 403.

The tool never stores the key on our servers. It's kept in the page while you work and forgotten when you reload, unless you tick Remember the API key until this tab is closed.

Permissions by import type

Permission names as they appear on the Freshservice role page. All need the scope Across all groups in the service desk.

What you're doingRole permissions
Connect and download a templateTickets: View tickets. Listing workspaces also needs the admin permission Manage workspace details and status; without it the tool uses the primary workspace.
New ticketsTickets: View tickets (this includes creating them).
Update and close ticketsTickets: View tickets and Edit ticket properties.
Close service requests with no descriptionAn Account Admin key. Freshservice won't close a ticket without a description, so the tool retries once skipping mandatory fields, which only an admin may do. Use a temporary admin agent just for this and deactivate it straight after.
RepliesTickets: View tickets and Reply to a ticket. Replies go out from your helpdesk to customers.
Service requestsTickets: View tickets, and the service catalog item must be visible to the agent.
Group and "Assigned to" checks (optional)Admin: View agents and agent groups. Without it the tool skips these checks and Freshservice reports any mismatch when sending.

Every Freshservice setup is a little different. Test with a few rows first, then widen the role only if Freshservice refuses something.

Fix a 403: "This API key doesn't have permission"

Freshservice answers 403 when the key works but its agent isn't allowed to do what was asked. The tool stops the run straight away, because every other row would fail the same way. Nothing in the stopped row was created.

  1. Check which import type you were running, and find it in the table above.
  2. In Freshservice, open the agent's role and add the missing permission. Check the agent's scope is Across all groups in the service desk, and that it's in the right workspace.
  3. Back in the tool, click Send next batch again. Rows already sent are skipped.

A 401 is different: the key itself is wrong or the agent is deactivated. Copy the key again from the agent's profile.

After the load

Questions? Contact support.