Front Migration Checklist

If you are preparing to migrate your support or shared inbox operations into Front, having a detailed checklist is essential. Front offers a robust API and flexible workspace model, but you only get a smooth migration when the environment is prepared well and when you understand what must be done through API and what must be configured manually.

This checklist walks you through the whole journey. The planning. The technical prep. The actual data move. The post-migration cleanup. And everything you must verify before agents start working full-time in Front.

Scope the migration

Get clear on the basics before touching any code. Rushing this part causes painful rework later.

Decide how many years of conversation history you are moving.
Identify how many active and inactive teammates need to exist in Front so ownership is mapped correctly.
Figure out which inboxes, tags, custom fields, conversation metadata, attachments, internal comments and message threads you need to preserve.
Decide what you want to drop. Old spam. Test messages. Dead contacts. Outdated tags.
Map old routing logic to Front's assignment model and "inboxes" structure.
Confirm API rate limits and estimate migration time. Front's API enforces per-endpoint rate limits — check the X-RateLimit-Limit and X-RateLimit-Remaining headers returned by each call to understand your throughput ceiling.
Estimate data volumes: total contacts, conversations, messages, and attachment sizes. Volume determines whether you need queuing, batching, or can run a straightforward sequential import.

Keep your scope document visible to everyone on your team. It avoids last-minute surprises.

What can be migrated via API vs. what requires the UI

The single most important thing to understand before building migration scripts is the boundary between what Front's API can handle and what must be configured manually in the UI. The table below maps every major resource type:

Resource	API	UI Only	Notes
Contacts & Companies	✅		`POST /contacts` — includes custom fields, company links, legacy IDs
Conversations & Messages	✅		`POST /conversations` via custom channels; messages added with `POST /messages`
Attachments	✅		Attached per-message; check Front's per-file size limit in their docs
Tags	✅		Applied to conversations programmatically
Custom Field Values	✅		Values set via API, but custom field definitions must be created in the UI first
Assignments & Participants	✅		Assign to teammates, add followers, set conversation status
Internal Comments	✅		Recreated in conversation timeline; @mentions may not trigger notifications on import
Custom Channels	✅		Used to attribute imported history to a dedicated source
Rules / Integrations	Partial	Partial	Webhooks and some plugin config via API; automation builder is UI-only
Channels & Connected Inboxes		✅	Email, IMAP, Google, Microsoft, SMS, WhatsApp, social — all manual
Teammates, Roles & Permissions		✅	Must invite and assign roles before referencing in migration scripts
Shared Inboxes & Team Structure		✅	Members and visibility rules configured by hand
Automation Rules		✅	Auto-assign, keyword routing, escalations, tagging logic
Message Templates (Canned Responses)		✅	Saved replies created manually
Collaboration Settings		✅	Mention behavior, collision detection, comment preferences
Signatures & Personal Preferences		✅	Per-agent: notifications, shortcuts, calendar integrations
Plugins & Integrations (install)		✅	CRM plugins, billing, third-party apps need UI confirmation

Key details on API-migratable resources

Contacts & Companies

Front's API lets you recreate your entire customer base. You can programmatically add contacts, update their details, attach custom fields and link them to companies. This means you can preserve old attributes like legacy IDs or notes and have every historical ticket point back to the right person or organisation.

Conversations & Messages

You rebuild whole conversations through the API by posting into a custom channel. Every message, reply, internal comment and timestamp can be recreated in the exact order it happened. Front treats imported conversations the same as live ones structurally — you get a clean, threaded history.

Attachments

The API allows you to add files to any message in the thread, keeping their proper names and formats. PDFs, logs, screenshots or inline images sit where they belong in the conversation. Check Front's documentation for per-attachment size limits before starting — oversized files will fail silently or return a 413 error.

Tags, Custom Fields & Metadata

If your old helpdesk relied heavily on labels or custom fields, you can bring all of that over. Tags can be applied to conversations, and custom metadata fields can store details like old ticket IDs, priorities or categories.

Important: Custom field definitions must be created via the Front UI before you can populate them via API. Build this into your setup sequence.

Assignments, Ownership & Participants

You can assign conversations to teammates, add participants or followers and place the conversation inside the correct shared inbox. Status values like open or archived can also be set through the API.

Comments, Mentions & Internal Notes

Private notes and internal discussions can be recreated. Mentions may not trigger notifications the way they do in live usage, but the historical comments will appear in the correct order inside the conversation timeline.

Custom Channels & Source Attribution

