{"site":{"name":"Koji","description":"AI-native customer research platform that helps teams conduct, analyze, and synthesize customer interviews at scale.","url":"https://www.koji.so","contentTypes":["blog","documentation"],"lastUpdated":"2026-05-18T13:33:28.761Z"},"content":[{"type":"documentation","id":"afb58fbb-21d1-4266-b7dc-3a0efb632493","slug":"importing-participants-csv","title":"Importing Participants via CSV","url":"https://www.koji.so/docs/importing-participants-csv","summary":"Upload a CSV file to import up to 500 participants into your Koji project. Each person gets a unique tracking link with pre-filled intake fields. This guide covers file format, the import process, and link distribution.","content":"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.\n\n## When to Use CSV Import\n\nCSV import is ideal when you:\n\n- Have an existing list of customers, users, or prospects in a spreadsheet or CRM export\n- Want each participant to have their own trackable link\n- Need to pre-fill intake form fields (like name or email) so participants do not have to type them again\n- Are running a targeted study where you know exactly who should participate\n\n## How It Works\n\n1. **Prepare your CSV file** with the required columns.\n2. **Import the file** from your project's respondents tab.\n3. **Koji creates a unique record** for each row, complete with a personal interview link.\n4. **Distribute the links** by email, Slack, or any other channel.\n\nWhen 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.\n\n## Preparing Your CSV File\n\n### Required Columns\n\nThere are no strictly required columns — Koji will import whatever you provide. However, the following column names are recognized and handled specially:\n\n| Column | Purpose |\n|---|---|\n| `name`, `display_name`, `fullname`, or `full_name` | Shown in your results table and used to greet the participant |\n| `email` | Stored for follow-up and identification |\n| `external_id` or `id` | Your own identifier for matching against your CRM or database |\n\nAny additional columns (such as `company`, `role`, `segment`, or custom attributes) are stored as intake data and attached to the respondent record.\n\n### Format Requirements\n\n- **File type:** `.csv` (comma-separated values)\n- **Encoding:** UTF-8 is recommended to handle international characters\n- **Header row:** The first row must contain column names\n- **Maximum rows:** Up to 500 participants per upload\n- **No duplicate IDs:** If you include an `external_id` column, each value should be unique\n\nHere is an example file:\n\n```csv\nname,email,company,role\nJane Smith,jane@acme.com,Acme Corp,Product Manager\nBob Johnson,bob@example.org,Widgets Inc,UX Designer\nLi Wei,li.wei@startup.io,StartupCo,CEO\n```\n\n## Importing Your File\n\n1. Open your project and navigate to the **Respondents** tab.\n2. Click the **Import CSV** button.\n3. Select your CSV file from your computer.\n4. Koji will parse the file and show a preview of the detected columns and rows.\n5. Confirm the import.\n\nAfter the import completes, you will see each participant listed in the respondents table. Every row includes:\n\n- The participant's name (if provided)\n- Their unique interview link\n- A status indicator showing whether they have started or completed the interview\n\n## Unique Tracking Links\n\nEach imported participant gets a personalized URL that looks like:\n\n```\nhttps://yourdomain.com/i/your-slug?rid=abc123\n```\n\nThe `rid` parameter ties the response back to that specific person. When the participant clicks the link:\n\n- Their intake form fields are pre-filled with the data you imported\n- Their interview is automatically associated with the correct respondent record\n- You can see exactly which imported participants have completed the interview and which have not\n\n## Pre-Filling Lead Form Fields\n\nIf your project has an [intake form](/docs/intake-forms-and-consent) 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.\n\nParticipants can still edit pre-filled values if needed, but in most cases they simply click through to start the interview.\n\n## Plan Availability\n\nCSV import is available on all Koji plans. The feature is gated behind the CRM import entitlement, which is included with your account. If you do not see the **Import CSV** button on the respondents tab, check your plan details or contact support.\n\n## Structured Questions and CSV Imports\n\nIf your study includes [structured questions](/docs/structured-questions-guide) (scales, multiple choice, ranking, or yes/no), participants who arrive via their personalized CSV link will see the same interactive question widgets as any other participant. Structured question responses are captured and associated with the imported respondent record automatically.\n\n## After Import: Distributing Links\n\nOnce your participants are imported, the next step is sending them their unique links. You can:\n\n- **Copy individual links** from the respondents table by clicking the link icon next to each row.\n- **Export the list** with links included, then use your email tool or CRM to send personalized outreach.\n- **Combine with the Headless API** to trigger interviews programmatically. See [Headless API Overview](/docs/headless-api-overview) for more on this approach.\n\n## Monitoring Progress\n\nThe respondents table updates in real time as participants complete interviews. You can see:\n\n- **Status:** Whether the participant has not started, is in progress, or has completed the interview\n- **Quality score:** The automatically assigned score for completed interviews\n- **Conversation details:** Click into any row to read the full transcript and see the analysis\n\n## Tips for a Smooth Import\n\n1. **Clean your data first.** Remove duplicates and fix formatting issues before uploading.\n2. **Use consistent column names.** Stick to the recognized names (`name`, `display_name`, `fullname`, `full_name`, `email`, `external_id`) so Koji maps them automatically.\n3. **Stay within the 500-row limit.** Each upload supports a maximum of 500 participants. For larger lists, split into multiple files.\n4. **Test with a small batch.** Upload five to ten rows first to verify everything looks right before importing your full list.\n5. **Communicate expectations.** When you send out the links, let participants know what to expect — a brief conversational interview that takes just a few minutes.\n\n## Next Steps\n\n- [Sharing Your Interview Link](/docs/sharing-your-interview-link) — other ways to distribute your interview\n- [Headless API Overview](/docs/headless-api-overview) — manage interviews programmatically\n- [Structured Questions Guide](/docs/structured-questions-guide) — add interactive question types to your study\n\n## Further reading on the blog\n\n- [How to Recruit User Research Participants: The Complete Guide (2026)](/blog/how-to-recruit-user-research-participants-2026) — Recruiting the wrong participants is more expensive than recruiting none at all. Here's the complete playbook: screeners, channels, incentiv\n\n<!-- further-reading:blog -->\n","category":"Collecting Responses","lastModified":"2026-05-13T00:26:36.807295+00:00","metaTitle":"Importing Participants via CSV — Koji Docs","metaDescription":"Bulk import participants from a CSV spreadsheet into Koji. Each gets a unique tracking link with pre-filled intake data.","keywords":["CSV import","bulk import","participants","spreadsheet","tracking links","respondents"],"aiSummary":"Upload a CSV file to import up to 500 participants into your Koji project. Each person gets a unique tracking link with pre-filled intake fields. This guide covers file format, the import process, and link distribution.","aiPrerequisites":["sharing-your-interview-link"],"aiLearningOutcomes":["Prepare a CSV file with the correct format","Upload participants to a project","Distribute unique tracking links","Monitor participant completion status"],"aiDifficulty":"intermediate","aiEstimatedTime":"6 min read"}],"pagination":{"total":1,"returned":1,"offset":0}}