Back to Home

Import & Export Coding Guides

Most institutional users already have a codebook — often years of refinement encoded in an Excel sheet. qualcode.ai ingests that file directly, so you don't have to retype categories one by one. This page walks through the full round-trip: import, optional LLM enrichment, download, and re-import.

The easy path is the fast path. A clean two-column list, a file with hierarchy rows, or a power-user file that explicitly labels each row's role — all flow through the same drag-drop-and-import path. Just pick your file and click Import. The preview catches anything the auto-detector got wrong before any data is written. See File Layouts when you need the exact rules for columns, row types, and hierarchy markers.

The import wizard, step by step

The wizard at Coding guides → Import a guide has six steps. Most users complete it in a couple of minutes; the only step that takes any real time is the optional LLM enrichment.

Step 1 — Name your guide

Give the guide a name and pick whether it's single-label (each response gets one category) or multi-label (each response can receive several). You can change the name later; the labelling mode is fixed once the guide exists, so choose carefully. If you're unsure, see Best Practices.

Step 2 — Upload your codebook

Drop an Excel (.xlsx, .xls) or CSV file. The wizard accepts files up to 10 MB and parses the first sheet of an Excel workbook.

If you don't already have a file in the right shape, download one of the starter templates:

Step 3 — Review what the parser found

The wizard shows you a preview of the guide it will create: category names, category descriptions, and which rows it treated as groups versus assignable categories. If your file has category hierarchies, this is where you check that the group rows and category rows look right before importing.

You don't need to memorise the parser rules to import a guide. The short version is: each imported category gets a category name and category description; hierarchy rows add context when your file marks them that way; unmarked visual headings are ignored. The File Layouts page has the full reference for the supported source-file formats, including formats that use columns named Code, Label, Description, and Level.

Step 4 — Choose whether to enrich

By default, each imported category row becomes a category in your guide, with a category name and a category description based on the source file. For codebooks larger than 50 or so categories, we recommend turning on LLM enrichment: an authoring helper that writes a fuller definition for every category, including what's included and what's explicitly excluded.

Before you start, the wizard shows the upfront credit estimate — the exact wording you'll see is "Reserve credits & start enrichment". Credits are reserved (not yet billed) when enrichment begins. See Credits for how the reservation model works in detail.

Wait — single rater? Yes, enrichment intentionally uses one provider. It's an authoring helper that produces draft text for you to review and edit — there's no ground truth to cross-check against, so the dual-rater principle doesn't apply here. Classification itself (the part that produces your coded data) still uses two independent raters in isolation, exactly as documented in Dual-Rater Method.

Step 5 — Watch enrichment fill in the details

The LLM works through your categories in batches, filling in three structured fields per category:

  • DEFINITION — what this category means, including parent-group context when your guide has hierarchy
  • INCLUDES — example phrasings respondents might use that belong in this category
  • EXCLUDES — adjacent ideas that look similar but belong elsewhere

Enrichment mirrors your source language. INCLUDES lists contain real respondent phrasings — for an English codebook, things like "really friendly", "attentive staff". Feed it a German or Spanish codebook and you'll get descriptions in that language, with example phrasings respondents in that language actually use — not translations into English.

The progress screen shows the reservation and the amount used so far. You can cancel at any point. Cancelling is safe: unused reserved credits refund automatically, and you can choose to keep the categories that already enriched (the rest are committed with their original descriptions) or discard the whole import.

Step 6 — Create the guide

Review the enriched (or un-enriched) categories, then click Create guide. Normal guide creation does not charge again: enrichment credits were reserved when enrichment began, then settled or refunded when the import reached a completed, cancelled, or failed state. The credit ledger shows the reservation, any refund, and the final balance.

Downloading your guide

Every guide can be downloaded from its detail page. Two formats are available:

  • CSV — universal, opens cleanly in any tool
  • XLSX — preserves column widths and is friendlier for colleagues who edit in Excel

Both use the same export columns — Code and Description. In that exported file, Code contains the category name and Description contains the category description, so the file can be re-imported into qualcode.ai or another tool without manual cleanup. Hierarchy is preserved through the category-description prefix (e.g. Food › Texture: Crunchy), so even a flat re-import keeps each category disjoint from look-alikes elsewhere in the codebook.

Round-tripping: download → edit → re-import

The download/import pair is designed to preserve the parts that matter: category names and category descriptions. If your category names came from source-file codes, those values survive verbatim — numeric ("1", "12") and alphanumeric ("INN-01", "Q1") alike — so you can hand a guide off to a colleague who prefers to refine categories in Excel, get the file back, and re-import it as a clean flat guide. Original workbook formatting and hierarchy rows are not recreated; hierarchy context travels in the category descriptions.

Collaboration recipe: Download the guide as XLSX, edit descriptions or add categories in Excel, then re-import as a new guide (give it a fresh name). The two guides sit side by side in your library — the original stays intact while you iterate on the new version.

Duplicating a guide

Sometimes you want a clone you can edit without touching the original — for example, to spin off a tightened version for a specific subset of responses. Click the Duplicate icon on any guide card.

Duplication is intentionally lightweight:

  • Copies: guide metadata (name, description, mode, implicit-N/A setting) and every category (name, description, ordering)
  • Does not copy: training data, training versions, coding runs, or run history — the new guide starts clean
  • No LLM call, no credit charge — duplication is free and instant
  • Collision-safe naming: a duplicate of "My Guide" becomes "My Guide (duplicate)"; if that exists, "My Guide (duplicate 2)", and so on

Translating a guide

From a guide's detail page, use the translate icon to translate all category names and descriptions into another language. Translation updates the current guide, costs 10 credits, and is useful when a codebook needs to move between project teams or fieldwork languages.

Supported targets include German, English, French, Spanish, Italian, Portuguese, Dutch, Polish, Czech, Swedish, Danish, Norwegian, Finnish, Hungarian, Romanian, Japanese, Chinese (Simplified), Chinese (Traditional), Korean, Arabic, Turkish, and Russian. Auto-suggested guides preserve quoted respondent examples where relevant. If translation fails, the credits are refunded automatically.

Trash & restore

Deleted guides go to your trash, where they sit recoverable until you empty it. Draft auto-suggest suggestions are an exception — those are short-lived working state, so they delete immediately. See the Trash panel on your dashboard for the full picture.

Limits & guardrails

Limit Value Why
File size 10 MB Comfortably above any real codebook we've seen
Categories per import 1,000 Payload, reservation, and human-review ergonomics
Concurrent imports per user 2 Keeps enrichment workers fair across users
Project required? No Guides are user-scoped — reusable across all your projects

Where to find these features

  • Import a guide — button next to New Guide on the Coding guides page (cloud-upload icon)
  • Download — dropdown on each guide card and on the guide detail page (CSV / XLSX)
  • Duplicate — copy icon on each guide card; one click, no confirmation
  • Translate — language icon on the guide detail page
  • Trash — accessible from your dashboard sidebar

Related

  • File Layouts — reference for every supported file shape
  • Best Practices — designing categories that produce stronger agreement
  • Auto-Suggest — build a codebook from scratch using your data
  • Credits — how the reservation and refund model works
  • Training Versions — for uploading training examples (response → category pairs), which is a different feature from importing a guide