Script Import & Documents2 min readUpdated 30 May 2026Web app

Matching imported characters

This article covers the web app.

When a script is imported, every character name it finds shows up in the New Characters stage of the review. Your job here is to tell Haystack which ones are genuinely new and which are already in your project under a different name, so you don't end up with duplicates.

Add as new, or merge

Each character has two import modes:

  • Add as new character - creates a fresh character. Set the Name and Description, and turn on Crowd Character if this is background rather than a principal.
  • Merge with existing character - points this name at a character you already have, or at another new one from the same import, so they become one.

Merging duplicates

Pick Merge with existing character, then choose the character to merge with from the picker. It groups New Characters (others from this import) and Existing Characters (already in your project) so you can find the right one. The merge dropdown sets how the two relate:

  • Duplicates - treats this name as an alias of the chosen character. Both names refer to the same character, and no changes are made to the one you picked. Use this for a nickname or a spelling variant.
  • Replaces - swaps the chosen character for this one across all scenes, updating it with the details you set here.

A character that another one is being merged into is flagged so you don't accidentally edit both ends of the same merge. You must choose a character before you can move on from a merge.

Principals and crowd

Leave Crowd Character off and the character comes in as a principal with its own ID. Turn it on for background characters. The form shows how many scenes this character is being added to, so you can sanity-check it against the script. You can read the relevant script text on the Script tab while you decide.

To leave a character out entirely, turn off its include toggle. It is skipped and won't be created or merged. Handy for stray names the script picked up that aren't real characters.

Sorting characters out first means the scenes that follow already point at the right people. For the rest of the flow, see Reviewing an import.

Matching imported characters · Help Centre