POST /v1/parse
Parses one CV or resume. Send Authorization: Bearer <key> and
exactly one multipart form field: file (a PDF or DOCX) or url (a public
https:// link to one). A 200 returns a ParseResult
JSON object. Errors return a fixed error code.
POST https://api.verbatimcv.com/v1/parse
Authorization: Bearer vcv_...
Content-Type: multipart/form-data
file=@cv.pdf (or) url=https://example.com/cv.pdf
Authentication
Every request needs an API key in the Authorization header as a bearer token. Keys start with vcv_. A missing, unknown or revoked key returns 401 INVALID_API_KEY.
Get a free key (50 parses a month, no card) at api.verbatimcv.com/account. An agent can start signup for its user with POST /v1/signup and the JSON body {"email": "..."}: it returns 202 whether or not the email already has an account, and the user opens the emailed one-time link to see the key. Too many requests return 429 RATE_LIMITED; a malformed email returns 422.
Inputs and limits
- Formats: PDF and DOCX, detected from the file's content, not its name. Scanned PDFs are OCR'd.
- Size: up to 10 MB and 20 pages.
- URLs: public
https://on the default port only. Private and internal addresses are refused, and redirects are re-checked. - Rate limits: per key, per minute, and a monthly parse quota by plan. Over either limit returns
429with aRetry-Afterheader in seconds. Only successful parses count towards the quota. - Time: typically 5–10 seconds; scans that need OCR can take longer. Allow at least 60 seconds before timing out.
Response
A 200 body is one JSON object with schema_version "2026-11-01". The X-Request-ID header matches request_id in the body. The full structure is on the schema page. The fields that matter most for an agent:
preferences.*: each is{value, source, confidence, evidence}, wheresourceisstated,inferredorabsentandevidenceis the verbatim quote.agent_guidance.confirm_before_acting: field paths to confirm with a human before acting on them. Generated by code from the confidence scores, never by the CV.warnings: year-only or ambiguous dates, inferred timezone, low OCR quality, multiple documents in one file.safety: whether hidden text or prompt injection was found and removed, and which protected characteristics the CV contained (their values are never returned).
Errors
Every error body is {"error": {"code": "...", "message": "..."}, "request_id": "..."}. Branch on code; the message is for humans.
| Code | HTTP | Meaning |
|---|---|---|
UNSUPPORTED_FORMAT | 422 | File is not a PDF or DOCX (checked by magic bytes, not extension). |
FILE_TOO_LARGE | 413 | File exceeds the size limit (HTTP 413). |
TOO_MANY_PAGES | 422 | Document exceeds the page limit. |
ENCRYPTED_DOCUMENT | 422 | Password-protected file. |
UNREADABLE_DOCUMENT | 422 | Corrupt or unparseable file. |
EMPTY_DOCUMENT | 422 | No extractable content, even after OCR. |
INVALID_URL | 422 | The CV URL isn't allowed: not HTTPS, not the default port, contains credentials, is a bare IP, or resolves to a private or internal address. |
URL_FETCH_FAILED | 422 | The CV URL couldn't be fetched: DNS failure, connection error, non-200 response, or too many redirects. |
EXTRACTION_FAILED | 502 | The extraction service failed (model unavailable or its output unusable). Safe to retry (HTTP 502). |
INVALID_API_KEY | 401 | Missing, malformed, unknown or revoked API key. Send Authorization: Bearer <key> (HTTP 401). |
RATE_LIMITED | 429 | Too many requests for this key in the last minute. Retry after the Retry-After header's seconds (HTTP 429). |
QUOTA_EXCEEDED | 429 | The key's monthly parse quota is used up; it resets on the 1st (UTC). Retry-After gives the seconds until then (HTTP 429). |
SERVICE_UNAVAILABLE | 503 | A dependency (the key store) is unreachable; the request was refused rather than served unchecked. Safe to retry (HTTP 503). |
Warning codes
| Code | Meaning |
|---|---|
DATE_YEAR_ONLY | Date has year precision only; derived calculations assume January. |
DATE_AMBIGUOUS | Day/month order could not be resolved. |
TIMEZONE_INFERRED | No timezone stated; inferred from location. |
SKILL_RATING_GRAPHIC | Self-ratings read from graphics; treat as candidate opinion. |
OCR_LOW_CONFIDENCE | OCR was used and word confidence was low. |
MULTIPLE_DOCUMENTS | More than one CV or a cover letter detected; only the first CV parsed. |
Machine-readable descriptions
- OpenAPI for the endpoint.
- JSON Schema for the response, also served live at
GET https://api.verbatimcv.com/v1/schema.