list_matched_candidates
List a job's matched candidates
All MCP toolsRead
The job's matched candidates — the same set the company's home, its Decisions and the job room's band read: the pairs the engine drew for the candidate that still stand (their card is in the candidate's round — origin matched, the job's own ranking order), then the people who said interested to this job from search (origin expressed_interest, oldest first). A pair leaves the set when either side answers: the company proposes (propose_jobs) or passes (pass_matched_candidate), the candidate says interested (it then carries interestedAt and their note) or passes, or the pair enters the pipeline. Each entry carries the four-axis fit, the candidate's note when one was sent, and the person as the consent fold allows. To propose THIS job, call propose_jobs with the entry's personToken and the jobId; to lower this job and propose another, pass_matched_candidate first, then propose_jobs with the other job. Reading the engine's rows records their exposure. Empty for a job outside your organization, unpublished, or one you may not see. While the organization's new matching is paused at zero credits, the answer is empty with paused: "credits" and nothing is read or exposed. actorPersonId is the human principal you act for (persons.id), never a credential identity: candidate agents pass the candidate, employer agents pass the hiring-side member. Paginated by keyset cursor: pass the returned nextCursor as the next call's cursor to continue; null nextCursor = the final page. Occupation references in the answer carry name as the display name in the saved language of the person this call acts for (the bound person, or the person named as the one acted for on the caller's own side; a service key acting for nobody reads the connection's language) — read the id as the identity, never the name.
Input schema
{
"type": "object",
"properties": {
"actorPersonId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The acting hiring-side member (persons.id) — the set is read as theirs."
},
"jobId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The job whose matched candidates to list (jobs.id)."
},
"limit": {
"description": "Page size, 1..50 (default 20).",
"type": "integer",
"minimum": 1,
"maximum": 50
},
"cursor": {
"description": "Opaque continuation token — the previous page's nextCursor. Omit for the first page.",
"type": "string",
"minLength": 1
}
},
"required": [
"actorPersonId",
"jobId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output schema
{
"type": "object",
"properties": {
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ref": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The standing row's identity — the card row on the engine's origin, the interest row on the search origin; a re-drawn or re-expressed pair is a new ref."
},
"personToken": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The candidate, as an opaque subject_token — propose_jobs's and pass_matched_candidate's personToken."
},
"person": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "identified"
},
"personId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
}
},
"required": [
"kind",
"personId",
"name"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "anonymous"
},
"profile": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"pattern": "^4\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$",
"description": "Contract version as a SemVer core triple with major locked to 4 (pattern \"4.<minor>.<patch>\", e.g. \"4.0.0\"). Minors are additive-only: they may only add optional fields. Other majors and non-SemVer strings are rejected."
},
"work": {
"description": "Work history, one claim per employment.",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Employer / organization name, e.g. \"ACME Corp\"."
},
"position": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Role title, e.g. \"Software Engineer\"."
},
"department": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Department within the organization, e.g. \"Payments Platform Division\"."
},
"team": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Team within the department, e.g. \"Billing Infrastructure Team\"."
},
"startDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "Start date as ISO 8601 with optional month/day, e.g. \"2019\", \"2019-04\", or \"2019-04-01\"."
},
"endDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "End date as ISO 8601 with optional month/day; absent while the position is current."
},
"current": {
"description": "Currently-employed declaration: true while the position is ongoing. The write boundary requires a dated entry to carry exactly one of endDate / current: true, so an \"ended\" and an \"ongoing\" entry can never share one stored shape; stored documents that predate the field read back unchanged and self-heal to current: true on their next write.",
"type": "boolean"
},
"summary": {
"description": "Free-text overview of the responsibilities.",
"type": "string"
},
"highlights": {
"description": "Notable accomplishments in this position.",
"type": "array",
"items": {
"type": "string",
"description": "A single accomplishment."
}
},
"employmentType": {
"description": "Employment type: \"FULL_TIME\" (regular employment), \"PART_TIME\", \"CONTRACTOR\" (outsourcing / freelance), \"TEMPORARY\" (fixed-term or dispatch), or \"INTERN\". Same vocabulary as JobPosting.employmentType (schema.org / HR Open Standards aligned). Absent = undisclosed.",
"type": "string",
"enum": [
"FULL_TIME",
"PART_TIME",
"CONTRACTOR",
"TEMPORARY",
"INTERN"
]
},
"workplaceType": {
"description": "Workplace type: how this engagement was worked — \"none\" (on-site), \"hybrid\", or \"full\" (fully remote). Same vocabulary as JobPosting.remote. Absent = undisclosed.",
"type": "string",
"enum": [
"none",
"hybrid",
"full"
]
},
"location": {
"description": "Work location as an ISO 3166-2 subdivision code, e.g. \"JP-13\" — the same format as desiredLocations and JobPosting.jobLocation. Absent = undisclosed.",
"type": "string",
"pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$"
},
"sideJob": {
"description": "Side-job flag: true when this engagement ran alongside a primary job, false when it was the primary engagement. Orthogonal to employmentType — freelance work as the main job is CONTRACTOR + sideJob false. Absent = undisclosed.",
"type": "boolean"
},
"url": {
"description": "URL of the organization / employer website (standard JSON Resume slot).",
"type": "string",
"format": "uri"
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"name",
"position",
"provenance"
],
"additionalProperties": false,
"description": "One work-history claim (an employment at one organization)."
}
},
"education": {
"description": "Education history, one claim per enrollment.",
"type": "array",
"items": {
"type": "object",
"properties": {
"institution": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "School / university name, e.g. \"University of Tokyo\"."
},
"area": {
"description": "Field of study, e.g. \"Computer Science\".",
"type": "string"
},
"studyType": {
"description": "Degree or program type, e.g. \"Bachelor\".",
"type": "string"
},
"level": {
"description": "Structured education level on the shared ordered ladder, least to most advanced: \"high_school\", \"associate\" (junior / technical / vocational college, KOSEN), \"bachelor\", \"master\", or \"doctorate\" — the job-side EDUCATION_LEVELS ladder without \"none\". Derived from studyType whenever the wording maps; studyType keeps the raw verbatim wording either way. Anything else is rejected.",
"type": "string",
"enum": [
"high_school",
"associate",
"bachelor",
"master",
"doctorate"
]
},
"startDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "Start date as ISO 8601 with optional month/day, e.g. \"2015\", \"2015-04\"."
},
"endDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "End date as ISO 8601 with optional month/day; absent while enrolled."
},
"current": {
"description": "Currently-enrolled declaration: true while the enrollment is ongoing. Same write-boundary rule as work — a dated entry carries exactly one of endDate / current: true; predating stored documents read back unchanged and self-heal on write.",
"type": "boolean"
},
"score": {
"description": "Grade / GPA as free text, e.g. \"3.67/4.0\".",
"type": "string"
},
"courses": {
"description": "Notable courses/subjects taken.",
"type": "array",
"items": {
"type": "string",
"description": "A notable course or subject."
}
},
"url": {
"description": "URL of the institution website (standard JSON Resume slot).",
"type": "string",
"format": "uri"
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"institution",
"provenance"
],
"additionalProperties": false,
"description": "One education-history claim (an enrollment at one institution)."
}
},
"skills": {
"description": "Skill claims, one raw verbatim skill per element.",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Raw verbatim skill string exactly as stated (trimmed only): one skill per element, never split on commas or slashes, never normalized away."
},
"proficiency": {
"type": "object",
"properties": {
"scale": {
"type": "string",
"const": "mw7",
"description": "Proficiency scale identifier; only \"mw7\" (matchwire's neutral 7-level responsibility ladder) is defined."
},
"level": {
"type": "integer",
"minimum": 1,
"maximum": 7,
"description": "Integer 1-7 on the mw7 ladder: 1 follow, 2 assist, 3 apply, 4 enable, 5 advise, 6 initiate, 7 set strategy. Values outside 1-7 are rejected."
}
},
"required": [
"scale",
"level"
],
"additionalProperties": false,
"description": "Structured proficiency: { scale: \"mw7\", level: 1-7 }."
},
"keywords": {
"description": "Free-form keywords pertaining to this skill.",
"type": "array",
"items": {
"type": "string",
"description": "Free-form keyword related to this skill."
}
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"name",
"provenance"
],
"additionalProperties": false,
"description": "A single skill claim with the raw verbatim name and optional structured proficiency."
}
},
"languages": {
"description": "Language abilities: coded language × common fluency tier.",
"type": "array",
"items": {
"type": "object",
"properties": {
"language": {
"type": "string",
"enum": [
"aa",
"ab",
"ae",
"af",
"ak",
"am",
"an",
"ar",
"as",
"av",
"ay",
"az",
"ba",
"be",
"bg",
"bi",
"bm",
"bn",
"bo",
"br",
"bs",
"ca",
"ce",
"ch",
"co",
"cr",
"cs",
"cu",
"cv",
"cy",
"da",
"de",
"dv",
"dz",
"ee",
"el",
"en",
"eo",
"es",
"et",
"eu",
"fa",
"ff",
"fi",
"fj",
"fo",
"fr",
"fy",
"ga",
"gd",
"gl",
"gn",
"gu",
"gv",
"ha",
"he",
"hi",
"ho",
"hr",
"ht",
"hu",
"hy",
"hz",
"ia",
"id",
"ie",
"ig",
"ii",
"ik",
"io",
"is",
"it",
"iu",
"ja",
"jv",
"ka",
"kg",
"ki",
"kj",
"kk",
"kl",
"km",
"kn",
"ko",
"kr",
"ks",
"ku",
"kv",
"kw",
"ky",
"la",
"lb",
"lg",
"li",
"ln",
"lo",
"lt",
"lu",
"lv",
"mg",
"mh",
"mi",
"mk",
"ml",
"mn",
"mr",
"ms",
"mt",
"my",
"na",
"nan",
"nb",
"nd",
"ne",
"ng",
"nl",
"nn",
"no",
"nr",
"nv",
"ny",
"oc",
"oj",
"om",
"or",
"os",
"pa",
"pi",
"pl",
"ps",
"pt",
"qu",
"rm",
"rn",
"ro",
"ru",
"rw",
"sa",
"sc",
"sd",
"se",
"sg",
"si",
"sk",
"sl",
"sm",
"sn",
"so",
"sq",
"sr",
"ss",
"st",
"su",
"sv",
"sw",
"ta",
"te",
"tg",
"th",
"ti",
"tk",
"tl",
"tn",
"to",
"tr",
"ts",
"tt",
"tw",
"ty",
"ug",
"uk",
"ur",
"uz",
"ve",
"vi",
"vo",
"wa",
"wo",
"xh",
"yi",
"yo",
"yue",
"za",
"zh",
"zu"
],
"description": "Language code from the closed vocabulary: ISO 639-1 two-letter codes plus the allowlist \"yue\" (Cantonese) and \"nan\" (Taiwanese Hokkien), e.g. \"ja\", \"en\", \"zh\". Language names, unassigned codes, region-qualified tags (\"zh-TW\"), and uppercase are rejected."
},
"fluency": {
"description": "Common self-assessed fluency tier, least to most proficient: \"basic\" (basic conversation), \"daily\" (daily conversation), \"business\" (business conversation), \"fluent\", or \"native\". Anything else (free text, CEFR grades, JLPT ranks) is rejected — test results belong in certificates.",
"type": "string",
"enum": [
"basic",
"daily",
"business",
"fluent",
"native"
]
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"language",
"provenance"
],
"additionalProperties": false,
"description": "A language ability claim: a language code from the closed vocabulary plus the common self-assessed fluency tier. Framework grades (CEFR) and test ranks (JLPT) are not level keys — a rank is a credential and belongs in certificates (ADR-0174)."
}
},
"certificates": {
"description": "Certification claims.",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Certificate name, e.g. \"AWS SAA\" or \"PMP\"."
},
"date": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "Date awarded as ISO 8601 with optional month/day."
},
"expiresAt": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "Expiration date as ISO 8601 with optional month/day; absent when the certification does not expire or the expiry is unknown."
},
"issuer": {
"description": "Issuing organization, e.g. \"IPA\".",
"type": "string"
},
"credentialId": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Issuer-assigned credential / license number as printed on the credential, e.g. \"AP-2016-10-12345\"."
},
"url": {
"description": "URL to the certificate or issuer page.",
"type": "string",
"format": "uri"
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"name",
"provenance"
],
"additionalProperties": false,
"description": "One certification claim."
}
},
"awards": {
"description": "Award claims.",
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Award title, e.g. \"CEO Award\"."
},
"date": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "Date awarded as ISO 8601 with optional month/day."
},
"awarder": {
"description": "Who granted the award.",
"type": "string"
},
"summary": {
"description": "What the award was received for.",
"type": "string"
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"title",
"provenance"
],
"additionalProperties": false,
"description": "One award claim."
}
},
"publications": {
"description": "Publication claims (books, articles, papers, talks).",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Publication title, e.g. \"Scaling Payment Infrastructure in Practice\"."
},
"publisher": {
"description": "Publisher / venue, e.g. \"O'Reilly\".",
"type": "string"
},
"releaseDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "Release date as ISO 8601 with optional month/day."
},
"url": {
"description": "URL to the publication.",
"type": "string",
"format": "uri"
},
"summary": {
"description": "Short free-text description of the publication.",
"type": "string"
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"name",
"provenance"
],
"additionalProperties": false,
"description": "One publication claim (an authored book, article, paper, or talk write-up)."
}
},
"projects": {
"description": "Project claims (OSS, side projects, notable engagements).",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Project name, e.g. \"matchwire\" or \"internal auth platform renewal\"."
},
"description": {
"description": "Short free-text summary of the project.",
"type": "string"
},
"highlights": {
"description": "Notable accomplishments on this project.",
"type": "array",
"items": {
"type": "string",
"description": "A single accomplishment."
}
},
"keywords": {
"description": "Keywords (technologies, themes) pertaining to this project.",
"type": "array",
"items": {
"type": "string",
"description": "A technology or theme related to this project."
}
},
"startDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "Start date as ISO 8601 with optional month/day, e.g. \"2023\", \"2023-04\"."
},
"endDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "End date as ISO 8601 with optional month/day; absent while the project is ongoing."
},
"url": {
"description": "URL to the project (repository, product page, …).",
"type": "string",
"format": "uri"
},
"roles": {
"description": "Roles held on this project, e.g. [\"Maintainer\", \"Team Lead\"].",
"type": "array",
"items": {
"type": "string",
"description": "A role held on this project."
}
},
"entity": {
"description": "Entity the project belongs to, e.g. an employer or community name.",
"type": "string"
},
"type": {
"description": "Free-text project type, e.g. \"application\", \"library\", \"volunteering\".",
"type": "string"
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"name",
"provenance"
],
"additionalProperties": false,
"description": "One project claim (OSS, side project, or notable engagement)."
}
},
"volunteer": {
"description": "Volunteer-work claims, one per engagement.",
"type": "array",
"items": {
"type": "object",
"properties": {
"organization": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Organization name, e.g. \"Code for Japan\"."
},
"position": {
"description": "Role title, e.g. \"Organizer\".",
"type": "string"
},
"url": {
"description": "URL of the organization website.",
"type": "string",
"format": "uri"
},
"startDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "Start date as ISO 8601 with optional month/day, e.g. \"2021\", \"2021-04\"."
},
"endDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "End date as ISO 8601 with optional month/day; absent while the engagement is current."
},
"summary": {
"description": "Free-text overview of the volunteer work.",
"type": "string"
},
"highlights": {
"description": "Notable accomplishments in this engagement.",
"type": "array",
"items": {
"type": "string",
"description": "A single accomplishment."
}
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"organization",
"provenance"
],
"additionalProperties": false,
"description": "One volunteer-work claim (an engagement at one organization)."
}
},
"interests": {
"description": "Interest claims (topics and causes).",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$",
"description": "Interest name, e.g. \"distributed systems\" or \"Generative AI\"."
},
"keywords": {
"description": "Free-form keywords pertaining to this interest.",
"type": "array",
"items": {
"type": "string",
"description": "A free-form keyword related to this interest."
}
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"name",
"provenance"
],
"additionalProperties": false,
"description": "One interest claim (a topic or cause the candidate cares about)."
}
},
"desiredSalaries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code (exactly three uppercase letters). Required — no default."
},
"min": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Desired annual lower bound in raw currency units (non-negative integer). Required — a row without a lower bound does not exist in the contract."
},
"max": {
"description": "Optional annual upper bound in raw currency units; the posting↔row match never reads it, while the shared internal candidate facet fold reads it as the row's upper bound. Must be >= min when present.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"unit": {
"default": "YEAR",
"description": "Salary period unit; rows are always annual (\"YEAR\").",
"type": "string",
"const": "YEAR"
}
},
"required": [
"currency",
"min",
"unit"
],
"additionalProperties": false,
"description": "One per-currency desired-salary lower-bound row (annual): matching is strict against postings in this row's currency only — never converted, never compared across currencies."
},
"description": "Desired salaries: per-currency annual lower-bound rows, one row per currency. An EMPTY array means \"no salary condition\"."
},
"currentSalary": {
"type": "object",
"properties": {
"currency": {
"default": "JPY",
"description": "ISO 4217 currency code (exactly three uppercase letters). Defaults to \"JPY\".",
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"amount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Current annual salary as a non-negative integer in `currency`."
},
"provenance": {
"default": "provided",
"description": "How this claim entered the system: \"provided\" (self-reported, the default), \"observed\", or \"inferred\". Verification is orthogonal and lives in verification_annotations, never inside the profile.",
"type": "string",
"enum": [
"provided",
"observed",
"inferred"
]
}
},
"required": [
"currency",
"amount",
"provenance"
],
"additionalProperties": false,
"description": "Current annual salary: a non-negative integer amount in an ISO 4217 currency."
},
"mobility": {
"description": "Mobility: the ordered 3-level job-change intent (\"not_looking\" < \"open_to_move\" < \"actively_looking\"), edited only on /conditions (ADR-0084). Side-job interest is the separate sideJobDesire axis, never a mobility value; the write choke moves a residual side-job value onto that axis (normalizeMobility).",
"type": "string",
"enum": [
"not_looking",
"open_to_move",
"actively_looking"
]
},
"sideJobDesire": {
"type": "string",
"enum": [
"not_open",
"open"
],
"description": "Side-job desire: \"open\" or \"not_open\". Orthogonal to mobility."
},
"openToWork": {
"description": "Open-to-work: whether intent fields may surface to non-self viewers. Absent means false, deny-by-default (never captured). DERIVED from mobility (ADR-0084): the write chokes normalize it to deriveOpenToWork — true iff mobility is \"open_to_move\" or above — so it is never an independent preference.",
"type": "boolean"
},
"availability": {
"type": "object",
"properties": {
"earliestStartDate": {
"type": "string",
"pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
"description": "Earliest start date as ISO 8601 with optional month/day, e.g. \"2026-10\" or \"2026-10-01\"."
},
"weeklyHours": {
"description": "Available hours per week as a positive integer.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"additionalProperties": false,
"description": "Availability window: earliest start date and weekly available hours (both optional)."
},
"desiredLocations": {
"description": "Desired work locations: a mixed list of whole countries (ISO 3166-1 alpha-2, e.g. \"US\") and/or regions (ISO 3166-2 subdivisions, e.g. \"JP-13\"), e.g. [\"US\", \"JP-13\"], at least one (an EMPTY array is rejected — absent is the one spelling of \"not yet set\", and a person with no desired locations enters no new matching).",
"minItems": 1,
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code: exactly two uppercase letters, e.g. \"JP\". Three-letter codes (\"JPN\"), subdivision codes (\"JP-13\"), country names, and lowercase are rejected."
},
{
"type": "string",
"pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$",
"description": "ISO 3166-2 subdivision code: two uppercase letters, a hyphen, then 1-3 uppercase alphanumerics, e.g. \"JP-13\" (Tokyo). Country-only codes (\"JP\"), place names, and lowercase are rejected."
}
],
"description": "Desired-location entry: a whole country as an ISO 3166-1 alpha-2 code (e.g. \"US\") or one region as an ISO 3166-2 subdivision code (e.g. \"JP-13\"). Names, lowercase, and three-letter codes are rejected."
}
},
"desiredOccupations": {
"description": "Desired occupations: references { id, name? } to occupation rows, unique by id, in the order stated. An EMPTY array means \"not limiting by occupation\" — same meaning as absent (the desiredLocations posture).",
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The occupation's number (an `occupations` row) — the identity predicates count on."
},
"name": {
"description": "The row's display name in the reader's language, added when a read answers (trimmed, non-empty). Optional on a write and never stored — a stored reference carries the number alone.",
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$"
}
},
"required": [
"id"
],
"additionalProperties": false,
"description": "Occupation reference: { id, name? } — the row's number, plus the display name a read adds in the reader's language (a write may carry one; it is not stored)."
}
},
"desiredOfficeFrequency": {
"type": "object",
"properties": {
"min": {
"type": "string",
"enum": [
"remote_only",
"office_monthly",
"office_1_2_days",
"office_3_4_days",
"office_daily_remote_ok",
"office_daily"
],
"description": "The most remote-leaning end of the accepted range (inclusive)."
},
"max": {
"type": "string",
"enum": [
"remote_only",
"office_monthly",
"office_1_2_days",
"office_3_4_days",
"office_daily_remote_ok",
"office_daily"
],
"description": "The most office-leaning end of the accepted range (inclusive)."
}
},
"required": [
"min",
"max"
],
"additionalProperties": false,
"description": "Desired office frequency: the accepted CONTIGUOUS range on the ordered 6-level office-frequency scale, given by its two ends — min = most remote-leaning, max = most office-leaning, both inclusive. Absent = no constraint on this axis."
},
"desiredEmploymentTypes": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"type": "string",
"enum": [
"FULL_TIME",
"PART_TIME",
"CONTRACTOR",
"TEMPORARY",
"INTERN"
],
"description": "Employment type (schema.org vocabulary): \"FULL_TIME\", \"PART_TIME\", \"CONTRACTOR\", \"TEMPORARY\", or \"INTERN\". Other values are rejected."
},
"description": "Desired employment types: the employment forms the person accepts when moving to a new primary job, from the shared vocabulary (\"FULL_TIME\", \"PART_TIME\", \"CONTRACTOR\", \"TEMPORARY\", \"INTERN\"), unique, in the order stated, at least one (an EMPTY array is rejected — \"not limiting\" is spelled by selecting every form). A mobility-dependent axis: while mobility is \"not_looking\" the value is not used for matching (it is retained). Orthogonal to sideJobDesire: the side-job axis stays binary and never carries a form."
}
},
"required": [
"schemaVersion"
],
"additionalProperties": false,
"description": "Pseudonymous matchwire candidate profile: the canonical CandidateProfile minus the basics (PII) block. Strict at every nesting level; versioned via the source document's schemaVersion."
}
},
"required": [
"kind",
"profile"
],
"additionalProperties": false
}
],
"description": "The consent fold's answer (ADR-0200): identified only under the organization's active full grant; otherwise the pseudonymous, intent-stripped projection."
},
"origin": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"matched",
"expressed_interest"
],
"description": "\"matched\" — the engine showed the person under this job; \"expressed_interest\" — the person said interested from search."
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"description": "The earliest exposure, or the standing interested's instant (ISO 8601, UTC)."
}
},
"required": [
"kind",
"at"
],
"additionalProperties": false,
"description": "matched — the engine drew the pair for the candidate (the job's ranking order); expressed_interest — the person said interested from search."
},
"fit": {
"type": "object",
"properties": {
"salary": {
"type": "string",
"enum": [
"fit",
"near",
"out",
"none"
]
},
"workstyle": {
"type": "string",
"enum": [
"fit",
"near",
"out",
"none"
]
},
"occupation": {
"type": "string",
"enum": [
"fit",
"near",
"out",
"none"
]
},
"location": {
"type": "string",
"enum": [
"fit",
"near",
"out",
"none"
]
}
},
"required": [
"salary",
"workstyle",
"occupation",
"location"
],
"additionalProperties": false,
"description": "The job's registered conditions against the person's desires on the four axes — fit, near, out, or none when an axis is undisclosed — the same chips both sides' cards wear."
},
"interestedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
{
"type": "null"
}
],
"description": "When the candidate's interest arrived on a pair the engine drew (ISO 8601, UTC); null while none, and on the search origin (whose origin instant is the interest)."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The note the candidate sent with their interest — read before answering; null when none."
},
"drawnAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
{
"type": "null"
}
],
"description": "When the engine drew the pair (ISO 8601, UTC) on the matched origin; null on the search origin."
}
},
"required": [
"ref",
"personToken",
"person",
"origin",
"fit",
"interestedAt",
"note",
"drawnAt"
],
"additionalProperties": false
},
"description": "One page of the job's matched candidates, in the set's order."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Pass as the next call's cursor to continue; null on the final page."
},
"paused": {
"description": "Present, as credits, only while the organization's new matching is paused at zero credits with auto-replenish off: the list is empty for that reason, not because no one stands; absent otherwise.",
"type": "string",
"const": "credits"
}
},
"required": [
"candidates",
"nextCursor"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}