Skip to content
Help Center
Submit a request Sign in

Plan and run a Zendesk import

The Zendesk importer migrates tickets and knowledge articles in separate runs with saved checkpoints and reconciliation. Separate previews help verify customer identity, routing, article audience and source-field mappings before cutover.

Applies to: Supportbench Core. Location: Settings → Integrations → Import from Zendesk. Import configuration requires Administer all integrations. Article runs additionally require Alter existing articles. Import topics requires Administer article topics and write access to each selected Division; No division requires global Article access.

Before you begin

  • Plan a controlled migration with known source counts, intended Divisions and test records. A Preview and a saved mapping do not start an import.
  • Prepare the Zendesk subdomain, Admin email and API token. Credentials are held in the server session, not saved mappings or progress; do not include them in screenshots or shared logs.
  • Review ticket and article permissions separately. Imported Topics start private, and each brand’s Division becomes locked after its Containers or Articles have imported.

Configure and verify

  1. Open Settings → Integrations → Import from Zendesk. Enter Zendesk subdomain, Admin email and API token, then choose Test connection and Discover source data.
  2. For Tickets, select Cases to import and First export date. Review defaults and optional mappings before starting.
  3. In Preview and progress, choose Tickets and Save mappings. Choose Preview, inspect the proposed results and resolve blockers. Saving mappings or previewing does not start the run.
  4. Choose Start ticket run only when ready. Keep the page open, monitor progress and use the offered pause/resume controls as needed. Export errors and reconciliation evidence to investigate partial results.
  5. For Articles, choose the source brand and destination Division. When Import topics is off, select an existing Container in the same Division. Review the brand-specific audience and placement.
  6. Save mappings and Preview the Articles path separately. Resolve permission and placement errors before starting its Article run. Verify that imported Topics remain private until deliberately configured for the intended audience.
  7. If the page closes, browser requests stop but saved checkpoints remain. Reopen the page, re-enter credentials and use Resume after reviewing the saved run. Do not assume closing the page undid imported records.
  8. Use a new scan/export date when changing the Case-status filter. Resume retains the original filter. After a run, inspect representative records and reconciliation before treating the migration as complete.

Settings reference

Connection and operating controls

SettingWhat it controlsHow to choose
Subdomain / Administrator email / API tokenConnects to the intended Zendesk account. The token is protected in the server session.Confirm the source account and use authorized migration credentials.
Test connection / Discover source dataChecks access and discovers source fields and brands.Review discovered data before selecting destinations.
Ticket status / First export dateAll/Open/Closed source scope and the initial scan date.Open groups New/Open/Pending/On hold; Closed groups Solved/Closed, independently of custom labels.
Ticket defaultsDivision, Issue, Priority, fallback Status/Queue and reply/note activity type.Choose valid destinations for unmatched source values.
Optional fields / Standard-only / MappingsControls the fields brought across and their destination mapping.Keep the needed source identity and data types clear.
Import topics / Brand divisionBuilds brand/category/section topics and assigns the brand’s division or No division.New imported topics start private; review audience before making content available.
Ticket run / Article runIndependent preview/start/resume/pause controls.Validate each content type separately.
Export errors / Export reconciliationProduces evidence for failed and reconciled records.Use the exports to resolve gaps before cutover.

Behavior to know

  • Closing the page stops requests while checkpoints remain. Re-enter credentials to resume.
  • Changing a ticket status filter applies to a new scan with its export date; a resumed run retains its original filter.
  • Article reruns update source text while retaining Supportbench placement, slug and tags. Restricted or confirmed draft/unavailable source content remains or becomes internal; connection errors alone do not change visibility.
  • The first export date uses the local day boundary.

Recommended use

  • Preserve the source export and migration evidence. Identify the selected run, source mode, mappings and saved checkpoint before continuing or retrying.
  • Reconcile representative customer matches, Case/activity visibility and failures before expanding the scope or updating existing records. A completed run counter alone does not establish a successful customer migration.
  • Plan the cutover and any follow-up run explicitly. Use this importer’s actual preview, run and recovery controls; do not treat it as a continuously synchronized integration with a generic removal action.

Worked example

  1. Connect, discover source data and choose a narrow ticket scope.
  2. Review defaults/mappings and preview tickets.
  3. Run and reconcile the ticket sample, including replies, notes, CCs and files.
  4. Preview article brands, locales and topics separately; review audience before running articles.

Troubleshooting

ProblemWhat to check
Preview or Start is rejectedCheck integration permission; for Articles also check Alter existing articles, Administer article topics when importing Topics, and write access to selected Divisions or global Article access for No division.
Connection was lost after reopeningRe-enter credentials for the server session, then inspect the saved checkpoint and Resume rather than starting an unreviewed duplicate run.
A changed Case-status filter is ignored on ResumeResume keeps the original filter. Plan a new scan/export date for changed selection criteria.
A brand cannot move to another DivisionIts Division locks after its Containers or Articles have imported. Investigate the recorded placement before attempting another run.
Imported Topics are not publicTopics created by import begin private. Publication/audience verification is a separate deliberate step.
A later ticket run did not overwrite local owner or stateLater runs add missing conversations/files while preserving local status, owner and Queue. This avoids overwriting subsequent support work.
Article text updated but placement did notArticle reruns preserve local placement, slug and tags while updating imported text. Verify each kind of result separately.
  • Integrations → Use the data synchronization log
  • Organization → Configure agent roles and division access

Was this article helpful?