{"openapi":"3.0.3","info":{"title":"Rezmatch.ai API","version":"0.1.0","description":"Parse-and-match API for hiring products: structure résumés and job descriptions into normalized JSON, score candidate↔role fit with a calibrated explanation.\n\n**Hard rule:** Rezmatch.ai never stores résumés or JDs — processing is transient; documents are deleted immediately after processing.\n\n**Fairness:** matching always scores on a bias-redacted feature set and returns scores + explanations, never hire/reject verdicts.\n\nDocs show each endpoint's canonical method, but every endpoint also answers GET with `text`/`url` as query parameters — handy for quick tests from a browser or bare curl (file upload requires POST). Costs are metered in credits per successful call; failed calls are refunded.","contact":{"url":"https://github.com/stackd-dev/rezmatch"}},"servers":[{"url":"https://api.rezmatch.ai","description":"This API"}],"security":[{"AccessKeyHeader":[]},{"AccessKeyBearer":[]}],"tags":[{"name":"Parse","description":"Résumé and job-description parsing into normalized JSON"},{"name":"Match","description":"Candidate↔role fit scoring with explanations"},{"name":"Extract & Normalize","description":"À-la-carte extraction and taxonomy normalization"},{"name":"Safety","description":"Bias-redaction utilities"},{"name":"Utility","description":"Liveness and diagnostics"},{"name":"Management","description":"Dashboard-facing key and usage management (separate API, JWT-authenticated)"}],"paths":{"/parse/resume":{"post":{"tags":["Parse"],"operationId":"parseResume","summary":"Parse a résumé","description":"Parse a résumé into normalized Candidate JSON: E.164 phone, canonical location, work history with computed tenures, taxonomy-normalized skills, education with degree levels, and a bias-redacted `scoring_view` used by `/match`.\n\nProvide exactly one of `text`, `url`, or `file`. PDF files are processed natively; plain text is accepted; other binary formats return `unsupported_format`.\n\n**Cost: 1 credit.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"},"example":{"url":"https://files.example.com/resume.pdf"}}}},"responses":{"200":{"description":"Parsed Candidate JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateEnvelope"},"example":{"success":true,"data":{"candidate_id":"cand_9f2a41c07d13b6e8","contact":{"name":"Priya Sharma","email":"priya@example.com","phone":"+15125550100","location":"Austin, TX, United States","links":["https://github.com/priya"]},"summary":"Backend engineer focused on distributed systems.","total_experience_months":103,"seniority":"senior","work_history":[{"employer":"Acme Corp (Payments Division)","employer_normalized":"Acme Corp","title":"Senior Backend Engineer","title_normalized":"Backend Engineer","seniority":"senior","start":"2021-03","end":null,"tenure_months":65,"skills":["Go","Kubernetes","PostgreSQL"],"highlights":["Led migration to microservices"]}],"education":[{"institution":"University of Texas at Austin (Cockrell)","institution_normalized":"University of Texas at Austin","degree":"B.S.","degree_level":"bachelor","field":"Computer Science","field_normalized":"Computer Science","start":null,"end":"2018"}],"skills":[{"raw":"golang","canonical":"Go","taxonomy_id":"skill_go"},{"raw":"Phlebotomy","canonical":"Phlebotomy","taxonomy_id":null}],"certifications":[{"name":"CKA","issuer":"CNCF","year":2022}],"languages":["English"],"scoring_view":{"redacted_fields":["name","gender_proxies","age_proxies","photo"],"features":{"skills":["Go","Kubernetes","PostgreSQL"],"seniority":"senior","total_experience_months":103}}},"credits_used":1,"request_id":"req_7ed41a20-822f-4221-a674-cb84ebc74077"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"422":{"$ref":"#/components/responses/ParseFailed"}}}},"/parse/jd":{"post":{"tags":["Parse"],"operationId":"parseJd","summary":"Parse a job description","description":"Parse a job description into normalized Role JSON: canonical title + seniority, concise must-have skills with min-years, nice-to-haves, responsibilities, and qualifications. Job-board URLs (Greenhouse, Lever, company pages) are fetched directly.\n\nProvide exactly one of `text`, `url`, or `file`.\n\n**Cost: 1 credit.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"},"example":{"url":"https://job-boards.greenhouse.io/acme/jobs/123456"}}}},"responses":{"200":{"description":"Parsed Role JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleEnvelope"},"example":{"success":true,"data":{"role_id":"role_1a3f9be2c4d07a51","title":"Sr. Backend Engineer","title_normalized":"Backend Engineer","seniority":"senior","location":"Remote","employment_type":"full_time","must_have_skills":[{"canonical":"Go","taxonomy_id":"skill_go","min_years":3},{"canonical":"Kubernetes","taxonomy_id":"skill_kubernetes","min_years":null}],"nice_to_have_skills":[{"canonical":"Apache Kafka","taxonomy_id":"skill_kafka"}],"responsibilities":["Own services end to end"],"qualifications":["5+ years building distributed systems"],"min_experience_months":60},"credits_used":1,"request_id":"req_b35a573a-22ef-4379-9245-a01f0049150a"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"422":{"$ref":"#/components/responses/ParseFailed"}}}},"/match":{"post":{"tags":["Match"],"operationId":"match","summary":"Score one candidate against one role","description":"Calibrated 0-100 fit score with band, structured explanation (met/missed requirements with evidence), and signals. Hard requirements dominate: high text similarity cannot rescue missing must-haves, and large experience shortfalls cap the score.\n\nProvide the candidate as parsed `candidate` JSON **or** raw `resume_text`/`resume_url`/`resume_file` (parsed inline, +1 credit). Same for the role via `role` or `jd_text`/`jd_url`/`jd_file`.\n\nScoring always runs on the bias-redacted feature set; `fairness.scored_on_redacted_input` is always `true`. Results are evidence for human decisions — never hire/reject verdicts.\n\n**Cost: 2 credits + 1 per inline parse.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchInput"},"example":{"resume_text":"Jane Doe. Senior Backend Engineer at Foo since 2019. Skills: Go, Kubernetes, PostgreSQL.","jd_url":"https://job-boards.greenhouse.io/acme/jobs/123456"}}}},"responses":{"200":{"description":"Match result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchEnvelope"},"example":{"success":true,"data":{"score":84,"band":"strong","explanation":{"met":[{"requirement":"Go (3+ years)","evidence":"Go","verified":true}],"missed":[{"requirement":"Apache Kafka","severity":"nice_to_have"}],"over_qualified":false,"under_qualified":false,"seniority_fit":"match","notes":"The candidate meets all must-have requirements with strong skill similarity and a matching seniority level. The nice-to-have Kafka requirement was not evidenced."},"signals":{"must_have_coverage":1,"nice_to_have_coverage":0,"skill_similarity":0.8408,"seniority_gap":0},"fairness":{"scored_on_redacted_input":true}},"credits_used":4,"request_id":"req_ef6f1151-81c7-47a8-8086-88de98682bcd"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"422":{"description":"Inputs incomplete (`missing_candidate` / `missing_role`) or extraction failed (`parse_failed`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/score/requirements":{"post":{"tags":["Match"],"operationId":"scoreRequirements","summary":"Check which requirements a candidate meets","description":"Deterministic gate check — no LLM, no embeddings: taxonomy-ID and canonical skill matching, min-years vs computed tenure, seniority and experience gaps. Use it to pre-filter pools cheaply before full `/match` calls.\n\nRequires parsed `candidate` and `role` JSON (no raw-document inputs).\n\n**Cost: 1 credit.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["candidate","role"],"properties":{"candidate":{"$ref":"#/components/schemas/Candidate"},"role":{"$ref":"#/components/schemas/Role"}}}}}},"responses":{"200":{"description":"Requirement results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"met":[{"requirement":"Go (3+ years)","severity":"must_have","status":"met","evidence":"Go"}],"missed":[{"requirement":"Kafka","severity":"must_have","status":"missed","evidence":null}],"coverage":{"must_have":0.5,"nice_to_have":1}},"credits_used":1,"request_id":"req_bc88de56-9efc-4be8-9ae1-22cf86d86ca5"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"422":{"description":"missing_candidate / missing_role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/extract/skills":{"post":{"tags":["Extract & Normalize"],"operationId":"extractSkills","summary":"Extract skills from a document","description":"Every skill evidenced in the document as `{raw, canonical, taxonomy_id}` — canonical names for any industry; `taxonomy_id` when the seed taxonomy knows the skill. Accepts `text`, `url`, or `file`.\n\n**Cost: 1 credit.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"},"example":{"text":"Built dashboards in reactjs and tailwind, deployed on k8s."}}}},"responses":{"200":{"description":"Normalized skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"skills":[{"raw":"reactjs","canonical":"React","taxonomy_id":"skill_react"},{"raw":"tailwind","canonical":"Tailwind CSS","taxonomy_id":"skill_tailwind"},{"raw":"k8s","canonical":"Kubernetes","taxonomy_id":"skill_kubernetes"}]},"credits_used":1,"request_id":"req_0f6f1151-81c7-47a8-8086-88de98682bcd"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"}}}},"/extract/experience":{"post":{"tags":["Extract & Normalize"],"operationId":"extractExperience","summary":"Extract work history from a document","description":"Work history entries with normalized employers/titles and structured dates. Accepts `text`, `url`, or `file`. **Cost: 1 credit.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"}}}},"responses":{"200":{"description":"work_history[]","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/extract/education":{"post":{"tags":["Extract & Normalize"],"operationId":"extractEducation","summary":"Extract education from a document","description":"Education entries with official institution names, degree levels, and normalized fields. Accepts `text`, `url`, or `file`. **Cost: 1 credit.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"}}}},"responses":{"200":{"description":"education[]","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/extract/contact":{"post":{"tags":["Extract & Normalize"],"operationId":"extractContact","summary":"Extract contact details from a document","description":"Contact block with E.164 phone and structured location. Accepts `text`, `url`, or `file`. **Cost: 1 credit.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"}}}},"responses":{"200":{"description":"contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/redact":{"post":{"tags":["Safety"],"operationId":"redact","summary":"Redact PII and protected-class proxies","description":"Strip names, contact details, photo references, gendered language, age signals, and other protected-class proxies for bias-free evaluation, replacing each with a neutral placeholder and returning a categorized list of removals. Accepts `text`, `url`, or `file`.\n\n**Cost: 1 credit.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"},"example":{"text":"John Smith, 45, graduated 2003. He is an expert in Python."}}}},"responses":{"200":{"description":"Redacted text + removals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"redacted_text":"[NAME], [AGE], graduated [DATE]. [PRONOUN] is an expert in Python.","removed":[{"category":"name","original":"John Smith"},{"category":"age_proxy","original":"45"},{"category":"gender_proxy","original":"He"}]},"credits_used":1,"request_id":"req_1f6f1151-81c7-47a8-8086-88de98682bcd"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"}}}},"/normalize/title":{"get":{"tags":["Extract & Normalize"],"operationId":"normalizeTitle","summary":"Normalize a job title","description":"Raw title → canonical title + seniority, via the curated taxonomy (alias-matched, seniority prefixes extracted).\n\n**Cost: free.**","parameters":[{"name":"title","in":"query","required":true,"schema":{"type":"string"},"example":"Sr. Backend Engineer"}],"responses":{"200":{"description":"Canonical title","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"canonical":"Backend Engineer","seniority":"senior"},"credits_used":0,"request_id":"req_d7f935fe-9eba-4759-908a-815622dcda0e"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/normalize/skill":{"get":{"tags":["Extract & Normalize"],"operationId":"normalizeSkill","summary":"Normalize a skill","description":"Raw skill → canonical taxonomy entry with aliases. Skills outside the seed taxonomy return `taxonomy_id: null` with the input as canonical.\n\n**Cost: free.**","parameters":[{"name":"skill","in":"query","required":true,"schema":{"type":"string"},"example":"k8s"}],"responses":{"200":{"description":"Canonical skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"canonical":"Kubernetes","taxonomy_id":"skill_kubernetes","aliases":["k8s"]},"credits_used":0,"request_id":"req_00d542ff-427b-409b-a377-c913ff60fdfb"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/health":{"get":{"tags":["Utility"],"operationId":"health","summary":"Liveness check","description":"Unauthenticated liveness probe. **Cost: free.**","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"status":"ok","env":"dev"},"credits_used":0,"request_id":"req_2a783f3d"}}}}}}},"/ping":{"get":{"tags":["Utility"],"operationId":"ping","summary":"Authenticated metered ping","description":"Diagnostic endpoint demonstrating authentication and credit metering. **Cost: 1 credit.**","responses":{"200":{"description":"pong","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"}}}},"/v1/keys":{"post":{"tags":["Management"],"operationId":"createKey","summary":"Mint an API key","description":"Mint a new `rz_live_` API key. **The raw key is returned exactly once** and stored only as a SHA-256 hash — it can never be retrieved again.\n\nManagement API: separate base URL, authenticated with your dashboard session JWT (never an API key).","servers":[{"url":"https://oxtg7m5erd.execute-api.us-east-1.amazonaws.com","description":"Management API"}],"security":[{"DashboardJwt":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":100}}},"example":{"label":"Production"}}}},"responses":{"201":{"description":"Key minted — copy it now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"key":"rz_live_XXXXXXXX…","keyId":"key_1a2b3c4d5e6f7a8b","keyPrefix":"rz_live_XXXXXXXX","label":"Production"},"credits_used":0,"request_id":"req_…"}}}}}},"get":{"tags":["Management"],"operationId":"listKeys","summary":"List API keys","description":"List this account's keys — display prefixes only; raw keys are unrecoverable by design.","servers":[{"url":"https://oxtg7m5erd.execute-api.us-east-1.amazonaws.com","description":"Management API"}],"security":[{"DashboardJwt":[]}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/v1/keys/{keyId}":{"delete":{"tags":["Management"],"operationId":"revokeKey","summary":"Revoke an API key","description":"Revoke by status flip (never hard-deleted — the audit trail is preserved). Takes effect within ~60 seconds (authorizer cache TTL).","servers":[{"url":"https://oxtg7m5erd.execute-api.us-east-1.amazonaws.com","description":"Management API"}],"security":[{"DashboardJwt":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/v1/account":{"get":{"tags":["Management"],"operationId":"getAccount","summary":"Account: plan, credits, and catalog","description":"Current plan, credit balance, effective rate limit, whether a Stripe billing relationship exists, and the purchasable plan/pack catalog with prices.","servers":[{"url":"https://oxtg7m5erd.execute-api.us-east-1.amazonaws.com","description":"Management API"}],"security":[{"DashboardJwt":[]}],"responses":{"200":{"description":"Account summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"plan":"growth","credits":5820,"rate_limit_rpm":600,"stripe_customer":true,"catalog":{"plans":[{"id":"standard","name":"Standard","monthly_price_cents":2900,"monthly_credits":3000,"rate_limit_rpm":300}],"packs":[{"id":"pack_5k","name":"5,000 credits","price_cents":5500,"credits":5000}]}},"credits_used":0,"request_id":"req_…"}}}}}}},"/v1/billing/checkout":{"post":{"tags":["Management"],"operationId":"createCheckout","summary":"Start a purchase","description":"Create a Stripe Checkout session for a subscription plan (`{\"plan\": \"growth\"}`) or a one-time credit pack (`{\"pack\": \"pack_5k\"}`). Returns the hosted checkout URL; credits/plan apply automatically via webhook after payment.","servers":[{"url":"https://oxtg7m5erd.execute-api.us-east-1.amazonaws.com","description":"Management API"}],"security":[{"DashboardJwt":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","description":"Plan id from the /v1/account catalog"},"pack":{"type":"string","description":"Pack id from the /v1/account catalog"}}},"example":{"plan":"growth"}}}},"responses":{"200":{"description":"Hosted checkout URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"url":"https://checkout.stripe.com/c/pay/cs_…","session_id":"cs_…"},"credits_used":0,"request_id":"req_…"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/v1/billing/portal":{"post":{"tags":["Management"],"operationId":"createPortal","summary":"Open the billing portal","description":"Create a Stripe billing-portal session for managing or cancelling the subscription. Requires prior billing history.","servers":[{"url":"https://oxtg7m5erd.execute-api.us-east-1.amazonaws.com","description":"Management API"}],"security":[{"DashboardJwt":[]}],"responses":{"200":{"description":"Portal URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/v1/usage":{"get":{"tags":["Management"],"operationId":"getUsage","summary":"Credits and usage this period","servers":[{"url":"https://oxtg7m5erd.execute-api.us-east-1.amazonaws.com","description":"Management API"}],"security":[{"DashboardJwt":[]}],"responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"success":true,"data":{"plan":"free","credits_remaining":89,"period":"2026-07","credits_used_this_period":11,"calls_this_period":12},"credits_used":0,"request_id":"req_…"}}}}}}}},"components":{"securitySchemes":{"AccessKeyHeader":{"type":"apiKey","in":"header","name":"x-access-key","description":"Your rz_live_ API key. Mint one in the dashboard; shown exactly once."},"AccessKeyBearer":{"type":"http","scheme":"bearer","description":"The same rz_live_ key as a Bearer token, or an OAuth access token from the Rezmatch.ai connector flow."},"DashboardJwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Dashboard session JWT (Management API only — never accepts API keys)."}},"responses":{"BadRequest":{"description":"invalid_request / unsupported_format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"invalid_request","message":"One of text, url, or file is required"},"request_id":"req_…"}}}},"Unauthorized":{"description":"invalid_key — missing, unknown, or revoked access key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"invalid_key","message":"Missing or invalid access key"},"request_id":"req_…"}}}},"InsufficientCredits":{"description":"insufficient_credits — top up in the dashboard; the failed call is not charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"insufficient_credits","message":"Not enough credits for this call"},"request_id":"req_…"}}}},"ParseFailed":{"description":"parse_failed — the document could not be structured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"parse_failed","message":"Extraction failed"},"request_id":"req_…"}}}}},"schemas":{"DocumentInput":{"type":"object","description":"Exactly one of text, url, or file.","properties":{"text":{"type":"string","description":"Raw document text"},"url":{"type":"string","format":"uri","description":"http(s) URL of a document (PDF or text; 25s fetch timeout; 10MB cap)"},"file":{"type":"string","format":"byte","description":"Base64-encoded document bytes (PDF or plain text; 10MB cap)"}}},"Envelope":{"type":"object","required":["success","data","credits_used","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","description":"Endpoint payload"},"credits_used":{"type":"integer"},"request_id":{"type":"string"}}},"ErrorEnvelope":{"type":"object","required":["success","error","request_id"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","unsupported_format","invalid_key","insufficient_credits","not_found","idempotency_conflict","parse_failed","missing_candidate","missing_role","rate_limited","internal_error"]},"message":{"type":"string"}}},"request_id":{"type":"string"}}},"Seniority":{"type":"string","nullable":true,"enum":["intern","junior","mid","senior","staff","principal","lead","exec",null]},"Candidate":{"type":"object","description":"Normalized candidate (résumé) JSON. Dates render as YYYY-MM when the month is known, YYYY otherwise. Rezmatch.ai never stores this — it exists only in the response.","properties":{"candidate_id":{"type":"string","description":"Ephemeral identifier"},"contact":{"type":"object","properties":{"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true,"description":"Lowercased"},"phone":{"type":"string","nullable":true,"description":"E.164 (+14125550100) when derivable"},"location":{"type":"string","nullable":true,"description":"City, Region, Country"},"links":{"type":"array","items":{"type":"string"},"description":"Full https:// URLs"}}},"summary":{"type":"string","nullable":true},"total_experience_months":{"type":"integer","nullable":true},"seniority":{"$ref":"#/components/schemas/Seniority"},"work_history":{"type":"array","items":{"type":"object","properties":{"employer":{"type":"string"},"employer_normalized":{"type":"string","description":"Canonical parent-brand name"},"title":{"type":"string"},"title_normalized":{"type":"string"},"seniority":{"$ref":"#/components/schemas/Seniority"},"start":{"type":"string","nullable":true,"example":"2021-03"},"end":{"type":"string","nullable":true,"description":"null = current position"},"tenure_months":{"type":"integer","nullable":true},"skills":{"type":"array","items":{"type":"string"}},"highlights":{"type":"array","items":{"type":"string"}}}}},"education":{"type":"array","items":{"type":"object","properties":{"institution":{"type":"string"},"institution_normalized":{"type":"string","description":"Official name"},"degree":{"type":"string","nullable":true},"degree_level":{"type":"string","nullable":true,"enum":["high_school","associate","bachelor","master","doctorate","professional","certificate","bootcamp","other",null]},"field":{"type":"string","nullable":true},"field_normalized":{"type":"string","nullable":true},"start":{"type":"string","nullable":true},"end":{"type":"string","nullable":true,"example":"2018"}}}},"skills":{"type":"array","items":{"type":"object","properties":{"raw":{"type":"string","description":"As written in the document"},"canonical":{"type":"string","description":"Canonical name, any industry"},"taxonomy_id":{"type":"string","nullable":true,"description":"Stable ID when the seed taxonomy knows the skill"}}}},"certifications":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"issuer":{"type":"string","nullable":true},"year":{"type":"integer","nullable":true}}}},"languages":{"type":"array","items":{"type":"string"}},"scoring_view":{"type":"object","description":"The bias-redacted feature set /match scores on: job-relevant features only.","properties":{"redacted_fields":{"type":"array","items":{"type":"string"}},"features":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"string"}},"seniority":{"$ref":"#/components/schemas/Seniority"},"total_experience_months":{"type":"integer","nullable":true}}}}}}},"Role":{"type":"object","description":"Normalized role (job description) JSON.","properties":{"role_id":{"type":"string"},"title":{"type":"string"},"title_normalized":{"type":"string"},"seniority":{"$ref":"#/components/schemas/Seniority"},"location":{"type":"string","nullable":true},"employment_type":{"type":"string","nullable":true,"enum":["full_time","part_time","contract","internship","temporary",null]},"must_have_skills":{"type":"array","items":{"type":"object","properties":{"canonical":{"type":"string"},"taxonomy_id":{"type":"string","nullable":true},"min_years":{"type":"integer","nullable":true}}}},"nice_to_have_skills":{"type":"array","items":{"type":"object","properties":{"canonical":{"type":"string"},"taxonomy_id":{"type":"string","nullable":true}}}},"responsibilities":{"type":"array","items":{"type":"string"}},"qualifications":{"type":"array","items":{"type":"string"}},"min_experience_months":{"type":"integer","nullable":true}}},"MatchInput":{"type":"object","description":"One candidate source and one role source.","properties":{"candidate":{"$ref":"#/components/schemas/Candidate"},"resume_text":{"type":"string"},"resume_url":{"type":"string","format":"uri"},"resume_file":{"type":"string","format":"byte"},"role":{"$ref":"#/components/schemas/Role"},"jd_text":{"type":"string"},"jd_url":{"type":"string","format":"uri"},"jd_file":{"type":"string","format":"byte"},"explain":{"type":"boolean","default":true,"description":"Include the prose notes"}}},"MatchResult":{"type":"object","properties":{"score":{"type":"integer","minimum":0,"maximum":100},"band":{"type":"string","enum":["weak","moderate","good","strong","excellent"]},"explanation":{"type":"object","properties":{"met":{"type":"array","items":{"type":"object","properties":{"requirement":{"type":"string"},"evidence":{"type":"string","nullable":true},"verified":{"type":"boolean"}}}},"missed":{"type":"array","items":{"type":"object","properties":{"requirement":{"type":"string"},"severity":{"type":"string","enum":["must_have","nice_to_have"]}}}},"over_qualified":{"type":"boolean"},"under_qualified":{"type":"boolean"},"seniority_fit":{"type":"string","enum":["below","match","above"]},"notes":{"type":"string","description":"2-4 grounded sentences; never a verdict"}}},"signals":{"type":"object","properties":{"must_have_coverage":{"type":"number"},"nice_to_have_coverage":{"type":"number"},"skill_similarity":{"type":"number"},"seniority_gap":{"type":"integer"}}},"fairness":{"type":"object","properties":{"scored_on_redacted_input":{"type":"boolean","enum":[true]}}}}},"CandidateEnvelope":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Candidate"}}}]},"RoleEnvelope":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Role"}}}]},"MatchEnvelope":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MatchResult"}}}]}}}}