If you want imported history to come from a dedicated source, you can write everything into a custom channel. This makes it straightforward to trace which conversations were migrated and keeps reporting clean.

Rules & Integrations (Partially)

Not everything in Front's automation suite is API-driven. Integrations that rely on Front's plugin framework or webhook logic can be created or updated via API, but the full automation builder lives in the UI.

Setting Up Your Front Account Before Migration

Before you import data, get the target environment set up so the import lands into a clean, functional structure.

Create the Front account & configure core settings

Choose the right Front plan (features like shared inboxes, routing rules, analytics, custom objects) to match your expected usage. Some features — custom objects, advanced analytics — are only available on higher-tier plans.
Set up organisation settings: company name, timezone, default language, data residency (if applicable).
Invite key stakeholders (admins, lead agents). Decide who will own the migration process within Front.

Configure agents, teams & inboxes

Create all current active agents/teammates. If you plan to migrate inactive ones as owners of old tickets, create them too (or map to a "legacy owner" alias).
Set up shared inboxes (e.g., support@, sales@, billing@) in Front. Ensure forwarding or routing from those addresses is ready.
Create teams or groups if you segment by function (Support, Sales, Escalations). Map agent membership accordingly.
Provide each agent with a login and basic training so they are comfortable in Front before the cut-over.

Configure data schema: contacts, companies, custom objects

