Importing Participants via CSV

When you already have a list of people you want to interview, importing them from a CSV file is the fastest way to get started. Each imported participant receives a unique tracking link, and their details are pre-filled so they can jump straight into the conversation.

When to Use CSV Import

CSV import is ideal when you:

• Have an existing list of customers, users, or prospects in a spreadsheet or CRM export
• Want each participant to have their own trackable link
• Need to pre-fill intake form fields (like name or email) so participants do not have to type them again
• Are running a targeted study where you know exactly who should participate

How It Works

1. Prepare your CSV file with the required columns.
2. Upload the file from your project's respondents tab.
3. Koji creates a unique record for each row, complete with a personal interview link.
4. Distribute the links by email, Slack, or any other channel.

When a participant clicks their unique link, Koji recognizes them automatically. Their name, email, and any other imported fields appear in your results without the participant needing to re-enter anything.

Preparing Your CSV File

Required Columns

There are no strictly required columns — Koji will import whatever you provide. However, the following column names are recognized and handled specially:

Any additional columns (such as company, role, segment, or custom attributes) are stored as intake data and attached to the respondent record.

Format Requirements

• File type: .csv (comma-separated values)
• Encoding: UTF-8 is recommended to handle international characters
• Header row: The first row must contain column names
• Maximum rows: Up to 500 participants per upload
• No duplicate IDs: If you include an external_id column, each value should be unique

Here is an example file:

name,email,company,role
Jane Smith,[email protected],Acme Corp,Product Manager
Bob Johnson,[email protected],Widgets Inc,UX Designer
Li Wei,[email protected],StartupCo,CEO

Uploading Your File

1. Open your project and navigate to the Respondents tab.
2. Click the Upload button.
3. Select your CSV file from your computer.
4. Koji will parse the file and show a preview of the detected columns and rows.
5. Confirm the upload.

After the upload completes, you will see each participant listed in the respondents table. Every row includes:

• The participant's name (if provided)
• Their unique interview link
• A status indicator showing whether they have started or completed the interview

Unique Tracking Links

Each imported participant gets a personalized URL that looks like:

https://yourdomain.com/i/your-slug?rid=abc123

The rid parameter ties the response back to that specific person. When the participant clicks the link:

• Their intake form fields are pre-filled with the data you imported
• Their interview is automatically associated with the correct respondent record
• You can see exactly which imported participants have completed the interview and which have not

Pre-Filling Lead Form Fields

If your project has an intake form enabled, CSV-imported data maps to form fields automatically. For example, if your intake form collects a name and email, and your CSV has those columns, participants will see those fields already filled in when they land on the interview page.

Participants can still edit pre-filled values if needed, but in most cases they simply click through to start the interview.

Plan Requirements

CSV import is available on the Scale plan. If you are on a different plan, you will see an upgrade prompt when you try to upload. See the Plan Comparison Guide for details on what each tier includes.

After Import: Distributing Links

Once your participants are imported, the next step is sending them their unique links. You can:

• Copy individual links from the respondents table by clicking the link icon next to each row.
• Export the list with links included, then use your email tool or CRM to send personalized outreach.
• Combine with the Headless API to trigger interviews programmatically. See Headless API Overview for more on this approach.

Monitoring Progress

The respondents table updates in real time as participants complete interviews. You can see:

• Status: Whether the participant has not started, is in progress, or has completed the interview
• Quality score: The automatically assigned score for completed interviews
• Conversation details: Click into any row to read the full transcript and see the analysis

Tips for a Smooth Import

1. Clean your data first. Remove duplicates and fix formatting issues before uploading.
2. Use consistent column names. Stick to the recognized names (name, email, external_id) so Koji maps them automatically.
3. Test with a small batch. Upload five to ten rows first to verify everything looks right before importing your full list.
4. Communicate expectations. When you send out the links, let participants know what to expect — a brief conversational interview that takes just a few minutes.

Next Steps

• Sharing Your Interview Link — other ways to distribute your interview
• Headless API Overview — manage interviews programmatically