{"openapi":"3.1.0","info":{"title":"GCA CMP REST API","version":"1.1.0","description":"**[← Developer Portal](/)** · [Interactive docs (Swagger)](/docs) · [OpenAPI spec](/openapi.json) · [Postman](/portal/postman.json)\n\nExternal REST surface for the GCA Candidate Management Platform. Worknation candidate intake and record access. Authenticate with the X-API-Key header.\n\nCompatibility: changes are backward-compatible within v1. Breaking changes ship only in a new major version (e.g. /v2), never within v1."},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"},"webhookSignature":{"type":"apiKey","in":"header","name":"X-RR-Signature","description":"HMAC-SHA256 of the raw request body, formatted `sha256=`. Verify before trusting the event."}},"schemas":{}},"paths":{"/v1/candidates":{"post":{"summary":"Receive a candidate from Worknation","tags":["candidates"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Candidate record pushed from Worknation into GCA intake.","required":["externalId","firstName","lastName","email","countryOfResidence","consentGiven"],"properties":{"externalId":{"type":"string","minLength":1,"maxLength":128,"description":"Worknation's own stable identifier for this candidate.","example":"wn-88213","examples":["wn-1004"]},"firstName":{"type":"string","minLength":1,"maxLength":120,"examples":["Zoe"]},"middleName":{"type":["string","null"],"maxLength":120,"examples":["Ama"]},"preferredName":{"type":["string","null"],"maxLength":120,"examples":["Zoe"]},"lastName":{"type":"string","minLength":1,"maxLength":120,"examples":["Mensah"]},"email":{"type":"string","format":"email","maxLength":254,"examples":["zoe.mensah@example.com"]},"phone":{"type":"string","maxLength":32,"example":"+2348012345678","examples":["+233201234567"]},"dateOfBirth":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Full calendar date YYYY-MM-DD. Partial dates are rejected.","example":"1996-04-21","examples":["1996-04-21"]},"gender":{"type":"string","enum":["male","female","non_binary","prefer_not_to_say","other"],"examples":["female"]},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG","examples":["GH"]},"countryOfResidence":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG","examples":["GH"]},"address":{"type":"object","additionalProperties":false,"description":"Structured postal address. Only country is required.","required":["country"],"properties":{"line1":{"type":"string","maxLength":200,"examples":["12 Ring Road Central"]},"line2":{"type":["string","null"],"maxLength":200,"examples":["Apartment 4B"]},"city":{"type":"string","maxLength":120,"examples":["Accra"]},"region":{"type":["string","null"],"maxLength":120,"description":"State / province.","examples":["Greater Accra"]},"postalCode":{"type":["string","null"],"maxLength":32,"examples":["GA-123-4567"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG","examples":["GH"]}}},"skills":{"type":"array","maxItems":100,"default":[],"items":{"type":"object","additionalProperties":false,"description":"A single skill assertion supplied by Worknation.","required":["name","yearsExperience"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"Welding","examples":["Plumbing"]},"yearsExperience":{"type":"number","minimum":0,"maximum":60,"example":4,"examples":[6]},"proficiency":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"examples":["expert"]},"lastUsedYear":{"type":"integer","minimum":1950,"maximum":2100,"examples":[2026]}}}},"workHistory":{"type":"array","maxItems":40,"default":[],"items":{"type":"object","additionalProperties":false,"required":["employer","jobTitle","startDate"],"properties":{"employer":{"type":"string","minLength":1,"maxLength":200,"examples":["Accra Waterworks"]},"jobTitle":{"type":"string","minLength":1,"maxLength":200,"examples":["Senior Plumber"]},"employmentType":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"],"examples":["full_time"]},"startDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Full calendar date YYYY-MM-DD. Partial dates are rejected.","example":"1996-04-21","examples":["2019-03-01"]},"endDate":{"type":["string","null"],"format":"date","description":"Null means current role.","examples":["2026-06-30"]},"isCurrent":{"type":"boolean","default":false,"examples":[false]},"location":{"type":["string","null"],"maxLength":200,"examples":["Accra, Ghana"]},"description":{"type":["string","null"],"maxLength":4000,"examples":["Led a team of five on municipal water-infrastructure projects."]}}}},"education":{"type":"array","maxItems":40,"default":[],"items":{"type":"object","additionalProperties":false,"required":["institution"],"properties":{"institution":{"type":"string","minLength":1,"maxLength":200,"examples":["Accra Technical University"]},"qualification":{"type":["string","null"],"maxLength":200,"description":"Degree or certificate name.","examples":["HND Plumbing & Gas Engineering"]},"fieldOfStudy":{"type":["string","null"],"maxLength":200,"examples":["Plumbing Engineering"]},"completionStatus":{"type":"string","enum":["completed","in_progress","incomplete","expected"],"examples":["completed"]},"startDate":{"type":["string","null"],"format":"date","examples":["2014-09-01"]},"endDate":{"type":["string","null"],"format":"date","examples":["2017-06-30"]},"grade":{"type":["string","null"],"maxLength":60,"examples":["Distinction"]}}}},"languages":{"type":"array","maxItems":30,"default":[],"items":{"type":"object","additionalProperties":false,"required":["language","proficiency"],"properties":{"language":{"type":"string","minLength":2,"maxLength":60,"example":"English","examples":["English"]},"proficiency":{"type":"string","enum":["basic","conversational","professional","fluent","native"],"examples":["fluent"]}}}},"workEligibility":{"type":"array","maxItems":30,"default":[],"items":{"type":"object","additionalProperties":false,"description":"Right to work in one target market.","required":["country","status"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG","examples":["GB"]},"status":{"type":"string","enum":["citizen","permanent_resident","work_visa","requires_sponsorship","student_visa","not_eligible","unknown"],"examples":["requires_sponsorship"]},"visaType":{"type":["string","null"],"maxLength":120,"examples":["Skilled Worker"]},"expiresAt":{"type":["string","null"],"format":"date","examples":["2028-12-31"]}}}},"jobPreferences":{"type":"object","additionalProperties":false,"properties":{"desiredTitles":{"type":"array","maxItems":20,"default":[],"items":{"type":"string","maxLength":200,"examples":["Plumber"]}},"employmentTypes":{"type":"array","maxItems":8,"default":[],"items":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"],"examples":["full_time"]}},"preferredCountries":{"type":"array","maxItems":30,"default":[],"items":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG","examples":["GB"]}},"openToRelocation":{"type":["boolean","null"],"examples":[true]},"openToRemote":{"type":["boolean","null"],"examples":[false]},"salaryExpectation":{"type":"object","additionalProperties":false,"required":["currency"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 code.","examples":["GBP"]},"min":{"type":["number","null"],"minimum":0,"examples":[32000]},"max":{"type":["number","null"],"minimum":0,"examples":[45000]},"period":{"type":"string","enum":["hourly","daily","weekly","monthly","annual"],"default":"annual","examples":["annual"]}}}}},"referees":{"type":"array","maxItems":10,"default":[],"items":{"type":"object","additionalProperties":false,"description":"Reference contact. Holds PII — excluded from the safe projection.","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Kwame Asante"]},"relationship":{"type":["string","null"],"maxLength":120,"examples":["Former manager"]},"company":{"type":["string","null"],"maxLength":200,"examples":["Accra Waterworks"]},"email":{"type":["string","null"],"format":"email","maxLength":254,"examples":["kwame.asante@example.com"]},"phone":{"type":["string","null"],"maxLength":32,"examples":["+233209876543"]}}}},"tags":{"type":"array","maxItems":50,"default":[],"items":{"type":"string","maxLength":60,"examples":["trades"]}},"source":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string","maxLength":60,"default":"worknation","examples":["worknation"]},"sourceChannel":{"type":["string","null"],"maxLength":120,"description":"Job board, referral, etc.","examples":["referral"]},"campaign":{"type":["string","null"],"maxLength":120,"examples":["gca-africa-2026"]},"submittedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-14T10:30:00Z"]}}},"documents":{"type":"array","maxItems":50,"default":[],"items":{"type":"object","additionalProperties":false,"description":"A typed document with version history. INVARIANTS (not expressible in draft-07, enforced in intake/normalize): currentVersion must equal one of versions[].version; version numbers are unique within this Document.","required":["documentType","currentVersion","versions"],"properties":{"documentType":{"type":"string","description":"Type of an attached document. The sensitive set (identity_document, right_to_work, police_clearance, medical_certificate) is excluded from recruiter/partner projections via a fail-closed allowlist.","enum":["cv","cover_letter","resume_supplement","certification","qualification","academic_transcript","reference_letter","portfolio","video_introduction","work_sample","identity_document","right_to_work","police_clearance","medical_certificate","other"],"examples":["cv"]},"label":{"type":["string","null"],"maxLength":200,"example":"2024 CV","examples":["2024 CV"]},"currentVersion":{"type":"integer","minimum":1,"examples":[2]},"versions":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"description":"One version of a document. Reference-only — url is storage-agnostic (WN or GCA).","required":["version","url","uploadedAt"],"properties":{"version":{"type":"integer","minimum":1,"description":"Monotonic, unique within the parent Document.","examples":[1]},"url":{"type":"string","format":"uri","maxLength":2048,"description":"Reference to the file. May be https://, s3://, or any URI.","examples":["https://files.example/zoe-cv-v1.pdf"]},"fileName":{"type":["string","null"],"maxLength":255,"examples":["zoe-cv-v1.pdf"]},"contentType":{"type":["string","null"],"maxLength":127,"description":"MIME type, e.g. application/pdf.","examples":["application/pdf"]},"sizeBytes":{"type":["integer","null"],"minimum":0,"maximum":524288000,"examples":[184320]},"uploadedAt":{"type":"string","format":"date-time","examples":["2026-01-10T09:00:00Z"]},"checksum":{"type":["string","null"],"maxLength":128,"description":"Optional integrity hash, e.g. sha256:abc.","examples":["sha256:9f2b1c7a4e5d6f8091a2b3c4d5e6f708"]},"uploadedByExternalId":{"type":["string","null"],"maxLength":128,"examples":["wn-1004"]}}}}}}},"consentGiven":{"type":"boolean","description":"Candidate has consented to data processing. Required true to be accepted.","examples":[true]},"consents":{"type":"array","maxItems":20,"default":[],"items":{"type":"object","additionalProperties":false,"description":"Per-purpose, auditable consent entry (richer than the scalar consentGiven).","required":["type","granted"],"properties":{"type":{"type":"string","enum":["data_processing","marketing","background_check","data_sharing_partners"],"examples":["data_processing"]},"granted":{"type":"boolean","examples":[true]},"grantedAt":{"type":["string","null"],"format":"date-time","examples":["2026-01-10T08:55:00Z"]},"policyVersion":{"type":["string","null"],"maxLength":40,"examples":["2026-01"]}}}}}},"examples":{"candidate-rich.request":{"summary":"Full ATS candidate — every field and nested attribute populated. Per-field examples are derived from this.","value":{"externalId":"wn-1004","firstName":"Zoe","middleName":"Ama","preferredName":"Zoe","lastName":"Mensah","email":"zoe.mensah@example.com","phone":"+233201234567","dateOfBirth":"1996-04-21","gender":"female","nationality":"GH","countryOfResidence":"GH","address":{"line1":"12 Ring Road Central","line2":"Apartment 4B","city":"Accra","region":"Greater Accra","postalCode":"GA-123-4567","country":"GH"},"skills":[{"name":"Plumbing","yearsExperience":6,"proficiency":"expert","lastUsedYear":2026}],"workHistory":[{"employer":"Accra Waterworks","jobTitle":"Senior Plumber","employmentType":"full_time","startDate":"2019-03-01","endDate":"2026-06-30","isCurrent":false,"location":"Accra, Ghana","description":"Led a team of five on municipal water-infrastructure projects."}],"education":[{"institution":"Accra Technical University","qualification":"HND Plumbing & Gas Engineering","fieldOfStudy":"Plumbing Engineering","completionStatus":"completed","startDate":"2014-09-01","endDate":"2017-06-30","grade":"Distinction"}],"languages":[{"language":"English","proficiency":"fluent"},{"language":"Twi","proficiency":"native"}],"workEligibility":[{"country":"GB","status":"requires_sponsorship","visaType":"Skilled Worker","expiresAt":"2028-12-31"}],"jobPreferences":{"desiredTitles":["Plumber","Pipefitter"],"employmentTypes":["full_time","contract"],"preferredCountries":["GB","DE"],"openToRelocation":true,"openToRemote":false,"salaryExpectation":{"currency":"GBP","min":32000,"max":45000,"period":"annual"}},"referees":[{"name":"Kwame Asante","relationship":"Former manager","company":"Accra Waterworks","email":"kwame.asante@example.com","phone":"+233209876543"}],"tags":["trades","relocation-ready","verified"],"source":{"provider":"worknation","sourceChannel":"referral","campaign":"gca-africa-2026","submittedAt":"2026-07-14T10:30:00Z"},"documents":[{"documentType":"cv","label":"2024 CV","currentVersion":2,"versions":[{"version":1,"url":"https://files.example/zoe-cv-v1.pdf","fileName":"zoe-cv-v1.pdf","contentType":"application/pdf","sizeBytes":184320,"uploadedAt":"2026-01-10T09:00:00Z","checksum":"sha256:9f2b1c7a4e5d6f8091a2b3c4d5e6f708","uploadedByExternalId":"wn-1004"},{"version":2,"url":"https://files.example/zoe-cv-v2.pdf","fileName":"zoe-cv-v2.pdf","contentType":"application/pdf","sizeBytes":201728,"uploadedAt":"2026-06-02T09:00:00Z","checksum":"sha256:4c1a2b3d4e5f60718293a4b5c6d7e8f9","uploadedByExternalId":"wn-1004"}]},{"documentType":"identity_document","label":"Ghana Passport","currentVersion":1,"versions":[{"version":1,"url":"https://files.example/zoe-passport.pdf","fileName":"zoe-passport.pdf","contentType":"application/pdf","sizeBytes":512000,"uploadedAt":"2026-01-10T09:00:00Z","checksum":"sha256:aa11bb22cc33dd44ee55ff6677889900","uploadedByExternalId":"wn-1004"}]}],"consentGiven":true,"consents":[{"type":"data_processing","granted":true,"grantedAt":"2026-01-10T08:55:00Z","policyVersion":"2026-01"},{"type":"data_sharing_partners","granted":true,"grantedAt":"2026-01-10T08:56:00Z","policyVersion":"2026-01"}]}},"candidate-create.request":{"summary":"Minimal candidate — the smallest accepted request body.","value":{"externalId":"wn-88213","firstName":"Ada","lastName":"Okoro","email":"ada.okoro@example.com","countryOfResidence":"NG","skills":[{"name":"Welding","yearsExperience":4,"proficiency":"advanced"}],"consentGiven":true}}}}},"description":"Candidate record pushed from Worknation into GCA intake."},"responses":{"201":{"description":"The 201 response to POST /v1/candidates. Record is in intake, not yet promoted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"The 201 response to POST /v1/candidates. Record is in intake, not yet promoted.","required":["stagedId","externalId","status","receivedAt"],"properties":{"stagedId":{"type":"string","example":"staged_01J9Z0..."},"externalId":{"type":"string"},"status":{"enum":["received"]},"receivedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}},"401":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}}},"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"curl -X POST http://localhost:3000/v1/candidates \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"externalId\": \"wn-1004\",\n \"firstName\": \"Zoe\",\n \"middleName\": \"Ama\",\n \"preferredName\": \"Zoe\",\n \"lastName\": \"Mensah\",\n \"email\": \"zoe.mensah@example.com\",\n \"phone\": \"+233201234567\",\n \"dateOfBirth\": \"1996-04-21\",\n \"gender\": \"female\",\n \"nationality\": \"GH\",\n \"countryOfResidence\": \"GH\",\n \"address\": {\n \"line1\": \"12 Ring Road Central\",\n \"line2\": \"Apartment 4B\",\n \"city\": \"Accra\",\n \"region\": \"Greater Accra\",\n \"postalCode\": \"GA-123-4567\",\n \"country\": \"GH\"\n },\n \"skills\": [\n {\n \"name\": \"Plumbing\",\n \"yearsExperience\": 6,\n \"proficiency\": \"expert\",\n \"lastUsedYear\": 2026\n }\n ],\n \"workHistory\": [\n {\n \"employer\": \"Accra Waterworks\",\n \"jobTitle\": \"Senior Plumber\",\n \"employmentType\": \"full_time\",\n \"startDate\": \"2019-03-01\",\n \"endDate\": \"2026-06-30\",\n \"isCurrent\": false,\n \"location\": \"Accra, Ghana\",\n \"description\": \"Led a team of five on municipal water-infrastructure projects.\"\n }\n ],\n \"education\": [\n {\n \"institution\": \"Accra Technical University\",\n \"qualification\": \"HND Plumbing & Gas Engineering\",\n \"fieldOfStudy\": \"Plumbing Engineering\",\n \"completionStatus\": \"completed\",\n \"startDate\": \"2014-09-01\",\n \"endDate\": \"2017-06-30\",\n \"grade\": \"Distinction\"\n }\n ],\n \"languages\": [\n {\n \"language\": \"English\",\n \"proficiency\": \"fluent\"\n },\n {\n \"language\": \"Twi\",\n \"proficiency\": \"native\"\n }\n ],\n \"workEligibility\": [\n {\n \"country\": \"GB\",\n \"status\": \"requires_sponsorship\",\n \"visaType\": \"Skilled Worker\",\n \"expiresAt\": \"2028-12-31\"\n }\n ],\n \"jobPreferences\": {\n \"desiredTitles\": [\n \"Plumber\",\n \"Pipefitter\"\n ],\n \"employmentTypes\": [\n \"full_time\",\n \"contract\"\n ],\n \"preferredCountries\": [\n \"GB\",\n \"DE\"\n ],\n \"openToRelocation\": true,\n \"openToRemote\": false,\n \"salaryExpectation\": {\n \"currency\": \"GBP\",\n \"min\": 32000,\n \"max\": 45000,\n \"period\": \"annual\"\n }\n },\n \"referees\": [\n {\n \"name\": \"Kwame Asante\",\n \"relationship\": \"Former manager\",\n \"company\": \"Accra Waterworks\",\n \"email\": \"kwame.asante@example.com\",\n \"phone\": \"+233209876543\"\n }\n ],\n \"tags\": [\n \"trades\",\n \"relocation-ready\",\n \"verified\"\n ],\n \"source\": {\n \"provider\": \"worknation\",\n \"sourceChannel\": \"referral\",\n \"campaign\": \"gca-africa-2026\",\n \"submittedAt\": \"2026-07-14T10:30:00Z\"\n },\n \"documents\": [\n {\n \"documentType\": \"cv\",\n \"label\": \"2024 CV\",\n \"currentVersion\": 2,\n \"versions\": [\n {\n \"version\": 1,\n \"url\": \"https://files.example/zoe-cv-v1.pdf\",\n \"fileName\": \"zoe-cv-v1.pdf\",\n \"contentType\": \"application/pdf\",\n \"sizeBytes\": 184320,\n \"uploadedAt\": \"2026-01-10T09:00:00Z\",\n \"checksum\": \"sha256:9f2b1c7a4e5d6f8091a2b3c4d5e6f708\",\n \"uploadedByExternalId\": \"wn-1004\"\n },\n {\n \"version\": 2,\n \"url\": \"https://files.example/zoe-cv-v2.pdf\",\n \"fileName\": \"zoe-cv-v2.pdf\",\n \"contentType\": \"application/pdf\",\n \"sizeBytes\": 201728,\n \"uploadedAt\": \"2026-06-02T09:00:00Z\",\n \"checksum\": \"sha256:4c1a2b3d4e5f60718293a4b5c6d7e8f9\",\n \"uploadedByExternalId\": \"wn-1004\"\n }\n ]\n },\n {\n \"documentType\": \"identity_document\",\n \"label\": \"Ghana Passport\",\n \"currentVersion\": 1,\n \"versions\": [\n {\n \"version\": 1,\n \"url\": \"https://files.example/zoe-passport.pdf\",\n \"fileName\": \"zoe-passport.pdf\",\n \"contentType\": \"application/pdf\",\n \"sizeBytes\": 512000,\n \"uploadedAt\": \"2026-01-10T09:00:00Z\",\n \"checksum\": \"sha256:aa11bb22cc33dd44ee55ff6677889900\",\n \"uploadedByExternalId\": \"wn-1004\"\n }\n ]\n }\n ],\n \"consentGiven\": true,\n \"consents\": [\n {\n \"type\": \"data_processing\",\n \"granted\": true,\n \"grantedAt\": \"2026-01-10T08:55:00Z\",\n \"policyVersion\": \"2026-01\"\n },\n {\n \"type\": \"data_sharing_partners\",\n \"granted\": true,\n \"grantedAt\": \"2026-01-10T08:56:00Z\",\n \"policyVersion\": \"2026-01\"\n }\n ]\n}'"},{"lang":"JavaScript","label":"fetch","source":"const res = await fetch(\"http://localhost:3000/v1/candidates\", {\n method: \"POST\",\n headers: {\n \"X-API-Key\": \"YOUR_API_KEY\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"externalId\": \"wn-1004\",\n \"firstName\": \"Zoe\",\n \"middleName\": \"Ama\",\n \"preferredName\": \"Zoe\",\n \"lastName\": \"Mensah\",\n \"email\": \"zoe.mensah@example.com\",\n \"phone\": \"+233201234567\",\n \"dateOfBirth\": \"1996-04-21\",\n \"gender\": \"female\",\n \"nationality\": \"GH\",\n \"countryOfResidence\": \"GH\",\n \"address\": {\n \"line1\": \"12 Ring Road Central\",\n \"line2\": \"Apartment 4B\",\n \"city\": \"Accra\",\n \"region\": \"Greater Accra\",\n \"postalCode\": \"GA-123-4567\",\n \"country\": \"GH\"\n },\n \"skills\": [\n {\n \"name\": \"Plumbing\",\n \"yearsExperience\": 6,\n \"proficiency\": \"expert\",\n \"lastUsedYear\": 2026\n }\n ],\n \"workHistory\": [\n {\n \"employer\": \"Accra Waterworks\",\n \"jobTitle\": \"Senior Plumber\",\n \"employmentType\": \"full_time\",\n \"startDate\": \"2019-03-01\",\n \"endDate\": \"2026-06-30\",\n \"isCurrent\": false,\n \"location\": \"Accra, Ghana\",\n \"description\": \"Led a team of five on municipal water-infrastructure projects.\"\n }\n ],\n \"education\": [\n {\n \"institution\": \"Accra Technical University\",\n \"qualification\": \"HND Plumbing & Gas Engineering\",\n \"fieldOfStudy\": \"Plumbing Engineering\",\n \"completionStatus\": \"completed\",\n \"startDate\": \"2014-09-01\",\n \"endDate\": \"2017-06-30\",\n \"grade\": \"Distinction\"\n }\n ],\n \"languages\": [\n {\n \"language\": \"English\",\n \"proficiency\": \"fluent\"\n },\n {\n \"language\": \"Twi\",\n \"proficiency\": \"native\"\n }\n ],\n \"workEligibility\": [\n {\n \"country\": \"GB\",\n \"status\": \"requires_sponsorship\",\n \"visaType\": \"Skilled Worker\",\n \"expiresAt\": \"2028-12-31\"\n }\n ],\n \"jobPreferences\": {\n \"desiredTitles\": [\n \"Plumber\",\n \"Pipefitter\"\n ],\n \"employmentTypes\": [\n \"full_time\",\n \"contract\"\n ],\n \"preferredCountries\": [\n \"GB\",\n \"DE\"\n ],\n \"openToRelocation\": true,\n \"openToRemote\": false,\n \"salaryExpectation\": {\n \"currency\": \"GBP\",\n \"min\": 32000,\n \"max\": 45000,\n \"period\": \"annual\"\n }\n },\n \"referees\": [\n {\n \"name\": \"Kwame Asante\",\n \"relationship\": \"Former manager\",\n \"company\": \"Accra Waterworks\",\n \"email\": \"kwame.asante@example.com\",\n \"phone\": \"+233209876543\"\n }\n ],\n \"tags\": [\n \"trades\",\n \"relocation-ready\",\n \"verified\"\n ],\n \"source\": {\n \"provider\": \"worknation\",\n \"sourceChannel\": \"referral\",\n \"campaign\": \"gca-africa-2026\",\n \"submittedAt\": \"2026-07-14T10:30:00Z\"\n },\n \"documents\": [\n {\n \"documentType\": \"cv\",\n \"label\": \"2024 CV\",\n \"currentVersion\": 2,\n \"versions\": [\n {\n \"version\": 1,\n \"url\": \"https://files.example/zoe-cv-v1.pdf\",\n \"fileName\": \"zoe-cv-v1.pdf\",\n \"contentType\": \"application/pdf\",\n \"sizeBytes\": 184320,\n \"uploadedAt\": \"2026-01-10T09:00:00Z\",\n \"checksum\": \"sha256:9f2b1c7a4e5d6f8091a2b3c4d5e6f708\",\n \"uploadedByExternalId\": \"wn-1004\"\n },\n {\n \"version\": 2,\n \"url\": \"https://files.example/zoe-cv-v2.pdf\",\n \"fileName\": \"zoe-cv-v2.pdf\",\n \"contentType\": \"application/pdf\",\n \"sizeBytes\": 201728,\n \"uploadedAt\": \"2026-06-02T09:00:00Z\",\n \"checksum\": \"sha256:4c1a2b3d4e5f60718293a4b5c6d7e8f9\",\n \"uploadedByExternalId\": \"wn-1004\"\n }\n ]\n },\n {\n \"documentType\": \"identity_document\",\n \"label\": \"Ghana Passport\",\n \"currentVersion\": 1,\n \"versions\": [\n {\n \"version\": 1,\n \"url\": \"https://files.example/zoe-passport.pdf\",\n \"fileName\": \"zoe-passport.pdf\",\n \"contentType\": \"application/pdf\",\n \"sizeBytes\": 512000,\n \"uploadedAt\": \"2026-01-10T09:00:00Z\",\n \"checksum\": \"sha256:aa11bb22cc33dd44ee55ff6677889900\",\n \"uploadedByExternalId\": \"wn-1004\"\n }\n ]\n }\n ],\n \"consentGiven\": true,\n \"consents\": [\n {\n \"type\": \"data_processing\",\n \"granted\": true,\n \"grantedAt\": \"2026-01-10T08:55:00Z\",\n \"policyVersion\": \"2026-01\"\n },\n {\n \"type\": \"data_sharing_partners\",\n \"granted\": true,\n \"grantedAt\": \"2026-01-10T08:56:00Z\",\n \"policyVersion\": \"2026-01\"\n }\n ]\n}),\n})\nconst data = await res.json()"},{"lang":"Python","label":"requests","source":"import requests, json\n\npayload = json.loads(r\"\"\"{\n \"externalId\": \"wn-1004\",\n \"firstName\": \"Zoe\",\n \"middleName\": \"Ama\",\n \"preferredName\": \"Zoe\",\n \"lastName\": \"Mensah\",\n \"email\": \"zoe.mensah@example.com\",\n \"phone\": \"+233201234567\",\n \"dateOfBirth\": \"1996-04-21\",\n \"gender\": \"female\",\n \"nationality\": \"GH\",\n \"countryOfResidence\": \"GH\",\n \"address\": {\n \"line1\": \"12 Ring Road Central\",\n \"line2\": \"Apartment 4B\",\n \"city\": \"Accra\",\n \"region\": \"Greater Accra\",\n \"postalCode\": \"GA-123-4567\",\n \"country\": \"GH\"\n },\n \"skills\": [\n {\n \"name\": \"Plumbing\",\n \"yearsExperience\": 6,\n \"proficiency\": \"expert\",\n \"lastUsedYear\": 2026\n }\n ],\n \"workHistory\": [\n {\n \"employer\": \"Accra Waterworks\",\n \"jobTitle\": \"Senior Plumber\",\n \"employmentType\": \"full_time\",\n \"startDate\": \"2019-03-01\",\n \"endDate\": \"2026-06-30\",\n \"isCurrent\": false,\n \"location\": \"Accra, Ghana\",\n \"description\": \"Led a team of five on municipal water-infrastructure projects.\"\n }\n ],\n \"education\": [\n {\n \"institution\": \"Accra Technical University\",\n \"qualification\": \"HND Plumbing & Gas Engineering\",\n \"fieldOfStudy\": \"Plumbing Engineering\",\n \"completionStatus\": \"completed\",\n \"startDate\": \"2014-09-01\",\n \"endDate\": \"2017-06-30\",\n \"grade\": \"Distinction\"\n }\n ],\n \"languages\": [\n {\n \"language\": \"English\",\n \"proficiency\": \"fluent\"\n },\n {\n \"language\": \"Twi\",\n \"proficiency\": \"native\"\n }\n ],\n \"workEligibility\": [\n {\n \"country\": \"GB\",\n \"status\": \"requires_sponsorship\",\n \"visaType\": \"Skilled Worker\",\n \"expiresAt\": \"2028-12-31\"\n }\n ],\n \"jobPreferences\": {\n \"desiredTitles\": [\n \"Plumber\",\n \"Pipefitter\"\n ],\n \"employmentTypes\": [\n \"full_time\",\n \"contract\"\n ],\n \"preferredCountries\": [\n \"GB\",\n \"DE\"\n ],\n \"openToRelocation\": true,\n \"openToRemote\": false,\n \"salaryExpectation\": {\n \"currency\": \"GBP\",\n \"min\": 32000,\n \"max\": 45000,\n \"period\": \"annual\"\n }\n },\n \"referees\": [\n {\n \"name\": \"Kwame Asante\",\n \"relationship\": \"Former manager\",\n \"company\": \"Accra Waterworks\",\n \"email\": \"kwame.asante@example.com\",\n \"phone\": \"+233209876543\"\n }\n ],\n \"tags\": [\n \"trades\",\n \"relocation-ready\",\n \"verified\"\n ],\n \"source\": {\n \"provider\": \"worknation\",\n \"sourceChannel\": \"referral\",\n \"campaign\": \"gca-africa-2026\",\n \"submittedAt\": \"2026-07-14T10:30:00Z\"\n },\n \"documents\": [\n {\n \"documentType\": \"cv\",\n \"label\": \"2024 CV\",\n \"currentVersion\": 2,\n \"versions\": [\n {\n \"version\": 1,\n \"url\": \"https://files.example/zoe-cv-v1.pdf\",\n \"fileName\": \"zoe-cv-v1.pdf\",\n \"contentType\": \"application/pdf\",\n \"sizeBytes\": 184320,\n \"uploadedAt\": \"2026-01-10T09:00:00Z\",\n \"checksum\": \"sha256:9f2b1c7a4e5d6f8091a2b3c4d5e6f708\",\n \"uploadedByExternalId\": \"wn-1004\"\n },\n {\n \"version\": 2,\n \"url\": \"https://files.example/zoe-cv-v2.pdf\",\n \"fileName\": \"zoe-cv-v2.pdf\",\n \"contentType\": \"application/pdf\",\n \"sizeBytes\": 201728,\n \"uploadedAt\": \"2026-06-02T09:00:00Z\",\n \"checksum\": \"sha256:4c1a2b3d4e5f60718293a4b5c6d7e8f9\",\n \"uploadedByExternalId\": \"wn-1004\"\n }\n ]\n },\n {\n \"documentType\": \"identity_document\",\n \"label\": \"Ghana Passport\",\n \"currentVersion\": 1,\n \"versions\": [\n {\n \"version\": 1,\n \"url\": \"https://files.example/zoe-passport.pdf\",\n \"fileName\": \"zoe-passport.pdf\",\n \"contentType\": \"application/pdf\",\n \"sizeBytes\": 512000,\n \"uploadedAt\": \"2026-01-10T09:00:00Z\",\n \"checksum\": \"sha256:aa11bb22cc33dd44ee55ff6677889900\",\n \"uploadedByExternalId\": \"wn-1004\"\n }\n ]\n }\n ],\n \"consentGiven\": true,\n \"consents\": [\n {\n \"type\": \"data_processing\",\n \"granted\": true,\n \"grantedAt\": \"2026-01-10T08:55:00Z\",\n \"policyVersion\": \"2026-01\"\n },\n {\n \"type\": \"data_sharing_partners\",\n \"granted\": true,\n \"grantedAt\": \"2026-01-10T08:56:00Z\",\n \"policyVersion\": \"2026-01\"\n }\n ]\n}\"\"\")\n\nres = requests.post(\n \"http://localhost:3000/v1/candidates\",\n headers={\"X-API-Key\": \"YOUR_API_KEY\"},\n json=payload,\n)\ndata = res.json()"}],"parameters":[]}},"/v1/candidates/{id}":{"get":{"summary":"Fetch a candidate record","tags":["candidates"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"The recruiter/partner-safe projection. Excludes PII/sensitive data: email, phone, date of birth, gender, full address, referees, and sensitive document types (identity_document, right_to_work, police_clearance, medical_certificate).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"The recruiter/partner-safe projection. Excludes PII/sensitive data: email, phone, date of birth, gender, full address, referees, and sensitive document types (identity_document, right_to_work, police_clearance, medical_certificate).","required":["id","externalId","firstName","lastName","countryOfResidence","skills","status","workReadinessScore","updatedAt"],"properties":{"id":{"type":"string","examples":["cand_01J9Z0ABCXYZ"]},"externalId":{"type":"string","examples":["wn-1004"]},"firstName":{"type":"string","examples":["Zoe"]},"middleName":{"type":["null","string"],"examples":["Ama"]},"preferredName":{"type":["null","string"],"examples":["Zoe"]},"lastName":{"type":"string","examples":["Mensah"]},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG","examples":["GH"]},"countryOfResidence":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG","examples":["GH"]},"skills":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"A single skill assertion supplied by Worknation.","required":["name","yearsExperience"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"Welding","examples":["Plumbing"]},"yearsExperience":{"type":"number","minimum":0,"maximum":60,"example":4,"examples":[6]},"proficiency":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"examples":["expert"]},"lastUsedYear":{"type":"integer","minimum":1950,"maximum":2100,"examples":[2026]}}}},"workHistory":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["employer","jobTitle","startDate"],"properties":{"employer":{"type":"string","minLength":1,"maxLength":200,"examples":["Accra Waterworks"]},"jobTitle":{"type":"string","minLength":1,"maxLength":200,"examples":["Senior Plumber"]},"employmentType":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"],"examples":["full_time"]},"startDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Full calendar date YYYY-MM-DD. Partial dates are rejected.","example":"1996-04-21","examples":["2019-03-01"]},"endDate":{"type":["null","string"],"format":"date","description":"Null means current role.","examples":["2026-06-30"]},"isCurrent":{"type":"boolean","default":false,"examples":[false]},"location":{"type":["null","string"],"maxLength":200,"examples":["Accra, Ghana"]},"description":{"type":["null","string"],"maxLength":4000,"examples":["Led a team of five on municipal water-infrastructure projects."]}}}},"education":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["institution"],"properties":{"institution":{"type":"string","minLength":1,"maxLength":200,"examples":["Accra Technical University"]},"qualification":{"type":["null","string"],"maxLength":200,"description":"Degree or certificate name.","examples":["HND Plumbing & Gas Engineering"]},"fieldOfStudy":{"type":["null","string"],"maxLength":200,"examples":["Plumbing Engineering"]},"completionStatus":{"type":"string","enum":["completed","in_progress","incomplete","expected"],"examples":["completed"]},"startDate":{"type":["null","string"],"format":"date","examples":["2014-09-01"]},"endDate":{"type":["null","string"],"format":"date","examples":["2017-06-30"]},"grade":{"type":["null","string"],"maxLength":60,"examples":["Distinction"]}}}},"languages":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["language","proficiency"],"properties":{"language":{"type":"string","minLength":2,"maxLength":60,"example":"English","examples":["English"]},"proficiency":{"type":"string","enum":["basic","conversational","professional","fluent","native"],"examples":["fluent"]}}}},"workEligibility":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"Right to work in one target market.","required":["country","status"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG","examples":["GB"]},"status":{"type":"string","enum":["citizen","permanent_resident","work_visa","requires_sponsorship","student_visa","not_eligible","unknown"],"examples":["requires_sponsorship"]},"visaType":{"type":["null","string"],"maxLength":120,"examples":["Skilled Worker"]},"expiresAt":{"type":["null","string"],"format":"date","examples":["2028-12-31"]}}}},"jobPreferences":{"type":"object","additionalProperties":false,"properties":{"desiredTitles":{"type":"array","maxItems":20,"default":[],"items":{"type":"string","maxLength":200,"examples":["Plumber"]}},"employmentTypes":{"type":"array","maxItems":8,"default":[],"items":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"],"examples":["full_time"]}},"preferredCountries":{"type":"array","maxItems":30,"default":[],"items":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG","examples":["GB"]}},"openToRelocation":{"type":["null","boolean"],"examples":[true]},"openToRemote":{"type":["null","boolean"],"examples":[false]},"salaryExpectation":{"type":"object","additionalProperties":false,"required":["currency"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 code.","examples":["GBP"]},"min":{"type":["null","number"],"minimum":0,"examples":[32000]},"max":{"type":["null","number"],"minimum":0,"examples":[45000]},"period":{"type":"string","enum":["hourly","daily","weekly","monthly","annual"],"default":"annual","examples":["annual"]}}}}},"tags":{"type":"array","items":{"type":"string","maxLength":60,"examples":["trades"]}},"documents":{"type":"array","description":"Safe document types only; sensitive types are dropped by the projection.","items":{"type":"object","additionalProperties":false,"description":"A typed document with version history. INVARIANTS (not expressible in draft-07, enforced in intake/normalize): currentVersion must equal one of versions[].version; version numbers are unique within this Document.","required":["documentType","currentVersion","versions"],"properties":{"documentType":{"type":"string","description":"Type of an attached document. The sensitive set (identity_document, right_to_work, police_clearance, medical_certificate) is excluded from recruiter/partner projections via a fail-closed allowlist.","enum":["cv","cover_letter","resume_supplement","certification","qualification","academic_transcript","reference_letter","portfolio","video_introduction","work_sample","identity_document","right_to_work","police_clearance","medical_certificate","other"],"examples":["cv"]},"label":{"type":["null","string"],"maxLength":200,"example":"2024 CV","examples":["2024 CV"]},"currentVersion":{"type":"integer","minimum":1,"examples":[2]},"versions":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"description":"One version of a document. Reference-only — url is storage-agnostic (WN or GCA).","required":["version","url","uploadedAt"],"properties":{"version":{"type":"integer","minimum":1,"description":"Monotonic, unique within the parent Document.","examples":[1]},"url":{"type":"string","format":"uri","maxLength":2048,"description":"Reference to the file. May be https://, s3://, or any URI.","examples":["https://files.example/zoe-cv-v1.pdf"]},"fileName":{"type":["null","string"],"maxLength":255,"examples":["zoe-cv-v1.pdf"]},"contentType":{"type":["null","string"],"maxLength":127,"description":"MIME type, e.g. application/pdf.","examples":["application/pdf"]},"sizeBytes":{"type":["null","integer"],"minimum":0,"maximum":524288000,"examples":[184320]},"uploadedAt":{"type":"string","format":"date-time","examples":["2026-01-10T09:00:00Z"]},"checksum":{"type":["null","string"],"maxLength":128,"description":"Optional integrity hash, e.g. sha256:abc.","examples":["sha256:9f2b1c7a4e5d6f8091a2b3c4d5e6f708"]},"uploadedByExternalId":{"type":["null","string"],"maxLength":128,"examples":["wn-1004"]}}}}}}},"status":{"type":"string","enum":["intake","verified","promoted"],"examples":["promoted"]},"availabilityStatus":{"type":"string","enum":["available","unavailable","pending","employed","open_to_offers"],"examples":["available"]},"verificationStatus":{"type":"string","enum":["pending","in_review","verified","failed"],"examples":["verified"]},"workReadinessScore":{"type":["null","number"],"minimum":0,"maximum":100,"examples":[82]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-07-15T09:00:00Z"]}}},"examples":{"candidate.response":{"summary":"Safe candidate projection — every response field populated. No email, phone, DOB, address, referees, or sensitive documents.","value":{"id":"cand_01J9Z0ABCXYZ","externalId":"wn-1004","firstName":"Zoe","middleName":"Ama","preferredName":"Zoe","lastName":"Mensah","nationality":"GH","countryOfResidence":"GH","skills":[{"name":"Plumbing","yearsExperience":6,"proficiency":"expert","lastUsedYear":2026}],"workHistory":[{"employer":"Accra Waterworks","jobTitle":"Senior Plumber","employmentType":"full_time","startDate":"2019-03-01","endDate":"2026-06-30","isCurrent":false,"location":"Accra, Ghana","description":"Led a team of five on municipal water-infrastructure projects."}],"education":[{"institution":"Accra Technical University","qualification":"HND Plumbing & Gas Engineering","fieldOfStudy":"Plumbing Engineering","completionStatus":"completed","startDate":"2014-09-01","endDate":"2017-06-30","grade":"Distinction"}],"languages":[{"language":"English","proficiency":"fluent"},{"language":"Twi","proficiency":"native"}],"workEligibility":[{"country":"GB","status":"requires_sponsorship","visaType":"Skilled Worker","expiresAt":"2028-12-31"}],"jobPreferences":{"desiredTitles":["Plumber","Pipefitter"],"employmentTypes":["full_time","contract"],"preferredCountries":["GB","DE"],"openToRelocation":true,"openToRemote":false,"salaryExpectation":{"currency":"GBP","min":32000,"max":45000,"period":"annual"}},"tags":["trades","relocation-ready","verified"],"documents":[{"documentType":"cv","label":"2024 CV","currentVersion":2,"versions":[{"version":1,"url":"https://files.example/zoe-cv-v1.pdf","fileName":"zoe-cv-v1.pdf","contentType":"application/pdf","sizeBytes":184320,"uploadedAt":"2026-01-10T09:00:00Z","checksum":"sha256:9f2b1c7a4e5d6f8091a2b3c4d5e6f708","uploadedByExternalId":"wn-1004"},{"version":2,"url":"https://files.example/zoe-cv-v2.pdf","fileName":"zoe-cv-v2.pdf","contentType":"application/pdf","sizeBytes":201728,"uploadedAt":"2026-06-02T09:00:00Z","checksum":"sha256:4c1a2b3d4e5f60718293a4b5c6d7e8f9","uploadedByExternalId":"wn-1004"}]}],"status":"promoted","availabilityStatus":"available","verificationStatus":"verified","workReadinessScore":82,"updatedAt":"2026-07-15T09:00:00Z"}}}}}},"401":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}},"404":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}}}},"put":{"summary":"Amend limited candidate fields","tags":["candidates"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"PUT /v1/candidates/:id — the fields Worknation may amend. No externalId/id, no enrichment.","properties":{"firstName":{"type":"string","minLength":1,"maxLength":120},"middleName":{"type":["string","null"],"maxLength":120},"preferredName":{"type":["string","null"],"maxLength":120},"lastName":{"type":"string","minLength":1,"maxLength":120},"phone":{"type":"string","maxLength":32},"address":{"type":"object","additionalProperties":false,"description":"Structured postal address. Only country is required.","required":["country"],"properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":["string","null"],"maxLength":200},"city":{"type":"string","maxLength":120},"region":{"type":["string","null"],"maxLength":120,"description":"State / province."},"postalCode":{"type":["string","null"],"maxLength":32},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"}}},"skills":{"type":"array","maxItems":2,"items":{"type":"object","additionalProperties":false,"description":"A single skill assertion supplied by Worknation.","required":["name","yearsExperience"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"Welding"},"yearsExperience":{"type":"number","minimum":0,"maximum":60,"example":4},"proficiency":{"type":"string","enum":["beginner","intermediate","advanced","expert"]},"lastUsedYear":{"type":"integer","minimum":1950,"maximum":2100}}},"minItems":2},"workHistory":{"type":"array","maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["employer","jobTitle","startDate"],"properties":{"employer":{"type":"string","minLength":1,"maxLength":200},"jobTitle":{"type":"string","minLength":1,"maxLength":200},"employmentType":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"]},"startDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Full calendar date YYYY-MM-DD. Partial dates are rejected.","example":"1996-04-21"},"endDate":{"type":"string","format":"date","description":"Null means current role."},"isCurrent":{"type":"boolean","default":false},"location":{"type":["string","null"],"maxLength":200},"description":{"type":["string","null"],"maxLength":4000}}},"minItems":2},"education":{"type":"array","maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["institution"],"properties":{"institution":{"type":"string","minLength":1,"maxLength":200},"qualification":{"type":["string","null"],"maxLength":200,"description":"Degree or certificate name."},"fieldOfStudy":{"type":["string","null"],"maxLength":200},"completionStatus":{"type":"string","enum":["completed","in_progress","incomplete","expected"]},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"grade":{"type":["string","null"],"maxLength":60}}},"minItems":2},"languages":{"type":"array","maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["language","proficiency"],"properties":{"language":{"type":"string","minLength":2,"maxLength":60,"example":"English"},"proficiency":{"type":"string","enum":["basic","conversational","professional","fluent","native"]}}},"minItems":2},"workEligibility":{"type":"array","maxItems":2,"items":{"type":"object","additionalProperties":false,"description":"Right to work in one target market.","required":["country","status"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"},"status":{"type":"string","enum":["citizen","permanent_resident","work_visa","requires_sponsorship","student_visa","not_eligible","unknown"]},"visaType":{"type":["string","null"],"maxLength":120},"expiresAt":{"type":"string","format":"date"}}},"minItems":2},"jobPreferences":{"type":"object","additionalProperties":false,"properties":{"desiredTitles":{"type":"array","maxItems":2,"default":[],"items":{"type":"string","maxLength":200},"minItems":2},"employmentTypes":{"type":"array","maxItems":2,"default":[],"items":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"]},"minItems":2},"preferredCountries":{"type":"array","maxItems":2,"default":[],"items":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"},"minItems":2},"openToRelocation":{"type":["boolean","null"]},"openToRemote":{"type":["boolean","null"]},"salaryExpectation":{"type":"object","additionalProperties":false,"required":["currency"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 code."},"min":{"type":["number","null"],"minimum":0},"max":{"type":["number","null"],"minimum":0},"period":{"type":"string","enum":["hourly","daily","weekly","monthly","annual"],"default":"annual"}}}}},"documents":{"type":"array","maxItems":2,"items":{"type":"object","additionalProperties":false,"description":"A typed document with version history. INVARIANTS (not expressible in draft-07, enforced in intake/normalize): currentVersion must equal one of versions[].version; version numbers are unique within this Document.","required":["documentType","currentVersion","versions"],"properties":{"documentType":{"type":"string","description":"Type of an attached document. The sensitive set (identity_document, right_to_work, police_clearance, medical_certificate) is excluded from recruiter/partner projections via a fail-closed allowlist.","enum":["cv","cover_letter","resume_supplement","certification","qualification","academic_transcript","reference_letter","portfolio","video_introduction","work_sample","identity_document","right_to_work","police_clearance","medical_certificate","other"]},"label":{"type":["string","null"],"maxLength":200,"example":"2024 CV"},"currentVersion":{"type":"integer","minimum":1},"versions":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","additionalProperties":false,"description":"One version of a document. Reference-only — url is storage-agnostic (WN or GCA).","required":["version","url","uploadedAt"],"properties":{"version":{"type":"integer","minimum":1,"description":"Monotonic, unique within the parent Document."},"url":{"type":"string","format":"uri","maxLength":2048,"description":"Reference to the file. May be https://, s3://, or any URI."},"fileName":{"type":["string","null"],"maxLength":255},"contentType":{"type":["string","null"],"maxLength":127,"description":"MIME type, e.g. application/pdf."},"sizeBytes":{"type":["integer","null"],"minimum":0,"maximum":524288000},"uploadedAt":{"type":"string","format":"date-time"},"checksum":{"type":["string","null"],"maxLength":128,"description":"Optional integrity hash, e.g. sha256:abc."},"uploadedByExternalId":{"type":["string","null"],"maxLength":128}}}}}},"minItems":2},"consentGiven":{"type":"boolean"},"consents":{"type":"array","maxItems":2,"items":{"type":"object","additionalProperties":false,"description":"Per-purpose, auditable consent entry (richer than the scalar consentGiven).","required":["type","granted"],"properties":{"type":{"type":"string","enum":["data_processing","marketing","background_check","data_sharing_partners"]},"granted":{"type":"boolean"},"grantedAt":{"type":"string","format":"date-time"},"policyVersion":{"type":["string","null"],"maxLength":40}}},"minItems":2}}}}},"description":"PUT /v1/candidates/:id — the fields Worknation may amend. No externalId/id, no enrichment."},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"The recruiter/partner-safe projection. Excludes PII/sensitive data: email, phone, date of birth, gender, full address, referees, and sensitive document types (identity_document, right_to_work, police_clearance, medical_certificate).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"The recruiter/partner-safe projection. Excludes PII/sensitive data: email, phone, date of birth, gender, full address, referees, and sensitive document types (identity_document, right_to_work, police_clearance, medical_certificate).","required":["id","externalId","firstName","lastName","countryOfResidence","skills","status","workReadinessScore","updatedAt"],"properties":{"id":{"type":"string"},"externalId":{"type":"string"},"firstName":{"type":"string"},"middleName":{"type":["null","string"]},"preferredName":{"type":["null","string"]},"lastName":{"type":"string"},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"},"countryOfResidence":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"},"skills":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"A single skill assertion supplied by Worknation.","required":["name","yearsExperience"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"Welding"},"yearsExperience":{"type":"number","minimum":0,"maximum":60,"example":4},"proficiency":{"type":"string","enum":["beginner","intermediate","advanced","expert"]},"lastUsedYear":{"type":"integer","minimum":1950,"maximum":2100}}},"maxItems":2},"workHistory":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["employer","jobTitle","startDate"],"properties":{"employer":{"type":"string","minLength":1,"maxLength":200},"jobTitle":{"type":"string","minLength":1,"maxLength":200},"employmentType":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"]},"startDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Full calendar date YYYY-MM-DD. Partial dates are rejected.","example":"1996-04-21"},"endDate":{"type":"null","format":"date","description":"Null means current role."},"isCurrent":{"type":"boolean","default":false},"location":{"type":["null","string"],"maxLength":200},"description":{"type":["null","string"],"maxLength":4000}}},"maxItems":2},"education":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["institution"],"properties":{"institution":{"type":"string","minLength":1,"maxLength":200},"qualification":{"type":["null","string"],"maxLength":200,"description":"Degree or certificate name."},"fieldOfStudy":{"type":["null","string"],"maxLength":200},"completionStatus":{"type":"string","enum":["completed","in_progress","incomplete","expected"]},"startDate":{"type":"null","format":"date"},"endDate":{"type":"null","format":"date"},"grade":{"type":["null","string"],"maxLength":60}}},"maxItems":2},"languages":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["language","proficiency"],"properties":{"language":{"type":"string","minLength":2,"maxLength":60,"example":"English"},"proficiency":{"type":"string","enum":["basic","conversational","professional","fluent","native"]}}},"maxItems":2},"workEligibility":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"Right to work in one target market.","required":["country","status"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"},"status":{"type":"string","enum":["citizen","permanent_resident","work_visa","requires_sponsorship","student_visa","not_eligible","unknown"]},"visaType":{"type":["null","string"],"maxLength":120},"expiresAt":{"type":"null","format":"date"}}},"maxItems":2},"jobPreferences":{"type":"object","additionalProperties":false,"properties":{"desiredTitles":{"type":"array","maxItems":2,"default":[],"items":{"type":"string","maxLength":200},"minItems":2},"employmentTypes":{"type":"array","maxItems":2,"default":[],"items":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"]},"minItems":2},"preferredCountries":{"type":"array","maxItems":2,"default":[],"items":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"},"minItems":2},"openToRelocation":{"type":["null","boolean"]},"openToRemote":{"type":["null","boolean"]},"salaryExpectation":{"type":"object","additionalProperties":false,"required":["currency"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 code."},"min":{"type":["null","number"],"minimum":0},"max":{"type":["null","number"],"minimum":0},"period":{"type":"string","enum":["hourly","daily","weekly","monthly","annual"],"default":"annual"}}}}},"tags":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":2},"documents":{"type":"array","description":"Safe document types only; sensitive types are dropped by the projection.","items":{"type":"object","additionalProperties":false,"description":"A typed document with version history. INVARIANTS (not expressible in draft-07, enforced in intake/normalize): currentVersion must equal one of versions[].version; version numbers are unique within this Document.","required":["documentType","currentVersion","versions"],"properties":{"documentType":{"type":"string","description":"Type of an attached document. The sensitive set (identity_document, right_to_work, police_clearance, medical_certificate) is excluded from recruiter/partner projections via a fail-closed allowlist.","enum":["cv","cover_letter","resume_supplement","certification","qualification","academic_transcript","reference_letter","portfolio","video_introduction","work_sample","identity_document","right_to_work","police_clearance","medical_certificate","other"]},"label":{"type":["null","string"],"maxLength":200,"example":"2024 CV"},"currentVersion":{"type":"integer","minimum":1},"versions":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","additionalProperties":false,"description":"One version of a document. Reference-only — url is storage-agnostic (WN or GCA).","required":["version","url","uploadedAt"],"properties":{"version":{"type":"integer","minimum":1,"description":"Monotonic, unique within the parent Document."},"url":{"type":"string","format":"uri","maxLength":2048,"description":"Reference to the file. May be https://, s3://, or any URI."},"fileName":{"type":["null","string"],"maxLength":255},"contentType":{"type":["null","string"],"maxLength":127,"description":"MIME type, e.g. application/pdf."},"sizeBytes":{"type":["null","integer"],"minimum":0,"maximum":524288000},"uploadedAt":{"type":"string","format":"date-time"},"checksum":{"type":["null","string"],"maxLength":128,"description":"Optional integrity hash, e.g. sha256:abc."},"uploadedByExternalId":{"type":["null","string"],"maxLength":128}}}}}},"maxItems":2},"status":{"type":"string","enum":["intake","verified","promoted"]},"availabilityStatus":{"type":"string","enum":["available","unavailable","pending","employed","open_to_offers"]},"verificationStatus":{"type":"string","enum":["pending","in_review","verified","failed"]},"workReadinessScore":{"type":["null","number"],"minimum":0,"maximum":100},"updatedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}},"404":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}}}}},"/v1/webhook-endpoints":{"post":{"summary":"Register a webhook endpoint","tags":["webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Register a URL to receive signed webhook events.","required":["url","eventTypes"],"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"example":"https://wn.example/gca-hooks"},"eventTypes":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]}},"description":{"type":["string","null"],"maxLength":200}}}}},"description":"Register a URL to receive signed webhook events."},"responses":{"201":{"description":"Returned ONCE on create/rotate — the signingSecret is not retrievable later.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Returned ONCE on create/rotate — the signingSecret is not retrievable later.","required":["id","url","eventTypes","active","createdAt","signingSecret"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]},"maxItems":2},"description":{"type":["null","string"]},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"signingSecret":{"type":"string","example":"whsec_3f9a...redacted"}}}}}},"400":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}},"401":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}}},"parameters":[]},"get":{"summary":"List webhook endpoints","tags":["webhooks"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"A registered webhook endpoint (signing secret is never returned here).","required":["id","url","eventTypes","active","createdAt"],"properties":{"id":{"type":"string","example":"whe_01J9Z0"},"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]},"maxItems":2},"description":{"type":["null","string"]},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"maxItems":2}}}}}},"401":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}}},"parameters":[]}},"/v1/webhook-endpoints/{id}":{"get":{"summary":"Fetch a webhook endpoint","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"A registered webhook endpoint (signing secret is never returned here).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"A registered webhook endpoint (signing secret is never returned here).","required":["id","url","eventTypes","active","createdAt"],"properties":{"id":{"type":"string","example":"whe_01J9Z0"},"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]},"maxItems":2},"description":{"type":["null","string"]},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}},"404":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"401":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}},"404":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}}}}},"/v1/webhook-endpoints/{id}/test":{"post":{"summary":"Send a sample event to this endpoint","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"202":{"description":"Default Response"},"401":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}},"404":{"description":"Standard error envelope returned for 4xx/5xx.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Standard error envelope returned for 4xx/5xx.","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}}}}}}}}}},"servers":[{"url":"https://api.dev.gca.rolerelay.com","description":"Development"},{"url":"https://api.gca.rolerelay.com","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"candidates","description":"Candidate intake and records"},{"name":"webhooks","description":"Subscribe to candidate-lifecycle events"}],"webhooks":{"candidate.received":{"post":{"tags":["webhooks"],"summary":"A candidate was received into intake.","description":"GCA POSTs this event to endpoints subscribed to `candidate.received`. Verify `X-RR-Signature`, dedupe on the event `id`, and return any 2xx to acknowledge.","security":[{"webhookSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","description":"Common envelope on every webhook event.","required":["id","type","apiVersion","occurredAt","region"],"properties":{"id":{"type":"string","examples":["evt_01J9Z0ABCXYZ"]},"type":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]},"apiVersion":{"type":"string","examples":["v1"]},"occurredAt":{"type":"string","format":"date-time"},"region":{"type":"string","enum":["africa","uk","germany","australia"]}}},{"type":"object","required":["type","data"],"properties":{"type":{"const":"candidate.received"},"data":{"type":"object","additionalProperties":false,"required":["stagedId","externalId","status","receivedAt"],"properties":{"stagedId":{"type":"string","examples":["staged_01J9Z0"]},"externalId":{"type":"string","examples":["wn-1004"]},"status":{"type":"string","enum":["received"]},"receivedAt":{"type":"string","format":"date-time"}}}}}]},"examples":{"sample":{"value":{"id":"evt_received01","type":"candidate.received","apiVersion":"v1","region":"africa","occurredAt":"2026-07-15T09:00:00Z","data":{"stagedId":"staged_01J9Z0","externalId":"wn-1004","status":"received","receivedAt":"2026-07-15T09:00:00Z"}}}}}}},"responses":{"2XX":{"description":"Acknowledged. Return any 2xx; non-2xx triggers redelivery."}}}},"candidate.verified":{"post":{"tags":["webhooks"],"summary":"Identity verification completed for a candidate.","description":"GCA POSTs this event to endpoints subscribed to `candidate.verified`. Verify `X-RR-Signature`, dedupe on the event `id`, and return any 2xx to acknowledge.","security":[{"webhookSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","description":"Common envelope on every webhook event.","required":["id","type","apiVersion","occurredAt","region"],"properties":{"id":{"type":"string","examples":["evt_01J9Z0ABCXYZ"]},"type":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]},"apiVersion":{"type":"string","examples":["v1"]},"occurredAt":{"type":"string","format":"date-time"},"region":{"type":"string","enum":["africa","uk","germany","australia"]}}},{"type":"object","required":["type","data"],"properties":{"type":{"const":"candidate.verified"},"data":{"type":"object","additionalProperties":false,"required":["candidateId","externalId","verificationStatus","verifiedAt"],"properties":{"candidateId":{"type":"string","examples":["cand_01J9Z0"]},"externalId":{"type":"string","examples":["wn-1004"]},"verificationStatus":{"type":"string","enum":["verified","failed"]},"verifiedAt":{"type":"string","format":"date-time"}}}}}]},"examples":{"sample":{"value":{"id":"evt_verified01","type":"candidate.verified","apiVersion":"v1","region":"africa","occurredAt":"2026-07-15T09:00:00Z","data":{"candidateId":"cand_01J9Z0","externalId":"wn-1004","verificationStatus":"verified","verifiedAt":"2026-07-15T09:00:00Z"}}}}}}},"responses":{"2XX":{"description":"Acknowledged. Return any 2xx; non-2xx triggers redelivery."}}}},"candidate.promoted":{"post":{"tags":["webhooks"],"summary":"A candidate met the exit criteria and was promoted (now searchable).","description":"GCA POSTs this event to endpoints subscribed to `candidate.promoted`. Verify `X-RR-Signature`, dedupe on the event `id`, and return any 2xx to acknowledge.","security":[{"webhookSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","description":"Common envelope on every webhook event.","required":["id","type","apiVersion","occurredAt","region"],"properties":{"id":{"type":"string","examples":["evt_01J9Z0ABCXYZ"]},"type":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]},"apiVersion":{"type":"string","examples":["v1"]},"occurredAt":{"type":"string","format":"date-time"},"region":{"type":"string","enum":["africa","uk","germany","australia"]}}},{"type":"object","required":["type","data"],"properties":{"type":{"const":"candidate.promoted"},"data":{"type":"object","additionalProperties":false,"required":["candidateId","externalId","status","promotedAt"],"properties":{"candidateId":{"type":"string","examples":["cand_01J9Z0"]},"externalId":{"type":"string","examples":["wn-1004"]},"status":{"type":"string","enum":["promoted"]},"promotedAt":{"type":"string","format":"date-time"},"workReadinessScore":{"type":["number","null"],"minimum":0,"maximum":100,"examples":[82]}}}}}]},"examples":{"sample":{"value":{"id":"evt_promoted01","type":"candidate.promoted","apiVersion":"v1","region":"africa","occurredAt":"2026-07-15T09:00:00Z","data":{"candidateId":"cand_01J9Z0","externalId":"wn-1004","status":"promoted","promotedAt":"2026-07-15T09:00:00Z","workReadinessScore":82}}}}}}},"responses":{"2XX":{"description":"Acknowledged. Return any 2xx; non-2xx triggers redelivery."}}}},"candidate.validation_failed":{"post":{"tags":["webhooks"],"summary":"A submitted candidate failed intake validation.","description":"GCA POSTs this event to endpoints subscribed to `candidate.validation_failed`. Verify `X-RR-Signature`, dedupe on the event `id`, and return any 2xx to acknowledge.","security":[{"webhookSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","description":"Common envelope on every webhook event.","required":["id","type","apiVersion","occurredAt","region"],"properties":{"id":{"type":"string","examples":["evt_01J9Z0ABCXYZ"]},"type":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]},"apiVersion":{"type":"string","examples":["v1"]},"occurredAt":{"type":"string","format":"date-time"},"region":{"type":"string","enum":["africa","uk","germany","australia"]}}},{"type":"object","required":["type","data"],"properties":{"type":{"const":"candidate.validation_failed"},"data":{"type":"object","additionalProperties":false,"required":["stagedId","externalId","reasons"],"properties":{"stagedId":{"type":"string","examples":["staged_01J9Z0"]},"externalId":{"type":"string","examples":["wn-1004"]},"reasons":{"type":"array","minItems":1,"items":{"type":"string","examples":["missing consent"]}}}}}}]},"examples":{"sample":{"value":{"id":"evt_failed01","type":"candidate.validation_failed","apiVersion":"v1","region":"africa","occurredAt":"2026-07-15T09:00:00Z","data":{"stagedId":"staged_01J9Z0","externalId":"wn-1004","reasons":["missing consent","invalid email"]}}}}}}},"responses":{"2XX":{"description":"Acknowledged. Return any 2xx; non-2xx triggers redelivery."}}}},"candidate.consent_revoked":{"post":{"tags":["webhooks"],"summary":"A candidate revoked consent; access is frozen.","description":"GCA POSTs this event to endpoints subscribed to `candidate.consent_revoked`. Verify `X-RR-Signature`, dedupe on the event `id`, and return any 2xx to acknowledge.","security":[{"webhookSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","description":"Common envelope on every webhook event.","required":["id","type","apiVersion","occurredAt","region"],"properties":{"id":{"type":"string","examples":["evt_01J9Z0ABCXYZ"]},"type":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]},"apiVersion":{"type":"string","examples":["v1"]},"occurredAt":{"type":"string","format":"date-time"},"region":{"type":"string","enum":["africa","uk","germany","australia"]}}},{"type":"object","required":["type","data"],"properties":{"type":{"const":"candidate.consent_revoked"},"data":{"type":"object","additionalProperties":false,"required":["candidateId","externalId","revokedAt"],"properties":{"candidateId":{"type":"string","examples":["cand_01J9Z0"]},"externalId":{"type":"string","examples":["wn-1004"]},"revokedAt":{"type":"string","format":"date-time"},"accessFrozen":{"type":"boolean","examples":[true]}}}}}]},"examples":{"sample":{"value":{"id":"evt_revoked01","type":"candidate.consent_revoked","apiVersion":"v1","region":"africa","occurredAt":"2026-07-15T09:00:00Z","data":{"candidateId":"cand_01J9Z0","externalId":"wn-1004","revokedAt":"2026-07-15T09:00:00Z","accessFrozen":true}}}}}}},"responses":{"2XX":{"description":"Acknowledged. Return any 2xx; non-2xx triggers redelivery."}}}},"candidate.erased":{"post":{"tags":["webhooks"],"summary":"A candidate's data was erased (GDPR / Kenya DPA). No PII in the payload.","description":"GCA POSTs this event to endpoints subscribed to `candidate.erased`. Verify `X-RR-Signature`, dedupe on the event `id`, and return any 2xx to acknowledge.","security":[{"webhookSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","description":"Common envelope on every webhook event.","required":["id","type","apiVersion","occurredAt","region"],"properties":{"id":{"type":"string","examples":["evt_01J9Z0ABCXYZ"]},"type":{"type":"string","description":"The candidate-lifecycle events GCA emits. (assessment/placement events are Phase 2.)","enum":["candidate.received","candidate.verified","candidate.promoted","candidate.validation_failed","candidate.consent_revoked","candidate.erased"]},"apiVersion":{"type":"string","examples":["v1"]},"occurredAt":{"type":"string","format":"date-time"},"region":{"type":"string","enum":["africa","uk","germany","australia"]}}},{"type":"object","required":["type","data"],"properties":{"type":{"const":"candidate.erased"},"data":{"type":"object","additionalProperties":false,"description":"Proof-of-erasure. Deliberately carries NO PII beyond identifiers.","required":["candidateId","externalId","legalBasis","erasedAt","tombstoneId"],"properties":{"candidateId":{"type":"string","examples":["cand_01J9Z0"]},"externalId":{"type":"string","examples":["wn-1004"]},"legalBasis":{"type":"string","enum":["gdpr_art_17","kenya_dpa"],"examples":["kenya_dpa"]},"erasedAt":{"type":"string","format":"date-time"},"tombstoneId":{"type":"string","examples":["tomb_01J9Z0"]}}}}}]},"examples":{"sample":{"value":{"id":"evt_erased01","type":"candidate.erased","apiVersion":"v1","region":"africa","occurredAt":"2026-07-15T09:00:00Z","data":{"candidateId":"cand_01J9Z0","externalId":"wn-1004","legalBasis":"kenya_dpa","erasedAt":"2026-07-15T09:00:00Z","tombstoneId":"tomb_01J9Z0"}}}}}}},"responses":{"2XX":{"description":"Acknowledged. Return any 2xx; non-2xx triggers redelivery."}}}}},"securityDefs":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"},"webhookSignature":{"type":"apiKey","in":"header","name":"X-RR-Signature","description":"HMAC-SHA256 of the raw request body, formatted `sha256=`. Verify before trusting the event."}},"baseUrl":"http://localhost:3000"}