Bulk Resume Upload API

Import up to 200 resumes and 20.0 MB per ZIP bundle.

Single-File API Bulk Upload Schema Design Try resume parser

Use this endpoint when you need to import up to 200 resumes at a time into TalentPrism. ZIP uploads are limited to 20.0 MB. Upload a CSV manifest (and optionally a ZIP of local resumes) and we‘ll parse each file, create/update candidates, attach the resume file, and log every parse for auditing.

Authentication

Same API key / session auth you already use. Only authenticated team users can submit bulk uploads.

1. Endpoint Summary

Upload

POST /candidate/api/bulk-parse-resumes/

multipart/form-data
Fields: manifest (CSV, required), resumes_zip (optional ZIP), schema_key, source
Limits: 200 rows and 20.0 MB per ZIP
Returns { upload_id, status, total_rows } with HTTP 202

Status

GET /candidate/api/bulk-parse-resumes/<upload_id>/

Returns summary counts + per-row status
Page refresh friendly (poll every few seconds)
Rows include candidate_id or error message

2. Minimal CSV Manifest

Keep it simple: header row + one line per candidate. Only the columns below are read; everything else is ignored.

Download a starter template: bulk_resume_manifest.csv

Column	Description	Required?
resume_url	Public HTTPS link to the resume file	One of resume_url or zip_path
zip_path	Relative path inside the optional ZIP (e.g. `resumes/jane.pdf`)	One of resume_url or zip_path
first_name	Override if the resume is missing this	Optional
last_name	Override if the resume is missing this	Optional
email	Contact email (used if the resume doesn’t have one)	Optional
phone	Contact phone (E.164 or digits)	Optional

Everything else (role, summary, tags) comes from the parser, so you don’t have to pre-fill it.

3. Sample Request

curl -X POST https://talentprism.ai/candidate/api/bulk-parse-resumes/ \
  -H "Authorization: Api-Key <YOUR_KEY>" \
  -F [email protected] \
  -F [email protected] \
  -F schema_key=shipyard

If every row uses resume_url, the resumes_zip part is optional.

4. Polling Upload Status

GET /candidate/api/bulk-parse-resumes/<upload_id>/

{
  "id": 123,
  "status": "processing",
  "total_rows": 5,
  "processed_rows": 3,
  "success_count": 3,
  "failure_count": 0,
  "rows": [
    {"row_number": 1, "status": "succeeded", "candidate_id": 456, "error_message": ""},
    {"row_number": 2, "status": "succeeded", "candidate_id": 457, "error_message": ""},
    {"row_number": 3, "status": "processing", "candidate_id": null, "error_message": ""}
  ]
}

Statuses: queued → processing → completed (or completed_with_errors / failed). Failed rows include the error message so you can fix the manifest and retry a smaller batch.

5. Ready-made Upload Script

Don't want to build your own client? Download our helper script to batch local files automatically (200 resumes and 20.0 MB per request) and respect the daily rate limits.

Download Python Script

python bulk_resume_uploader.py \
  --api-key='Api-Key <YOUR_KEY>' \
  --directory='/path/to/resumes' \
  --schema-key=shipyard

Scans the directory, chunks files by count and estimated ZIP size, uploads them sequentially.
Automatically waits for each upload to finish before starting the next.
Stops after 30 uploads by default (matching the rate limit); adjust with --max-uploads.
Polls the status endpoint and prints row-level errors so you can fix and retry.

6. Best Practices

Keep batches small. 200 rows and 20.0 MB per ZIP keeps uploads reliable; break large imports into multiple files.
Use HTTPS URLs when possible. They parse faster than large ZIPs.
Watch for duplicates. We dedupe on phone/email per team, but clean manifests make it easier to trace issues.
Respect rate limits. Each team gets 30 uploads/day by default. Reach out if you need more.
Retry failures selectively. You can build a new CSV with only the failed rows (copy errors from the status endpoint) and re-upload.

7. FAQ

What file types are supported?
PDF, DOCX, and the same image formats supported by the single-file API.

How long does processing take?
Most batches finish in under a minute. Large PDFs or image OCR may take longer; you can poll the status endpoint continuously.

Where can I see the output?
Each candidate shows up under your TalentPrism team with their resume attached and the parsed snapshot viewable in the UI.

Can I automate result retrieval?
Yes—poll the status endpoint and store the candidate_id values returned per row.

Can't find what you're looking for?