---
title: "Replace a candidate profile"
method: PUT
path: "/candidates/{id}/profile"
tags: ["Candidates"]
---

# Replace a candidate profile

`PUT /candidates/{id}/profile`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/candidates/{id}/profile`
- Auth: HTTP bearer

Replaces the selected profile projection. The write body is a desired-state projection, not the GET response shape: scalars are top-level, and read-only fields are rejected. Absent keys are left unchanged; `null` on a scalar clears it; providing a collection array replaces that collection wholesale (empty array clears). Requires `candidates.manage`. The request is idempotent when an `Idempotency-Key` header is supplied.

## Path parameters

- `id` string, required: The candidate id.

## Request body

- CandidateProfileProjection
  - `headline` string, nullable: Absent key leaves the stored headline unchanged; `null` clears it.
  - `bio` string, nullable: Absent key leaves the stored bio unchanged; `null` clears it.
  - `location` string, nullable: Absent key leaves the stored location unchanged; `null` clears it.
  - `countryCode` string, nullable: Absent key leaves the stored country code unchanged; `null` clears it. Ignored without an error while the candidate has a home place that this request keeps (a changed `location` removes it): the country code is then that place's country.
  - `skills` string[]: Absent key leaves the stored skills unchanged. Providing an array replaces the collection wholesale (empty array clears). Maximum 200 rows.
  - `languages` CandidateProfileLanguageProjection[]: Absent key leaves the stored languages unchanged. Providing an array replaces the collection wholesale (empty array clears). Maximum 50 rows.
    - `name` string, required: Language name.
    - `proficiency` string, required: Proficiency label.
    - `sortOrder` integer, required: Display order, lower first.
  - `experience` CandidateProfileExperienceProjection[]: Absent key leaves the stored experience unchanged. Providing an array replaces the collection wholesale (empty array clears). Maximum 50 rows.
    - `title` string, required: Job title.
    - `companyName` string, required: Employer name.
    - `companyUrl` string, nullable: Employer URL.
    - `location` string, nullable: Role location.
    - `employmentType` string, nullable: Employment type.
    - `locationType` string, nullable: Location type.
    - `foundVia` string, nullable: How the role was found.
    - `startDate` string, required: Start date.
    - `endDate` string, nullable: End date.
    - `description` string, nullable: Role description.
    - `experienceSkills` string[], nullable: Per-role skills; replaced with the row.
    - `sortOrder` integer, required: Display order, lower first.
  - `education` CandidateProfileEducationProjection[]: Absent key leaves the stored education unchanged. Providing an array replaces the collection wholesale (empty array clears). Maximum 50 rows.
    - `institutionName` string, required: Institution name.
    - `institutionUrl` string, nullable: Institution URL.
    - `degree` string, nullable: Degree awarded.
    - `fieldOfStudy` string, nullable: Field of study.
    - `grade` string, nullable: Grade or GPA.
    - `activitiesAndSocieties` string, nullable: Activities and societies.
    - `startDate` string, nullable: Start date.
    - `endDate` string, nullable: End date.
    - `description` string, nullable: Education description.
    - `sortOrder` integer, required: Display order, lower first.

## Response `200`

Successful response.

- CandidateSyncSnapshot
  - `id` string, required: Unique identifier for the candidate.
  - `email` string, required: The candidate's email address.
  - `displayName` string, nullable, required: The candidate's display name.
  - `revision` integer, required: Monotonic Candidate lifecycle revision.
  - `profileRevision` integer, required: Monotonic profile-projection revision.
  - `deactivatedAt` string, date-time, nullable, required: ISO 8601 timestamp when sign-in was disabled, or `null` when active.
  - `profile` object, required
    - `headline` string, nullable, required
    - `bio` string, nullable, required
    - `location` string, nullable, required
    - `countryCode` string, nullable, required
  - `skills` string[], required
  - `languages` CandidateSyncSnapshotLanguage[], required
    - `name` string, required
    - `proficiency` string, required
    - `sortOrder` integer, required
  - `experience` CandidateSyncSnapshotExperience[], required
    - `title` string, required
    - `companyName` string, required
    - `companyUrl` string, nullable, required
    - `location` string, nullable, required
    - `employmentType` string, nullable, required
    - `locationType` string, nullable, required
    - `foundVia` string, nullable, required
    - `startDate` string, required
    - `endDate` string, nullable, required
    - `description` string, nullable, required
    - `experienceSkills` string[], nullable, required
    - `sortOrder` integer, required
  - `education` CandidateSyncSnapshotEducation[], required
    - `institutionName` string, required
    - `institutionUrl` string, nullable, required
    - `degree` string, nullable, required
    - `fieldOfStudy` string, nullable, required
    - `grade` string, nullable, required
    - `activitiesAndSocieties` string, nullable, required
    - `startDate` string, nullable, required
    - `endDate` string, nullable, required
    - `description` string, nullable, required
    - `sortOrder` integer, required

## Other responses

- `400`: The request was malformed.
- `404`: Candidate not found.
- `422`: Candidate has more related records than this endpoint supports.

## Changes

- **2026-10-19** `c34152c38176`: 3 info
  - added the optional property `error/upgrade` to the response with the `400` status
  - added the optional property `error/upgrade` to the response with the `404` status
  - added the optional property `error/upgrade` to the response with the `422` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/candidates/:id/profile/put.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)