Create custom contact and company fields (to capture legacy IDs, account tier, source system fields).
If you use "companies" (accounts) in your helpdesk, replicate those in Front via contacts + company associations or via custom objects if you need richer modelling.
If your source system has entities that don't map to contact/company/conversation, plan to use Front's Custom Objects feature. (Front's API supports many resource types.)

Prepare channels and routing rules

Ensure all inbound channels are set up in Front: email, live chat, SMS/WhatsApp (if applicable) or API sources. Front documentation for Channels API indicates custom channel support.
Temporarily disable or modify routing/automation rules that would trigger on imported old data (avoid flooding agents or customers).
Decide when you'll switch email forwarding from old system to Front shared inboxes at go-live.

Disable notifications and test import path

Turn off outgoing customer notifications for imported history (you don't want customers alerted about old tickets during import).
Run a small pilot import: import e.g., 100 contacts + 50 tickets + few attachments. Confirm mapping, data accuracy, attachments appear correctly, the right team and agent assignment.
Validate the import handling: message threading, contact assignment, timestamps, attachments, tags/status.

Migration Execution

Here's where it gets real. You'll run your main import, handle volume, monitor for errors, then cut over.

Import contacts and companies first. Once your contact base is in Front, conversations can reference them correctly.
Import conversations/messages: For each ticket in the source system you'll replicate as a Front conversation. Include all messages in the thread, attachments, status, participants, creation/close timestamps. Front's Core API supports creating and updating many relevant resources.
Import attachments with correct metadata so they attach properly to the conversation in Front.
Import old assignments: who owned the ticket, which team or inbox it belonged to. Map those to Front teammates/teams/inboxes.
Import tags, custom fields, rating history, and other metadata you decided were in scope.
Run delta import (see below) for all new tickets created after your main export cutoff and up to the moment of go-live.
Switch routing: update email forwarding/MX or routing rules so new requests land in Front rather than the old system.
Monitor API usage, errors, duplicates, failed imports. Maintain a log of any manual fixes required.
Communicate the cut-over: Let agents know when the system moves, when the old system is read-only, what to do in Front.

Delta import: closing the gap between export and go-live

The delta import is the step most teams underestimate. Between your initial data export and the moment you flip routing to Front, agents are still working in the old system. New tickets are created, existing tickets get replies, statuses change. If you don't capture that delta, you go live with missing conversations.

Here's how to handle it:

Record the exact timestamp of your main export cutoff. Every source system stores a created_at or updated_at timestamp on tickets. This is your filter boundary.
Re-export from the source system using that timestamp filter. Pull all tickets where created_at >= cutoff OR updated_at >= cutoff. The first catches new tickets; the second catches replies or status changes on existing ones.
Deduplicate against what's already in Front. If you stored the source ticket ID as a custom field (you should), query Front's API to check which conversations already exist. Only import net-new tickets and append new messages to existing conversations.
Run the delta as close to go-live as possible. The shorter the window between delta import and routing switch, the fewer conversations slip through. Ideally, the delta runs within the same hour you flip routing.
Verify the delta. After import, compare the count of tickets created in the source system during the delta window against what landed in Front. Any mismatch means a missed conversation.

Teams that skip this step or do it carelessly are the ones who discover missing tickets two weeks after go-live when a customer references a conversation that doesn't exist in Front.

Post-Migration Checklist

Once the data is loaded and agents are working in Front, it is time to validate, optimise and go live fully.

Data verification

Compare counts: contacts, companies, conversations, messages, attachments in Front vs source system.
Perform random spot checks: open a ticket in the source system and verify the conversation chain appears the same in Front (sender/recipient, timestamps, attachments, status).
Verify contact/company associations, custom fields.
Check that attachments open correctly.
Confirm teammates and teams are visible and have correct permissions.
Confirm conversation status is correct (open, closed, snoozed, archived) and that it lands in the correct shared inbox.

Channel testing & agent workflows

Test each inbound channel: email, chat, SMS/WhatsApp (if applicable). Create full new conversation and follow through resolution.
Verify outbound replies send correctly, and inbound replies thread cleanly in Front.
Agents should test assignment, tagging, internal comments, team handoffs in Front.
Ensure forwarding, auto-reply, SLA notifications (if applicable) are working as expected.

Automation, routing and workflows

Re-enable routing rules: auto-assign based on tags, keywords, team, channel.
Test workflow automations: status changes, tagging, notifications, escalations.
Validate custom steps and internal macros/templates. Front allows rule-based automation and API-driven integrations.

Agent setup & adaptation

Ensure each agent has correct role and permissions. Check what they see: their inboxes, shared inboxes, folders, tags.
Provide training: how Front differs from old system, how to use features like internal comments, collaboration with teammates, assigning, snoozing, archiving.
Encourage agents to set personal preferences: notification settings, signatures, integrations.

Final cleanup & go-live

Once you're confident, disable the old helpdesk system or set it to read-only to avoid duplicate tickets.
Reactivate all customer notifications that were turned off for import.
Start full live operations inside Front.
Schedule a review in 1 week and in 1 month to check performance, user feedback, missing tickets, workflow issues.
Collect agent feedback: what's working in Front, what gaps remain, iterate.

Common Migration Failures and How to Avoid Them

Failure	What happens	How to prevent it
Missing delta tickets	Conversations created between export and go-live never reach Front. Agents and customers reference tickets that don't exist.	Run delta import using timestamp filtering (see delta import section above). Verify counts before flipping routing.
Orphaned conversations from agent mapping errors	If a source agent isn't created in Front or is mapped to the wrong teammate, their conversations land unassigned or under the wrong owner. Agents lose context; SLAs break.	Create all agents in Front — including inactive ones — before importing. Map source agent IDs to Front teammate IDs in a lookup table and validate it before running the import.
Oversized attachments failing silently	Large files or inline images exceed Front's per-file limits. The API may return an error or silently drop the attachment, leaving conversations incomplete.	Check Front's attachment size limits before importing. Log every attachment import response. After import, compare attachment counts per conversation against the source.
Custom field data imported before definitions exist	If you try to set custom field values via API before creating the field definitions in the UI, the API call fails or the data is ignored.	Always create custom field definitions in the Front UI first. Then populate values via API. Include this as a blocking prerequisite in your setup checklist.
Automation rules triggering on imported data	If routing rules or auto-assign logic is active during import, old tickets get routed to agents, trigger SLA timers, or fire customer notifications.	Disable all automation rules and customer-facing notifications before starting the import. Re-enable them only after import is verified.

Additional tips

Labels/tags vs shared inboxes: In Front, how you use shared inboxes, tags, folders matters a lot for how agents view work. Think about the user view early.
Training is as important as the import. Even the best data import fails if agents don't know how the target system works. Front has a collaboration-centric workflow (shared inboxes, team comments) which may differ significantly from older "ticket system" workflows.
Monitor API rate limits: Front's API returns rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) on every response. Your migration scripts must read these headers and implement exponential back-off when limits are approached. Ignoring this causes 429 errors that stall or corrupt imports.
Clean up before import: If the source system has many unused tags/custom fields or duplicate contacts, run a clean-up phase first. It simplifies the target schema in Front.
Keep the old system accessible (read-only) for some period post-go-live so agents can reference historic tickets if something didn't migrate perfectly.
Handle edge cases explicitly: Conversations with no assignee should be routed to a catch-all inbox or tagged for manual review. Deleted or deactivated agents in the source system need a mapping decision — either recreate them as inactive teammates or reassign their conversations to a "legacy" placeholder.

Planning a migration?