How to Import Tickets & Contacts into Freshdesk (CSV & API)

The two import jobs, and why they're different

Freshdesk splits imports along a hard line. Contacts and companies are handled by a built-in CSV importer you'll find right in the UI. Tickets are not — there is no menu button that ingests a CSV of past conversations. Per Freshworks' own importing and exporting customer data documentation, the native importer covers customer records only, and ticket import "is not supported natively through this CSV method."

That single fact shapes every migration. If all you need is a fresh contact list, the free importer does the whole job in a few minutes. If you're moving years of ticket history off another help desk, you're in API territory — either writing against Freshdesk's bulk-import endpoints yourself or paying a tool to do it for you. Most real migrations are a mix: CSV for people, API or a tool for tickets.

Route 1: Importing contacts and companies via CSV

The CSV importer is the easy win. It lives directly in the UI and gives you a mapping screen so your spreadsheet columns line up with Freshdesk fields.

1. Prepare a UTF-8 CSV with column headers in the first row. Freshdesk reads that header row to offer field mappings.
2. Make sure each contact has, at minimum, a name plus an email address or a name plus a phone number — records missing both pairs won't import.
3. Format every date field as YYYY-MM-DD, and write phone numbers with a country code (e.g. +14088481234, not 4088481234).
4. Pre-create any custom fields in Admin before you import — the mapper can only target fields that already exist.
5. Go to Contacts → Import, upload the file, map each column to a Freshdesk field on the mapping screen, and click Import. You'll get a status email when it finishes.

A few sharp edges worth knowing before you run it. Email is the unique key — if an imported row matches an existing contact's email, Freshdesk overwrites that contact rather than creating a duplicate, so a sloppy file can quietly clobber good data. Each contact can hold up to 10 email addresses (one primary, nine secondary). And contacts and companies import separately — there's no combined upload, so you run the Companies importer and the Contacts importer as two passes, companies first if you want the associations to resolve.

One non-obvious gotcha: Freshdesk requires at least 10 tickets to already exist in the account before it will let you import contacts. On a brand-new instance that means creating a handful of throwaway tickets first, then importing your people. It's an odd requirement, but it trips up first-time migrators constantly.

Route 2: Importing tickets via the bulk-import API

Because there's no CSV button for tickets, volume ticket history comes in through Freshdesk's Bulk Import API. This is a genuine engineering task, not a settings screen, so budget developer time accordingly. The endpoints accept JSON only and carry firm limits:

• A maximum of 50 tickets or notes per request — you batch your history into chunks.
• An account-level rate limit of 10 requests per minute, which caps throughput at roughly 500 records a minute in ideal conditions and means a large backlog takes hours, not seconds.
• A per-entity attachment ceiling of 40 MB; anything over that fails as a partial failure while the rest of the entity imports.
• Dependent entities must exist first — the agents and requesters a ticket references have to be created (via the contact import above, or the API) before the ticket that points at them will import cleanly.

When tickets do come through the API, they carry their Type, Status, Priority, Source, custom fields, requester, agent, and tags — the structured skeleton of each conversation. That's a lot of fidelity, but it's fidelity you have to script, map, and error-handle yourself.

Route 3: A paid migration tool (when volume or fidelity matters)

If you're moving off Zendesk, Gorgias, or another platform with tens of thousands of tickets and attachments, a dedicated migration service is usually the sane choice over hand-rolling the API. Tools like Help Desk Migration (by Relokia) automate the source-export, field-mapping, and API-import steps, preserve attachments and threading, and offer Delta migration to sync records created during the move — so you get near-zero downtime instead of a hard cutover. The trade is cost: these are premium, per-record-priced services, whereas the native CSV importer is free. We compare the landscape in more depth in the best Freshdesk migration tools, and if you're specifically coming from Zendesk, the Zendesk to Freshdesk migration guide walks that exact path.

What moves vs what you rebuild

This is the table to internalize before you start, because the disappointment in most migrations comes from assuming a clean CSV or a tool moves everything. It moves the data — not the logic that acts on it.

The pattern: records port, behavior rebuilds. Your customers and their conversations can travel; the SLA policies, automations, business hours, and reporting that operate on them are configuration you'll set up again in the new instance. Treat that rebuild as planned scope, not a nasty surprise — our Freshdesk migration checklist sequences it so nothing slips.

The honest bits: downtime, gaps, and the free-vs-paid line

A few realities worth stating plainly. Downtime is a choice you make. A native CSV job for contacts is fast and low-risk, but a raw-API ticket migration of any size runs for hours under that 10-requests-per-minute ceiling, and you have to decide whether to freeze the source system during the move or reconcile changes afterward. Paid tools soften this with Delta migration; the free path does not.

The free importer has real gaps. It handles people, not conversations; it doesn't touch attachments; and it silently overwrites contacts on matching emails. For a small team importing a clean list, none of that matters. For a data-heavy cutover, those gaps are exactly why the API and paid tools exist.

And the honest framing on tooling: the native importer is free but narrow, the bulk API is free but a build, and a migration service is paid but comprehensive. There's no universally right answer — it's a function of your volume, your engineering capacity, and how much history you actually need to preserve.

Once the data is in: an AI layer on top

Importing is the beginning, not the end. Once your tickets and contacts live in Freshdesk, the work becomes answering the new tickets that keep arriving — and that's where an AI agent layer fits, sitting on top of the Freshdesk you just populated rather than replacing it. The broader category of AI agents for customer service exists to do the reading-and-writing that a support queue demands at volume.

Macha is one such layer. It connects to the Freshdesk you already use as a native connector — you link it with your subdomain and API key, and it reads and writes the same tickets you just imported. It drafts or posts grounded replies, triages incoming tickets by intent, and can look up an order or account status through a custom tool that turns a REST API into something an agent can call. Because Macha runs on your live ticket data, a clean import directly improves what it can do — more history means better-grounded answers. If you want the full picture of automating the queue after you've moved in, see how to automate Freshdesk with AI.

Two things to keep straight: Macha's connector is for Freshdesk specifically — not Freshchat, Freshservice, or Freshcaller — and its credits are consumed per AI action, not per resolution, which the pricing page lays out. It doesn't replace your help desk or your imported data; it works on top of both.

FAQ

Can I import tickets into Freshdesk with a CSV? No. Freshdesk's native CSV importer only handles contacts and companies. To bring in ticket history you use the Bulk Import API (JSON, up to 50 records per request, 10 requests per minute) or a third-party migration tool that automates those API calls for you.

Why does Freshdesk say I need 10 tickets before importing contacts? Freshdesk requires at least 10 tickets to already exist in the account before it will run a contact import. On a fresh instance, create a few placeholder tickets first, then import your contacts.

Do contacts and companies import together? No — they're two separate imports. Run the Companies import first, then Contacts, so company associations resolve correctly. Both are UTF-8 CSVs with a header row and YYYY-MM-DD dates.

What data doesn't migrate into Freshdesk? Records (contacts, companies, tickets) move; behavior doesn't. Automations, SLA policies, business hours, macros, and historical reports all have to be rebuilt or reconfigured in the new instance. Attachments over 40 MB per entity also fail on the raw API.

Do I have to replace Freshdesk to add AI after importing? No. An AI agent layer like Macha connects to Freshdesk as a native connector and works on top of your imported tickets and contacts — drafting replies and triaging by intent — without replacing the help desk.

Once your data is home, help your team answer faster on top of it. Start a free trial of Macha and connect it to your Freshdesk in minutes.