{"openapi":"3.1.0","info":{"title":"GCA CMP REST API","version":"1.2.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=<hex>`. Verify before trusting the event."}},"schemas":{}},"paths":{"/v1/candidates":{"post":{"summary":"Receive a candidate from Worknation","tags":["candidates"],"description":"Creates a staged candidate in intake and returns a stagedId. Idempotent on your externalId: retrying with the same externalId returns the original stagedId instead of creating a duplicate. Re-sync data with PUT, not a second POST.","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"]},"headline":{"type":["string","null"],"maxLength":200,"example":"Certified welder · 6 yrs offshore","examples":["Senior plumber · 6 yrs municipal water infrastructure"]},"summary":{"type":["string","null"],"maxLength":5000,"description":"Candidate bio / professional summary.","examples":["HND-qualified plumber with six years on municipal water-infrastructure projects in Accra. Led five-person crews; relocation-ready and open to sponsored roles in the UK and Germany."]},"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"]},"consentGiven":{"type":"boolean","description":"Candidate has consented to data processing. Required true to be accepted.","examples":[true]},"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"]}}},"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"]}}}}},"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"]}}},"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"]}}}},"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"]}},"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"]}}}}}}},"links":{"type":"array","maxItems":20,"default":[],"items":{"type":"object","additionalProperties":false,"description":"An external link on the candidate's profile (LinkedIn, portfolio site, etc.).","required":["type","url"],"properties":{"type":{"type":"string","description":"Kind of an external profile link.","enum":["linkedin","github","portfolio","twitter","website","other"],"examples":["linkedin"]},"url":{"type":"string","format":"uri","maxLength":2048,"example":"https://www.linkedin.com/in/amaka-obi","examples":["https://www.linkedin.com/in/zoe-mensah"]},"label":{"type":["string","null"],"maxLength":120,"example":"LinkedIn","examples":["LinkedIn"]}}}},"media":{"type":"array","maxItems":30,"default":[],"items":{"type":"object","additionalProperties":false,"description":"A profile media item (intro video, profile photo, portfolio piece). **Reference the asset one of two ways — send EXACTLY ONE of `assetKey` (+ `provider`) or `url`, never both.** (Enforced in intake/normalize; draft-07 can't express the constraint in the schema.)","required":["kind"],"properties":{"kind":{"type":"string","description":"Kind of a candidate media asset.","enum":["profile_photo","intro_video","portfolio_image","portfolio_video","audio","other"],"examples":["intro_video"]},"assetKey":{"type":["string","null"],"maxLength":512,"description":"**Either/or with `url` — send exactly one.** Opaque storage key; exchange it with `provider` for a short-lived signed URL (not directly fetchable).","example":"wn:media:vid_88213","examples":["wn:media:vid_1004"]},"provider":{"default":"worknation","description":"Who signs `assetKey`. Only meaningful when `assetKey` is set.","type":"string","enum":["worknation","gca"],"examples":["worknation"]},"url":{"type":["string","null"],"format":"uri","maxLength":2048,"description":"**Either/or with `assetKey` — send exactly one.** A directly-usable link (no key exchange needed).","example":"https://files.example/intro.mp4"},"contentType":{"type":["string","null"],"maxLength":127,"description":"MIME type, e.g. video/mp4 or image/jpeg.","example":"video/mp4","examples":["video/mp4"]},"fileName":{"type":["string","null"],"maxLength":255,"example":"intro.mp4","examples":["zoe-intro.mp4"]},"sizeBytes":{"type":["integer","null"],"minimum":0,"maximum":524288000,"example":4718592,"examples":[4718592]},"durationSeconds":{"type":["number","null"],"minimum":0,"description":"For video/audio assets.","example":68,"examples":[68]},"width":{"type":["integer","null"],"minimum":0,"description":"Pixel width for image/video assets.","example":1280,"examples":[1280]},"height":{"type":["integer","null"],"minimum":0,"description":"Pixel height for image/video assets.","example":720,"examples":[720]},"caption":{"type":["string","null"],"maxLength":500,"example":"60-second introduction","examples":["60-second introduction"]},"uploadedAt":{"type":["string","null"],"format":"date-time","example":"2026-06-02T09:05:00Z","examples":["2026-06-02T09:05:00Z"]}}}},"assessments":{"type":"array","maxItems":50,"default":[],"items":{"type":"object","additionalProperties":false,"description":"A candidate assessment summary carried on the profile. Worknation may push these on intake; GCA may add or override entries from its own assessment domain (domains/assessment stays authoritative for scoring and the work-readiness calculation). Read-model — not the system of record. **A full report is optional; if included, send AT MOST ONE of `reportKey` or `reportUrl`.**","required":["provider","name","status"],"properties":{"externalId":{"type":["string","null"],"maxLength":128,"description":"The provider's own result/exam id.","example":"kry-4f2a9","examples":["kry-88f21"]},"provider":{"default":"worknation","type":"string","description":"Who administered the assessment. Kryterion is GCA's proctoring engine; Worknation may push its own.","enum":["kryterion","worknation","other"],"examples":["kryterion"]},"name":{"type":"string","minLength":1,"maxLength":200,"example":"Welding Work-Readiness","examples":["Plumbing Work-Readiness"]},"status":{"type":"string","enum":["scheduled","in_progress","completed","expired","cancelled"],"examples":["completed"]},"outcome":{"description":"Present once the assessment is completed; omitted otherwise.","type":"string","enum":["pass","fail","inconclusive"],"examples":["pass"]},"score":{"type":["number","null"],"minimum":0,"maximum":100,"example":82,"examples":[84]},"maxScore":{"type":["number","null"],"minimum":0,"example":100,"examples":[100]},"scoreBand":{"type":["string","null"],"maxLength":60,"example":"Proficient","examples":["Proficient"]},"competencies":{"type":"array","maxItems":100,"default":[],"items":{"type":"object","additionalProperties":false,"description":"A per-competency score within an assessment (maps a provider competency code to a GCA skill).","required":["code"],"properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"WELD-201","examples":["PLM-110"]},"label":{"type":["string","null"],"maxLength":200,"example":"Arc Welding Safety","examples":["Pipe Fitting & Joining"]},"score":{"type":["number","null"],"minimum":0,"maximum":100,"examples":[90]}}}},"reportKey":{"type":["string","null"],"maxLength":512,"description":"**Either/or with `reportUrl` — at most one.** Opaque key to the full report; exchange with `provider` for a signed URL.","example":"kry:report:88f21","examples":["kry:report:88f21"]},"reportUrl":{"type":["string","null"],"format":"uri","maxLength":2048,"description":"**Either/or with `reportKey` — at most one.** A directly-usable link to the full report.","example":"https://files.example/report.pdf"},"completedAt":{"type":["string","null"],"format":"date-time","example":"2026-05-18T13:15:00Z","examples":["2026-05-18T13:15:00Z"]},"expiresAt":{"type":["string","null"],"format":"date-time","example":"2028-05-18T13:15:00Z","examples":["2028-05-18T13:15:00Z"]}}}},"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","headline":"Senior plumber · 6 yrs municipal water infrastructure","summary":"HND-qualified plumber with six years on municipal water-infrastructure projects in Accra. Led five-person crews; relocation-ready and open to sponsored roles in the UK and Germany.","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"}]}],"links":[{"type":"linkedin","url":"https://www.linkedin.com/in/zoe-mensah","label":"LinkedIn"},{"type":"portfolio","url":"https://zoe-mensah.example/work","label":"Project portfolio"}],"media":[{"kind":"intro_video","assetKey":"wn:media:vid_1004","provider":"worknation","contentType":"video/mp4","fileName":"zoe-intro.mp4","sizeBytes":4718592,"durationSeconds":68,"width":1280,"height":720,"caption":"60-second introduction","uploadedAt":"2026-06-02T09:05:00Z"},{"kind":"profile_photo","assetKey":"wn:media:img_1004","provider":"worknation","contentType":"image/jpeg","fileName":"zoe-headshot.jpg","sizeBytes":98304,"width":800,"height":800,"caption":"Profile headshot","uploadedAt":"2026-06-02T09:05:00Z"},{"kind":"portfolio_image","url":"https://files.example/zoe-portfolio-1.jpg","contentType":"image/jpeg","fileName":"portfolio-1.jpg","sizeBytes":245760,"width":1600,"height":1200,"caption":"Completed pipework — Accra municipal project","uploadedAt":"2026-05-30T14:00:00Z"}],"assessments":[{"externalId":"kry-88f21","provider":"kryterion","name":"Plumbing Work-Readiness","status":"completed","outcome":"pass","score":84,"maxScore":100,"scoreBand":"Proficient","competencies":[{"code":"PLM-110","label":"Pipe Fitting & Joining","score":90},{"code":"PLM-240","label":"Water Systems Safety","score":78}],"reportKey":"kry:report:88f21","completedAt":"2026-05-18T13:15:00Z","expiresAt":"2028-05-18T13:15:00Z"},{"externalId":"kry-90a12","provider":"kryterion","name":"Health & Safety Induction","status":"completed","outcome":"pass","score":95,"maxScore":100,"scoreBand":"Distinction","competencies":[{"code":"HS-100","label":"Site Safety","score":95}],"reportUrl":"https://files.example/zoe-hs-report.pdf","completedAt":"2026-04-02T10:00:00Z","expiresAt":"2027-04-02T10:00:00Z"}],"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. The record enters intake (not yet promoted). Store the stagedId and use it for follow-up calls (GET/PUT /v1/candidates/{id}); on promotion the record gains a canonical id (cand_...) while the stagedId stays a valid handle. POST is idempotent on (your org, externalId): a retry returns this same stagedId instead of creating a duplicate. You can also look a record up any time with GET /v1/candidates?externalId=.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"The 201 response to POST /v1/candidates. The record enters intake (not yet promoted). Store the stagedId and use it for follow-up calls (GET/PUT /v1/candidates/{id}); on promotion the record gains a canonical id (cand_...) while the stagedId stays a valid handle. POST is idempotent on (your org, externalId): a retry returns this same stagedId instead of creating a duplicate. You can also look a record up any time with GET /v1/candidates?externalId=.","required":["stagedId","externalId","status","receivedAt"],"properties":{"stagedId":{"type":"string","description":"Intake handle for this submission. Stable — resolves to the candidate through promotion.","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 https://api.dev.gca.rolerelay.com/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  \"headline\": \"Senior plumber · 6 yrs municipal water infrastructure\",\n  \"summary\": \"HND-qualified plumber with six years on municipal water-infrastructure projects in Accra. Led five-person crews; relocation-ready and open to sponsored roles in the UK and Germany.\",\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  \"links\": [\n    {\n      \"type\": \"linkedin\",\n      \"url\": \"https://www.linkedin.com/in/zoe-mensah\",\n      \"label\": \"LinkedIn\"\n    },\n    {\n      \"type\": \"portfolio\",\n      \"url\": \"https://zoe-mensah.example/work\",\n      \"label\": \"Project portfolio\"\n    }\n  ],\n  \"media\": [\n    {\n      \"kind\": \"intro_video\",\n      \"assetKey\": \"wn:media:vid_1004\",\n      \"provider\": \"worknation\",\n      \"contentType\": \"video/mp4\",\n      \"fileName\": \"zoe-intro.mp4\",\n      \"sizeBytes\": 4718592,\n      \"durationSeconds\": 68,\n      \"width\": 1280,\n      \"height\": 720,\n      \"caption\": \"60-second introduction\",\n      \"uploadedAt\": \"2026-06-02T09:05:00Z\"\n    },\n    {\n      \"kind\": \"profile_photo\",\n      \"assetKey\": \"wn:media:img_1004\",\n      \"provider\": \"worknation\",\n      \"contentType\": \"image/jpeg\",\n      \"fileName\": \"zoe-headshot.jpg\",\n      \"sizeBytes\": 98304,\n      \"width\": 800,\n      \"height\": 800,\n      \"caption\": \"Profile headshot\",\n      \"uploadedAt\": \"2026-06-02T09:05:00Z\"\n    },\n    {\n      \"kind\": \"portfolio_image\",\n      \"url\": \"https://files.example/zoe-portfolio-1.jpg\",\n      \"contentType\": \"image/jpeg\",\n      \"fileName\": \"portfolio-1.jpg\",\n      \"sizeBytes\": 245760,\n      \"width\": 1600,\n      \"height\": 1200,\n      \"caption\": \"Completed pipework — Accra municipal project\",\n      \"uploadedAt\": \"2026-05-30T14:00:00Z\"\n    }\n  ],\n  \"assessments\": [\n    {\n      \"externalId\": \"kry-88f21\",\n      \"provider\": \"kryterion\",\n      \"name\": \"Plumbing Work-Readiness\",\n      \"status\": \"completed\",\n      \"outcome\": \"pass\",\n      \"score\": 84,\n      \"maxScore\": 100,\n      \"scoreBand\": \"Proficient\",\n      \"competencies\": [\n        {\n          \"code\": \"PLM-110\",\n          \"label\": \"Pipe Fitting & Joining\",\n          \"score\": 90\n        },\n        {\n          \"code\": \"PLM-240\",\n          \"label\": \"Water Systems Safety\",\n          \"score\": 78\n        }\n      ],\n      \"reportKey\": \"kry:report:88f21\",\n      \"completedAt\": \"2026-05-18T13:15:00Z\",\n      \"expiresAt\": \"2028-05-18T13:15:00Z\"\n    },\n    {\n      \"externalId\": \"kry-90a12\",\n      \"provider\": \"kryterion\",\n      \"name\": \"Health & Safety Induction\",\n      \"status\": \"completed\",\n      \"outcome\": \"pass\",\n      \"score\": 95,\n      \"maxScore\": 100,\n      \"scoreBand\": \"Distinction\",\n      \"competencies\": [\n        {\n          \"code\": \"HS-100\",\n          \"label\": \"Site Safety\",\n          \"score\": 95\n        }\n      ],\n      \"reportUrl\": \"https://files.example/zoe-hs-report.pdf\",\n      \"completedAt\": \"2026-04-02T10:00:00Z\",\n      \"expiresAt\": \"2027-04-02T10:00:00Z\"\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(\"https://api.dev.gca.rolerelay.com/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  \"headline\": \"Senior plumber · 6 yrs municipal water infrastructure\",\n  \"summary\": \"HND-qualified plumber with six years on municipal water-infrastructure projects in Accra. Led five-person crews; relocation-ready and open to sponsored roles in the UK and Germany.\",\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  \"links\": [\n    {\n      \"type\": \"linkedin\",\n      \"url\": \"https://www.linkedin.com/in/zoe-mensah\",\n      \"label\": \"LinkedIn\"\n    },\n    {\n      \"type\": \"portfolio\",\n      \"url\": \"https://zoe-mensah.example/work\",\n      \"label\": \"Project portfolio\"\n    }\n  ],\n  \"media\": [\n    {\n      \"kind\": \"intro_video\",\n      \"assetKey\": \"wn:media:vid_1004\",\n      \"provider\": \"worknation\",\n      \"contentType\": \"video/mp4\",\n      \"fileName\": \"zoe-intro.mp4\",\n      \"sizeBytes\": 4718592,\n      \"durationSeconds\": 68,\n      \"width\": 1280,\n      \"height\": 720,\n      \"caption\": \"60-second introduction\",\n      \"uploadedAt\": \"2026-06-02T09:05:00Z\"\n    },\n    {\n      \"kind\": \"profile_photo\",\n      \"assetKey\": \"wn:media:img_1004\",\n      \"provider\": \"worknation\",\n      \"contentType\": \"image/jpeg\",\n      \"fileName\": \"zoe-headshot.jpg\",\n      \"sizeBytes\": 98304,\n      \"width\": 800,\n      \"height\": 800,\n      \"caption\": \"Profile headshot\",\n      \"uploadedAt\": \"2026-06-02T09:05:00Z\"\n    },\n    {\n      \"kind\": \"portfolio_image\",\n      \"url\": \"https://files.example/zoe-portfolio-1.jpg\",\n      \"contentType\": \"image/jpeg\",\n      \"fileName\": \"portfolio-1.jpg\",\n      \"sizeBytes\": 245760,\n      \"width\": 1600,\n      \"height\": 1200,\n      \"caption\": \"Completed pipework — Accra municipal project\",\n      \"uploadedAt\": \"2026-05-30T14:00:00Z\"\n    }\n  ],\n  \"assessments\": [\n    {\n      \"externalId\": \"kry-88f21\",\n      \"provider\": \"kryterion\",\n      \"name\": \"Plumbing Work-Readiness\",\n      \"status\": \"completed\",\n      \"outcome\": \"pass\",\n      \"score\": 84,\n      \"maxScore\": 100,\n      \"scoreBand\": \"Proficient\",\n      \"competencies\": [\n        {\n          \"code\": \"PLM-110\",\n          \"label\": \"Pipe Fitting & Joining\",\n          \"score\": 90\n        },\n        {\n          \"code\": \"PLM-240\",\n          \"label\": \"Water Systems Safety\",\n          \"score\": 78\n        }\n      ],\n      \"reportKey\": \"kry:report:88f21\",\n      \"completedAt\": \"2026-05-18T13:15:00Z\",\n      \"expiresAt\": \"2028-05-18T13:15:00Z\"\n    },\n    {\n      \"externalId\": \"kry-90a12\",\n      \"provider\": \"kryterion\",\n      \"name\": \"Health & Safety Induction\",\n      \"status\": \"completed\",\n      \"outcome\": \"pass\",\n      \"score\": 95,\n      \"maxScore\": 100,\n      \"scoreBand\": \"Distinction\",\n      \"competencies\": [\n        {\n          \"code\": \"HS-100\",\n          \"label\": \"Site Safety\",\n          \"score\": 95\n        }\n      ],\n      \"reportUrl\": \"https://files.example/zoe-hs-report.pdf\",\n      \"completedAt\": \"2026-04-02T10:00:00Z\",\n      \"expiresAt\": \"2027-04-02T10:00:00Z\"\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  \"headline\": \"Senior plumber · 6 yrs municipal water infrastructure\",\n  \"summary\": \"HND-qualified plumber with six years on municipal water-infrastructure projects in Accra. Led five-person crews; relocation-ready and open to sponsored roles in the UK and Germany.\",\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  \"links\": [\n    {\n      \"type\": \"linkedin\",\n      \"url\": \"https://www.linkedin.com/in/zoe-mensah\",\n      \"label\": \"LinkedIn\"\n    },\n    {\n      \"type\": \"portfolio\",\n      \"url\": \"https://zoe-mensah.example/work\",\n      \"label\": \"Project portfolio\"\n    }\n  ],\n  \"media\": [\n    {\n      \"kind\": \"intro_video\",\n      \"assetKey\": \"wn:media:vid_1004\",\n      \"provider\": \"worknation\",\n      \"contentType\": \"video/mp4\",\n      \"fileName\": \"zoe-intro.mp4\",\n      \"sizeBytes\": 4718592,\n      \"durationSeconds\": 68,\n      \"width\": 1280,\n      \"height\": 720,\n      \"caption\": \"60-second introduction\",\n      \"uploadedAt\": \"2026-06-02T09:05:00Z\"\n    },\n    {\n      \"kind\": \"profile_photo\",\n      \"assetKey\": \"wn:media:img_1004\",\n      \"provider\": \"worknation\",\n      \"contentType\": \"image/jpeg\",\n      \"fileName\": \"zoe-headshot.jpg\",\n      \"sizeBytes\": 98304,\n      \"width\": 800,\n      \"height\": 800,\n      \"caption\": \"Profile headshot\",\n      \"uploadedAt\": \"2026-06-02T09:05:00Z\"\n    },\n    {\n      \"kind\": \"portfolio_image\",\n      \"url\": \"https://files.example/zoe-portfolio-1.jpg\",\n      \"contentType\": \"image/jpeg\",\n      \"fileName\": \"portfolio-1.jpg\",\n      \"sizeBytes\": 245760,\n      \"width\": 1600,\n      \"height\": 1200,\n      \"caption\": \"Completed pipework — Accra municipal project\",\n      \"uploadedAt\": \"2026-05-30T14:00:00Z\"\n    }\n  ],\n  \"assessments\": [\n    {\n      \"externalId\": \"kry-88f21\",\n      \"provider\": \"kryterion\",\n      \"name\": \"Plumbing Work-Readiness\",\n      \"status\": \"completed\",\n      \"outcome\": \"pass\",\n      \"score\": 84,\n      \"maxScore\": 100,\n      \"scoreBand\": \"Proficient\",\n      \"competencies\": [\n        {\n          \"code\": \"PLM-110\",\n          \"label\": \"Pipe Fitting & Joining\",\n          \"score\": 90\n        },\n        {\n          \"code\": \"PLM-240\",\n          \"label\": \"Water Systems Safety\",\n          \"score\": 78\n        }\n      ],\n      \"reportKey\": \"kry:report:88f21\",\n      \"completedAt\": \"2026-05-18T13:15:00Z\",\n      \"expiresAt\": \"2028-05-18T13:15:00Z\"\n    },\n    {\n      \"externalId\": \"kry-90a12\",\n      \"provider\": \"kryterion\",\n      \"name\": \"Health & Safety Induction\",\n      \"status\": \"completed\",\n      \"outcome\": \"pass\",\n      \"score\": 95,\n      \"maxScore\": 100,\n      \"scoreBand\": \"Distinction\",\n      \"competencies\": [\n        {\n          \"code\": \"HS-100\",\n          \"label\": \"Site Safety\",\n          \"score\": 95\n        }\n      ],\n      \"reportUrl\": \"https://files.example/zoe-hs-report.pdf\",\n      \"completedAt\": \"2026-04-02T10:00:00Z\",\n      \"expiresAt\": \"2027-04-02T10:00:00Z\"\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    \"https://api.dev.gca.rolerelay.com/v1/candidates\",\n    headers={\"X-API-Key\": \"YOUR_API_KEY\"},\n    json=payload,\n)\ndata = res.json()"}]},"get":{"summary":"Find a candidate by your externalId","tags":["candidates"],"description":"Resolve the candidate you created (within your org) from the externalId you supplied on POST — useful for idempotent retries or if you no longer have our id.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"externalId","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"},"headline":{"type":["null","string"]},"summary":{"type":["null","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"},"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"},"jobPreferences":{"type":"object","additionalProperties":false,"properties":{"desiredTitles":{"type":"array","maxItems":20,"default":[],"items":{"type":"string","maxLength":200}},"employmentTypes":{"type":"array","maxItems":8,"default":[],"items":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"]}},"preferredCountries":{"type":"array","maxItems":30,"default":[],"items":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"}},"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"}}}}},"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}}}},"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","string"],"format":"date","description":"Null means current role."},"isCurrent":{"type":"boolean","default":false},"location":{"type":["null","string"],"maxLength":200},"description":{"type":["null","string"],"maxLength":4000}}}},"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","string"],"format":"date"},"endDate":{"type":["null","string"],"format":"date"},"grade":{"type":["null","string"],"maxLength":60}}}},"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"]}}}},"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","string"],"format":"date"}}}},"tags":{"type":"array","items":{"type":"string","maxLength":60}},"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":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."},"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}}}}}}},"links":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"An external link on the candidate's profile (LinkedIn, portfolio site, etc.).","required":["type","url"],"properties":{"type":{"type":"string","description":"Kind of an external profile link.","enum":["linkedin","github","portfolio","twitter","website","other"]},"url":{"type":"string","format":"uri","maxLength":2048,"example":"https://www.linkedin.com/in/amaka-obi"},"label":{"type":["null","string"],"maxLength":120,"example":"LinkedIn"}}}},"media":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"A profile media item (intro video, profile photo, portfolio piece). **Reference the asset one of two ways — send EXACTLY ONE of `assetKey` (+ `provider`) or `url`, never both.** (Enforced in intake/normalize; draft-07 can't express the constraint in the schema.)","required":["kind"],"properties":{"kind":{"type":"string","description":"Kind of a candidate media asset.","enum":["profile_photo","intro_video","portfolio_image","portfolio_video","audio","other"]},"assetKey":{"type":["null","string"],"maxLength":512,"description":"**Either/or with `url` — send exactly one.** Opaque storage key; exchange it with `provider` for a short-lived signed URL (not directly fetchable).","example":"wn:media:vid_88213"},"provider":{"default":"worknation","description":"Who signs `assetKey`. Only meaningful when `assetKey` is set.","type":"string","enum":["worknation","gca"]},"url":{"type":["null","string"],"format":"uri","maxLength":2048,"description":"**Either/or with `assetKey` — send exactly one.** A directly-usable link (no key exchange needed).","example":"https://files.example/intro.mp4"},"contentType":{"type":["null","string"],"maxLength":127,"description":"MIME type, e.g. video/mp4 or image/jpeg.","example":"video/mp4"},"fileName":{"type":["null","string"],"maxLength":255,"example":"intro.mp4"},"sizeBytes":{"type":["null","integer"],"minimum":0,"maximum":524288000,"example":4718592},"durationSeconds":{"type":["null","number"],"minimum":0,"description":"For video/audio assets.","example":68},"width":{"type":["null","integer"],"minimum":0,"description":"Pixel width for image/video assets.","example":1280},"height":{"type":["null","integer"],"minimum":0,"description":"Pixel height for image/video assets.","example":720},"caption":{"type":["null","string"],"maxLength":500,"example":"60-second introduction"},"uploadedAt":{"type":["null","string"],"format":"date-time","example":"2026-06-02T09:05:00Z"}}}},"assessments":{"type":"array","description":"Assessment summaries; Worknation-supplied and/or GCA-enriched.","items":{"type":"object","additionalProperties":false,"description":"A candidate assessment summary carried on the profile. Worknation may push these on intake; GCA may add or override entries from its own assessment domain (domains/assessment stays authoritative for scoring and the work-readiness calculation). Read-model — not the system of record. **A full report is optional; if included, send AT MOST ONE of `reportKey` or `reportUrl`.**","required":["provider","name","status"],"properties":{"externalId":{"type":["null","string"],"maxLength":128,"description":"The provider's own result/exam id.","example":"kry-4f2a9"},"provider":{"default":"worknation","type":"string","description":"Who administered the assessment. Kryterion is GCA's proctoring engine; Worknation may push its own.","enum":["kryterion","worknation","other"]},"name":{"type":"string","minLength":1,"maxLength":200,"example":"Welding Work-Readiness"},"status":{"type":"string","enum":["scheduled","in_progress","completed","expired","cancelled"]},"outcome":{"description":"Present once the assessment is completed; omitted otherwise.","type":"string","enum":["pass","fail","inconclusive"]},"score":{"type":["null","number"],"minimum":0,"maximum":100,"example":82},"maxScore":{"type":["null","number"],"minimum":0,"example":100},"scoreBand":{"type":["null","string"],"maxLength":60,"example":"Proficient"},"competencies":{"type":"array","maxItems":100,"default":[],"items":{"type":"object","additionalProperties":false,"description":"A per-competency score within an assessment (maps a provider competency code to a GCA skill).","required":["code"],"properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"WELD-201"},"label":{"type":["null","string"],"maxLength":200,"example":"Arc Welding Safety"},"score":{"type":["null","number"],"minimum":0,"maximum":100}}}},"reportKey":{"type":["null","string"],"maxLength":512,"description":"**Either/or with `reportUrl` — at most one.** Opaque key to the full report; exchange with `provider` for a signed URL.","example":"kry:report:88f21"},"reportUrl":{"type":["null","string"],"format":"uri","maxLength":2048,"description":"**Either/or with `reportKey` — at most one.** A directly-usable link to the full report.","example":"https://files.example/report.pdf"},"completedAt":{"type":["null","string"],"format":"date-time","example":"2026-05-18T13:15:00Z"},"expiresAt":{"type":["null","string"],"format":"date-time","example":"2028-05-18T13:15:00Z"}}}}}}}}},"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"}}}}}},"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/candidates/{id}":{"get":{"summary":"Fetch a candidate record","tags":["candidates"],"description":"Accepts either the stagedId from POST or the canonical candidate id — both resolve to the same record through promotion.","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"]},"headline":{"type":["null","string"],"examples":["Senior plumber · 6 yrs municipal water infrastructure"]},"summary":{"type":["null","string"],"examples":["HND-qualified plumber with six years on municipal water-infrastructure projects in Accra. Led five-person crews; relocation-ready and open to sponsored roles in the UK and Germany."]},"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"]},"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"]},"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"]}}}}},"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"]}}}},"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"]}}}}}}},"links":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"An external link on the candidate's profile (LinkedIn, portfolio site, etc.).","required":["type","url"],"properties":{"type":{"type":"string","description":"Kind of an external profile link.","enum":["linkedin","github","portfolio","twitter","website","other"],"examples":["linkedin"]},"url":{"type":"string","format":"uri","maxLength":2048,"example":"https://www.linkedin.com/in/amaka-obi","examples":["https://www.linkedin.com/in/zoe-mensah"]},"label":{"type":["null","string"],"maxLength":120,"example":"LinkedIn","examples":["LinkedIn"]}}}},"media":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"A profile media item (intro video, profile photo, portfolio piece). **Reference the asset one of two ways — send EXACTLY ONE of `assetKey` (+ `provider`) or `url`, never both.** (Enforced in intake/normalize; draft-07 can't express the constraint in the schema.)","required":["kind"],"properties":{"kind":{"type":"string","description":"Kind of a candidate media asset.","enum":["profile_photo","intro_video","portfolio_image","portfolio_video","audio","other"],"examples":["intro_video"]},"assetKey":{"type":["null","string"],"maxLength":512,"description":"**Either/or with `url` — send exactly one.** Opaque storage key; exchange it with `provider` for a short-lived signed URL (not directly fetchable).","example":"wn:media:vid_88213","examples":["wn:media:vid_1004"]},"provider":{"default":"worknation","description":"Who signs `assetKey`. Only meaningful when `assetKey` is set.","type":"string","enum":["worknation","gca"],"examples":["worknation"]},"url":{"type":["null","string"],"format":"uri","maxLength":2048,"description":"**Either/or with `assetKey` — send exactly one.** A directly-usable link (no key exchange needed).","example":"https://files.example/intro.mp4"},"contentType":{"type":["null","string"],"maxLength":127,"description":"MIME type, e.g. video/mp4 or image/jpeg.","example":"video/mp4","examples":["video/mp4"]},"fileName":{"type":["null","string"],"maxLength":255,"example":"intro.mp4","examples":["zoe-intro.mp4"]},"sizeBytes":{"type":["null","integer"],"minimum":0,"maximum":524288000,"example":4718592,"examples":[4718592]},"durationSeconds":{"type":["null","number"],"minimum":0,"description":"For video/audio assets.","example":68,"examples":[68]},"width":{"type":["null","integer"],"minimum":0,"description":"Pixel width for image/video assets.","example":1280,"examples":[1280]},"height":{"type":["null","integer"],"minimum":0,"description":"Pixel height for image/video assets.","example":720,"examples":[720]},"caption":{"type":["null","string"],"maxLength":500,"example":"60-second introduction","examples":["60-second introduction"]},"uploadedAt":{"type":["null","string"],"format":"date-time","example":"2026-06-02T09:05:00Z","examples":["2026-06-02T09:05:00Z"]}}}},"assessments":{"type":"array","description":"Assessment summaries; Worknation-supplied and/or GCA-enriched.","items":{"type":"object","additionalProperties":false,"description":"A candidate assessment summary carried on the profile. Worknation may push these on intake; GCA may add or override entries from its own assessment domain (domains/assessment stays authoritative for scoring and the work-readiness calculation). Read-model — not the system of record. **A full report is optional; if included, send AT MOST ONE of `reportKey` or `reportUrl`.**","required":["provider","name","status"],"properties":{"externalId":{"type":["null","string"],"maxLength":128,"description":"The provider's own result/exam id.","example":"kry-4f2a9","examples":["kry-88f21"]},"provider":{"default":"worknation","type":"string","description":"Who administered the assessment. Kryterion is GCA's proctoring engine; Worknation may push its own.","enum":["kryterion","worknation","other"],"examples":["kryterion"]},"name":{"type":"string","minLength":1,"maxLength":200,"example":"Welding Work-Readiness","examples":["Plumbing Work-Readiness"]},"status":{"type":"string","enum":["scheduled","in_progress","completed","expired","cancelled"],"examples":["completed"]},"outcome":{"description":"Present once the assessment is completed; omitted otherwise.","type":"string","enum":["pass","fail","inconclusive"],"examples":["pass"]},"score":{"type":["null","number"],"minimum":0,"maximum":100,"example":82,"examples":[84]},"maxScore":{"type":["null","number"],"minimum":0,"example":100,"examples":[100]},"scoreBand":{"type":["null","string"],"maxLength":60,"example":"Proficient","examples":["Proficient"]},"competencies":{"type":"array","maxItems":100,"default":[],"items":{"type":"object","additionalProperties":false,"description":"A per-competency score within an assessment (maps a provider competency code to a GCA skill).","required":["code"],"properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"WELD-201","examples":["PLM-110"]},"label":{"type":["null","string"],"maxLength":200,"example":"Arc Welding Safety","examples":["Pipe Fitting & Joining"]},"score":{"type":["null","number"],"minimum":0,"maximum":100,"examples":[90]}}}},"reportKey":{"type":["null","string"],"maxLength":512,"description":"**Either/or with `reportUrl` — at most one.** Opaque key to the full report; exchange with `provider` for a signed URL.","example":"kry:report:88f21","examples":["kry:report:88f21"]},"reportUrl":{"type":["null","string"],"format":"uri","maxLength":2048,"description":"**Either/or with `reportKey` — at most one.** A directly-usable link to the full report.","example":"https://files.example/report.pdf"},"completedAt":{"type":["null","string"],"format":"date-time","example":"2026-05-18T13:15:00Z","examples":["2026-05-18T13:15:00Z"]},"expiresAt":{"type":["null","string"],"format":"date-time","example":"2028-05-18T13:15:00Z","examples":["2028-05-18T13:15: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","headline":"Senior plumber · 6 yrs municipal water infrastructure","summary":"HND-qualified plumber with six years on municipal water-infrastructure projects in Accra. Led five-person crews; relocation-ready and open to sponsored roles in the UK and Germany.","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"}]}],"links":[{"type":"linkedin","url":"https://www.linkedin.com/in/zoe-mensah","label":"LinkedIn"},{"type":"portfolio","url":"https://zoe-mensah.example/work","label":"Project portfolio"}],"media":[{"kind":"intro_video","assetKey":"wn:media:vid_1004","provider":"worknation","contentType":"video/mp4","fileName":"zoe-intro.mp4","sizeBytes":4718592,"durationSeconds":68,"width":1280,"height":720,"caption":"60-second introduction","uploadedAt":"2026-06-02T09:05:00Z"},{"kind":"profile_photo","assetKey":"wn:media:img_1004","provider":"worknation","contentType":"image/jpeg","fileName":"zoe-headshot.jpg","sizeBytes":98304,"width":800,"height":800,"caption":"Profile headshot","uploadedAt":"2026-06-02T09:05:00Z"},{"kind":"portfolio_image","url":"https://files.example/zoe-portfolio-1.jpg","contentType":"image/jpeg","fileName":"portfolio-1.jpg","sizeBytes":245760,"width":1600,"height":1200,"caption":"Completed pipework — Accra municipal project","uploadedAt":"2026-05-30T14:00:00Z"}],"assessments":[{"externalId":"kry-88f21","provider":"kryterion","name":"Plumbing Work-Readiness","status":"completed","outcome":"pass","score":84,"maxScore":100,"scoreBand":"Proficient","competencies":[{"code":"PLM-110","label":"Pipe Fitting & Joining","score":90},{"code":"PLM-240","label":"Water Systems Safety","score":78}],"reportKey":"kry:report:88f21","completedAt":"2026-05-18T13:15:00Z","expiresAt":"2028-05-18T13:15:00Z"},{"externalId":"kry-90a12","provider":"kryterion","name":"Health & Safety Induction","status":"completed","outcome":"pass","score":95,"maxScore":100,"scoreBand":"Distinction","competencies":[{"code":"HS-100","label":"Site Safety","score":95}],"reportUrl":"https://files.example/zoe-hs-report.pdf","completedAt":"2026-04-02T10:00:00Z","expiresAt":"2027-04-02T10:00:00Z"}],"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},"headline":{"type":["string","null"],"maxLength":200},"summary":{"type":["string","null"],"maxLength":5000},"phone":{"type":"string","maxLength":32},"consentGiven":{"type":"boolean"},"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"}}},"jobPreferences":{"type":"object","additionalProperties":false,"properties":{"desiredTitles":{"type":"array","maxItems":20,"default":[],"items":{"type":"string","maxLength":200}},"employmentTypes":{"type":"array","maxItems":8,"default":[],"items":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"]}},"preferredCountries":{"type":"array","maxItems":30,"default":[],"items":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"}},"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"}}}}},"skills":{"type":"array","maxItems":100,"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}}}},"workHistory":{"type":"array","maxItems":40,"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","null"],"format":"date","description":"Null means current role."},"isCurrent":{"type":"boolean","default":false},"location":{"type":["string","null"],"maxLength":200},"description":{"type":["string","null"],"maxLength":4000}}}},"education":{"type":"array","maxItems":40,"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","null"],"format":"date"},"endDate":{"type":["string","null"],"format":"date"},"grade":{"type":["string","null"],"maxLength":60}}}},"languages":{"type":"array","maxItems":30,"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"]}}}},"workEligibility":{"type":"array","maxItems":30,"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","null"],"format":"date"}}}},"documents":{"type":"array","maxItems":50,"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":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."},"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}}}}}}},"links":{"type":"array","maxItems":20,"items":{"type":"object","additionalProperties":false,"description":"An external link on the candidate's profile (LinkedIn, portfolio site, etc.).","required":["type","url"],"properties":{"type":{"type":"string","description":"Kind of an external profile link.","enum":["linkedin","github","portfolio","twitter","website","other"]},"url":{"type":"string","format":"uri","maxLength":2048,"example":"https://www.linkedin.com/in/amaka-obi"},"label":{"type":["string","null"],"maxLength":120,"example":"LinkedIn"}}}},"media":{"type":"array","maxItems":30,"items":{"type":"object","additionalProperties":false,"description":"A profile media item (intro video, profile photo, portfolio piece). **Reference the asset one of two ways — send EXACTLY ONE of `assetKey` (+ `provider`) or `url`, never both.** (Enforced in intake/normalize; draft-07 can't express the constraint in the schema.)","required":["kind"],"properties":{"kind":{"type":"string","description":"Kind of a candidate media asset.","enum":["profile_photo","intro_video","portfolio_image","portfolio_video","audio","other"]},"assetKey":{"type":["string","null"],"maxLength":512,"description":"**Either/or with `url` — send exactly one.** Opaque storage key; exchange it with `provider` for a short-lived signed URL (not directly fetchable).","example":"wn:media:vid_88213"},"provider":{"default":"worknation","description":"Who signs `assetKey`. Only meaningful when `assetKey` is set.","type":"string","enum":["worknation","gca"]},"url":{"type":["string","null"],"format":"uri","maxLength":2048,"description":"**Either/or with `assetKey` — send exactly one.** A directly-usable link (no key exchange needed).","example":"https://files.example/intro.mp4"},"contentType":{"type":["string","null"],"maxLength":127,"description":"MIME type, e.g. video/mp4 or image/jpeg.","example":"video/mp4"},"fileName":{"type":["string","null"],"maxLength":255,"example":"intro.mp4"},"sizeBytes":{"type":["integer","null"],"minimum":0,"maximum":524288000,"example":4718592},"durationSeconds":{"type":["number","null"],"minimum":0,"description":"For video/audio assets.","example":68},"width":{"type":["integer","null"],"minimum":0,"description":"Pixel width for image/video assets.","example":1280},"height":{"type":["integer","null"],"minimum":0,"description":"Pixel height for image/video assets.","example":720},"caption":{"type":["string","null"],"maxLength":500,"example":"60-second introduction"},"uploadedAt":{"type":["string","null"],"format":"date-time","example":"2026-06-02T09:05:00Z"}}}},"assessments":{"type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"description":"A candidate assessment summary carried on the profile. Worknation may push these on intake; GCA may add or override entries from its own assessment domain (domains/assessment stays authoritative for scoring and the work-readiness calculation). Read-model — not the system of record. **A full report is optional; if included, send AT MOST ONE of `reportKey` or `reportUrl`.**","required":["provider","name","status"],"properties":{"externalId":{"type":["string","null"],"maxLength":128,"description":"The provider's own result/exam id.","example":"kry-4f2a9"},"provider":{"default":"worknation","type":"string","description":"Who administered the assessment. Kryterion is GCA's proctoring engine; Worknation may push its own.","enum":["kryterion","worknation","other"]},"name":{"type":"string","minLength":1,"maxLength":200,"example":"Welding Work-Readiness"},"status":{"type":"string","enum":["scheduled","in_progress","completed","expired","cancelled"]},"outcome":{"description":"Present once the assessment is completed; omitted otherwise.","type":"string","enum":["pass","fail","inconclusive"]},"score":{"type":["number","null"],"minimum":0,"maximum":100,"example":82},"maxScore":{"type":["number","null"],"minimum":0,"example":100},"scoreBand":{"type":["string","null"],"maxLength":60,"example":"Proficient"},"competencies":{"type":"array","maxItems":100,"default":[],"items":{"type":"object","additionalProperties":false,"description":"A per-competency score within an assessment (maps a provider competency code to a GCA skill).","required":["code"],"properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"WELD-201"},"label":{"type":["string","null"],"maxLength":200,"example":"Arc Welding Safety"},"score":{"type":["number","null"],"minimum":0,"maximum":100}}}},"reportKey":{"type":["string","null"],"maxLength":512,"description":"**Either/or with `reportUrl` — at most one.** Opaque key to the full report; exchange with `provider` for a signed URL.","example":"kry:report:88f21"},"reportUrl":{"type":["string","null"],"format":"uri","maxLength":2048,"description":"**Either/or with `reportKey` — at most one.** A directly-usable link to the full report.","example":"https://files.example/report.pdf"},"completedAt":{"type":["string","null"],"format":"date-time","example":"2026-05-18T13:15:00Z"},"expiresAt":{"type":["string","null"],"format":"date-time","example":"2028-05-18T13:15:00Z"}}}},"consents":{"type":"array","maxItems":20,"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","null"],"format":"date-time"},"policyVersion":{"type":["string","null"],"maxLength":40}}}}}}}},"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"},"headline":{"type":["null","string"]},"summary":{"type":["null","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"},"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"},"jobPreferences":{"type":"object","additionalProperties":false,"properties":{"desiredTitles":{"type":"array","maxItems":20,"default":[],"items":{"type":"string","maxLength":200}},"employmentTypes":{"type":"array","maxItems":8,"default":[],"items":{"type":"string","enum":["full_time","part_time","contract","temporary","internship","apprenticeship","casual","volunteer"]}},"preferredCountries":{"type":"array","maxItems":30,"default":[],"items":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code, uppercase.","example":"NG"}},"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"}}}}},"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}}}},"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","string"],"format":"date","description":"Null means current role."},"isCurrent":{"type":"boolean","default":false},"location":{"type":["null","string"],"maxLength":200},"description":{"type":["null","string"],"maxLength":4000}}}},"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","string"],"format":"date"},"endDate":{"type":["null","string"],"format":"date"},"grade":{"type":["null","string"],"maxLength":60}}}},"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"]}}}},"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","string"],"format":"date"}}}},"tags":{"type":"array","items":{"type":"string","maxLength":60}},"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":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."},"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}}}}}}},"links":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"An external link on the candidate's profile (LinkedIn, portfolio site, etc.).","required":["type","url"],"properties":{"type":{"type":"string","description":"Kind of an external profile link.","enum":["linkedin","github","portfolio","twitter","website","other"]},"url":{"type":"string","format":"uri","maxLength":2048,"example":"https://www.linkedin.com/in/amaka-obi"},"label":{"type":["null","string"],"maxLength":120,"example":"LinkedIn"}}}},"media":{"type":"array","items":{"type":"object","additionalProperties":false,"description":"A profile media item (intro video, profile photo, portfolio piece). **Reference the asset one of two ways — send EXACTLY ONE of `assetKey` (+ `provider`) or `url`, never both.** (Enforced in intake/normalize; draft-07 can't express the constraint in the schema.)","required":["kind"],"properties":{"kind":{"type":"string","description":"Kind of a candidate media asset.","enum":["profile_photo","intro_video","portfolio_image","portfolio_video","audio","other"]},"assetKey":{"type":["null","string"],"maxLength":512,"description":"**Either/or with `url` — send exactly one.** Opaque storage key; exchange it with `provider` for a short-lived signed URL (not directly fetchable).","example":"wn:media:vid_88213"},"provider":{"default":"worknation","description":"Who signs `assetKey`. Only meaningful when `assetKey` is set.","type":"string","enum":["worknation","gca"]},"url":{"type":["null","string"],"format":"uri","maxLength":2048,"description":"**Either/or with `assetKey` — send exactly one.** A directly-usable link (no key exchange needed).","example":"https://files.example/intro.mp4"},"contentType":{"type":["null","string"],"maxLength":127,"description":"MIME type, e.g. video/mp4 or image/jpeg.","example":"video/mp4"},"fileName":{"type":["null","string"],"maxLength":255,"example":"intro.mp4"},"sizeBytes":{"type":["null","integer"],"minimum":0,"maximum":524288000,"example":4718592},"durationSeconds":{"type":["null","number"],"minimum":0,"description":"For video/audio assets.","example":68},"width":{"type":["null","integer"],"minimum":0,"description":"Pixel width for image/video assets.","example":1280},"height":{"type":["null","integer"],"minimum":0,"description":"Pixel height for image/video assets.","example":720},"caption":{"type":["null","string"],"maxLength":500,"example":"60-second introduction"},"uploadedAt":{"type":["null","string"],"format":"date-time","example":"2026-06-02T09:05:00Z"}}}},"assessments":{"type":"array","description":"Assessment summaries; Worknation-supplied and/or GCA-enriched.","items":{"type":"object","additionalProperties":false,"description":"A candidate assessment summary carried on the profile. Worknation may push these on intake; GCA may add or override entries from its own assessment domain (domains/assessment stays authoritative for scoring and the work-readiness calculation). Read-model — not the system of record. **A full report is optional; if included, send AT MOST ONE of `reportKey` or `reportUrl`.**","required":["provider","name","status"],"properties":{"externalId":{"type":["null","string"],"maxLength":128,"description":"The provider's own result/exam id.","example":"kry-4f2a9"},"provider":{"default":"worknation","type":"string","description":"Who administered the assessment. Kryterion is GCA's proctoring engine; Worknation may push its own.","enum":["kryterion","worknation","other"]},"name":{"type":"string","minLength":1,"maxLength":200,"example":"Welding Work-Readiness"},"status":{"type":"string","enum":["scheduled","in_progress","completed","expired","cancelled"]},"outcome":{"description":"Present once the assessment is completed; omitted otherwise.","type":"string","enum":["pass","fail","inconclusive"]},"score":{"type":["null","number"],"minimum":0,"maximum":100,"example":82},"maxScore":{"type":["null","number"],"minimum":0,"example":100},"scoreBand":{"type":["null","string"],"maxLength":60,"example":"Proficient"},"competencies":{"type":"array","maxItems":100,"default":[],"items":{"type":"object","additionalProperties":false,"description":"A per-competency score within an assessment (maps a provider competency code to a GCA skill).","required":["code"],"properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"WELD-201"},"label":{"type":["null","string"],"maxLength":200,"example":"Arc Welding Safety"},"score":{"type":["null","number"],"minimum":0,"maximum":100}}}},"reportKey":{"type":["null","string"],"maxLength":512,"description":"**Either/or with `reportUrl` — at most one.** Opaque key to the full report; exchange with `provider` for a signed URL.","example":"kry:report:88f21"},"reportUrl":{"type":["null","string"],"format":"uri","maxLength":2048,"description":"**Either/or with `reportKey` — at most one.** A directly-usable link to the full report.","example":"https://files.example/report.pdf"},"completedAt":{"type":["null","string"],"format":"date-time","example":"2026-05-18T13:15:00Z"},"expiresAt":{"type":["null","string"],"format":"date-time","example":"2028-05-18T13:15: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"}}}}}}}}},"/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":20,"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"]}},"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"}}}}}}}},"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"]}},"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"}}}}}}}}},"/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"]}},"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":"dev deployment"}],"security":[{"apiKey":[]}],"tags":[{"name":"candidates","description":"Candidate intake and records.\n\n**Identifiers —** `POST` returns a `stagedId`; store it and use it for every follow-up call. On promotion the record gains a durable canonical `id`, but the `stagedId` keeps resolving, so either works on `GET`/`PUT`.\n\n**Idempotency —** send your own `externalId` on create. A retry with the same `externalId` returns the original `stagedId` (no duplicate, no re-fired event). Recover our record any time with `GET /v1/candidates?externalId=`. Re-sync data with `PUT`, not a second `POST`."},{"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."}}}}}}