Single-File Resume Parsing API

Upload one resume at a time and get structured JSON instantly.

Single-File API Bulk Upload Schema Design Try resume parser

Use this endpoint to parse a single resume in real time. The API creates (or updates) the candidate record, saves the original file to the candidate profile, and stores the structured JSON output in resume_snapshot. Every call is authenticated, rate-limited, and logged for troubleshooting.

Endpoint

POST /candidate/api/parse-resume/

Accepts multipart/form-data. Response is JSON.

Request Parameters

Field	Type	Required?	Notes
resume	File	Yes	PDF/DOCX/image up to your plan�s limit
schema_key	String	No	Use to select a custom schema; defaults to team/global default
candidate_id	Integer	No	If provided we update that candidate; otherwise we create a new record

Rate limit: 100 calls per hour per team by default. Contact support if you need higher throughput.

Sample cURL

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

Omit candidate_id to create a new candidate automatically.

Response

{
  "parsed_resume": {
    "full_name": "Alex Worker",
    "phone": "+15551234567",
    "trade_primary": "Welder",
    "years_experience": "5+",
    "...": "..."
  },
  "candidate_id": 9876
}

candidate_id references the candidate that was created or updated.
The uploaded file is stored on that candidate�s profile (resume field).
The full JSON blob lives in candidate.resume_snapshot for later use.

Error Handling

Status	Meaning	Typical Causes
400	Bad request	Missing file, invalid schema key, unsupported file type, etc.
403	Forbidden	Trying to update a candidate from another team
404	Not found	candidate_id does not exist
429	Too many requests	Rate limit exceeded
500	Server error	Unexpected failure (logged in Sentry + audit table)

Features

Automatic candidate creation: When you omit candidate_id, we derive name/contact info from the resume (or your optional metadata) and create a new candidate.
Original file storage: The uploaded PDF/DOCX/image is saved to candidate.resume so your team can download it later.
Audit trail: Every call inserts a ResumeParseRequest row (team, user, time, duration, status). Use the admin UI or API to troubleshoot.
Schema control: Teams can define their own parsing schema/prompt in the TalentPrism UI; pass schema_key to select it per request.

FAQ

What formats are supported?
PDF, DOCX, PNG, JPG/JPEG, WEBP, TIFF. Large scans use OCR before LLM parsing.

Can we include metadata (source, tags)?
At this time the API takes file + schema key. You can update the candidate afterwards via our REST endpoints.

How fast is it?
Most resumes parse in 2�5 seconds. The response is synchronous so you get the JSON immediately.

Do we get notifications?
Not for the single file API. Use the response payload (and the candidate snapshot) to drive your own workflows.

Can't find what you're looking for?