VerbatimCV

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

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:

Errors

Every error body is {"error": {"code": "...", "message": "..."}, "request_id": "..."}. Branch on code; the message is for humans.

CodeHTTPMeaning
UNSUPPORTED_FORMAT422File is not a PDF or DOCX (checked by magic bytes, not extension).
FILE_TOO_LARGE413File exceeds the size limit (HTTP 413).
TOO_MANY_PAGES422Document exceeds the page limit.
ENCRYPTED_DOCUMENT422Password-protected file.
UNREADABLE_DOCUMENT422Corrupt or unparseable file.
EMPTY_DOCUMENT422No extractable content, even after OCR.
INVALID_URL422The 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_FAILED422The CV URL couldn't be fetched: DNS failure, connection error, non-200 response, or too many redirects.
EXTRACTION_FAILED502The extraction service failed (model unavailable or its output unusable). Safe to retry (HTTP 502).
INVALID_API_KEY401Missing, malformed, unknown or revoked API key. Send Authorization: Bearer <key> (HTTP 401).
RATE_LIMITED429Too many requests for this key in the last minute. Retry after the Retry-After header's seconds (HTTP 429).
QUOTA_EXCEEDED429The key's monthly parse quota is used up; it resets on the 1st (UTC). Retry-After gives the seconds until then (HTTP 429).
SERVICE_UNAVAILABLE503A dependency (the key store) is unreachable; the request was refused rather than served unchecked. Safe to retry (HTTP 503).

Warning codes

CodeMeaning
DATE_YEAR_ONLYDate has year precision only; derived calculations assume January.
DATE_AMBIGUOUSDay/month order could not be resolved.
TIMEZONE_INFERREDNo timezone stated; inferred from location.
SKILL_RATING_GRAPHICSelf-ratings read from graphics; treat as candidate opinion.
OCR_LOW_CONFIDENCEOCR was used and word confidence was low.
MULTIPLE_DOCUMENTSMore than one CV or a cover letter detected; only the first CV parsed.

Machine-readable descriptions