> ## Documentation Index
> Fetch the complete documentation index at: https://greatquestion.co/support/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing Candidates

> Bulk upload candidates into Great Question from a CSV file.

You can bulk upload candidates into Great Question from a CSV file, useful for loading an existing participant database, adding a new batch of people, or shortlisting candidates straight into a study.

## Before you import

Make sure your file is ready:

* It must be a **CSV file** (`.csv`).
* **Column headers must appear in the first row.**
* Ensure quotes are correctly paired if any field uses them.
* Only import the data you actually need.
* Use `YYYY-MM-DD` format for any date fields.
* Each row needs a valid **email address** (or another unique identifier, if enabled).

## Option 1: Import from the Candidates page

1. Go to the **Candidates** page.
2. Click **Add Candidates → Import from CSV**.
3. Upload your file.
4. **Map fields** in your CSV to existing candidate attributes.
5. Adjust import settings (see below).
6. Confirm the import.

<Note>
  CSV import can be disabled for your workspace. If it is, you'll see a lock icon and a message that your workspace admin has turned it off, ask an Admin to enable it.
</Note>

## Option 2: Import within a study

You can also import directly from inside a study. Candidates are added to your main candidate database and **shortlisted automatically** to that study at the same time.

## Import settings

During import you can configure:

* **Import name** — a label for this batch.
* **Candidate update process** — how to handle candidates that already exist.
* **Contact access** — who can contact the imported candidates. This setting only appears on accounts with Teams enabled.
* **Shortlist to a study** (optional).
* **Unique identifier** — Email, or a custom attribute flagged as unique.
* **Bulk attributes** — apply an attribute value to every candidate in the import.

<Note>
  A custom attribute can only be used as the unique identifier for matching and updating *existing* candidates, if every row in your file is brand new, the import falls back to matching on email.
</Note>

You'll receive an email confirmation when the import completes.

## Troubleshooting

| Issue                                             | What's happening                                                                   | How to fix                                                                       |
| ------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Upload fails                                      | The file isn't a valid CSV, or headers are missing                                 | Confirm the file is `.csv` and that column headers are in the first row          |
| Import option is locked                           | CSV import has been disabled for your workspace                                    | Ask an Admin to re-enable candidate CSV import                                   |
| Import seems stuck                                | A large file is still processing                                                   | Wait for the completion email                                                    |
| Columns aren't matching                           | Fields weren't mapped to the right attributes                                      | Re-check the field-mapping step and map each column deliberately                 |
| Some candidates were skipped                      | They already exist as duplicates, or their row had a blank unique-identifier value | Review the unique identifier and your candidate-update setting                   |
| Candidates imported but are flagged uncontactable | Their email address was present but invalid                                        | Fix the email on the candidate's profile                                         |
| New attributes don't appear right away            | Attribute visibility can take a moment to update                                   | Refresh the Candidates page after the import completes                           |
| Candidates didn't appear in a study               | The import wasn't set to shortlist to that study                                   | Re-import with the shortlist option, or add the candidates to the study manually |

***

**Still need help?** Contact us at [support@greatquestion.co](mailto:support@greatquestion.co) — median response time is 19 minutes during [support hours](https://greatquestion.co/features/about-our-support-team).