What columns does the applicants CSV need?
Four required columns: name, email, external_role_id and cv_filename. Everything else is optional, and unknown columns are ignored rather than rejected.
Updated September 28, 2026 · 6 min read
On this page
Column reference
| Column | Type | Description |
|---|---|---|
| name | textRequired | Full name as you want it shown on the scorecard. |
| textRequired | Used to match re-uploads to an existing candidate. Must be unique per role. | |
| external_role_id | textRequired | Must match an external_role_id in the roles CSV. This is what attaches the applicant to a rubric. |
| cv_filename | textRequired | Filename inside the ZIP, including the extension. PDF only, up to 10 MB. Letter case is ignored. |
| phone | textOptional | Shown on the scorecard. Not used in scoring. |
| linkedin_url | urlOptional | Shown on the profile. Not used in scoring. |
| github_url | urlOptional | Shown on the profile. Not analysed: a GitHub link is read only when it appears in the resume itself. |
| portfolio_url | urlOptional | Shown on the profile. |
A minimal file
Comma-separated, UTF-8, with a header row. Quote any field that contains a comma.
name,email,external_role_id,cv_filename
Rina Putri,rina@example.com,BE-2026-01,rina-putri.pdf
Adi Santoso,adi@example.com,BE-2026-01,adi-santoso.pdf
"Chen, Mei",mei@example.com,BE-2026-01,mei-chen.pdfcv_filename must match the filename in the ZIP, extension included. Letter case is ignored, and only PDFs are read. A mismatch here is the single most common upload failure.
Errors you might see
- Resume "…" not found in the ZIP.
- The filename in the CSV does not exist in the ZIP. Usually a missing extension or a typo.
- Resume "…" must be PDF.
- Word documents and images are skipped. Convert the file to PDF and upload the batch again.
- external_role_id "…" not found in roles.csv.
- The value is not present in the roles CSV. Upload both files in the same batch.
- Duplicate email+role in this import; skipped.
- Two rows share an email on the same role. Keep one — the second is not a separate applicant.
- Missing required name, email, external_role_id, or cv_filename.
- The row has a blank in one of the four required columns. If every row shows it, the header is misspelled. Header case and column order do not matter.
Still stuck? Email support@hyretech.ai and mention this article.