---
title: "Update Badge"
method: PUT
path: "/v1/badge/{badge_id}"
tags: ["Badge"]
---

# Update Badge

`PUT /v1/badge/{badge_id}`

## Request

- Base URL: `https://api.navigatr.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.navigatr.app/v1/badge/{badge_id}`
- Auth: OAuth 2
  - Password
  - Token URL: `/v1/token`

Update a badge. Partial updates are supported by only sending the keys with values that changed.
A badge approver who cannot otherwise edit the badge may set `qa_locked` to true on its own,
to re-lock it.
`source`, `issuer_id`, `external_id`, `external_url`, `provider_ids` and `community_ids` are
platform admin only: anyone else gets 403 when the value differs from the saved one, and a value
sent unchanged is accepted and ignored, so a full-object PUT still works.
`design_parameters` replaces the saved object whole, except its `qa` (the QA mark): only a
platform admin may change it (403 otherwise). Omitting `qa` (or sending null, or a null
`design_parameters`) keeps the saved mark, and sending the saved value is accepted from anyone.

available_to_all (bool) : Defaults to True.

    availability (str): Optional field. If not None, available_to_all is automatically set to False.
    type (Badge_Type): See below for available types.
    source (Source_Type): Defaults to Internal
    cost (Badge_Cost): Defaults to Free
    level (Badge_Level): Defaults to Foundational
    time_to_earn (Time_To_Earn): Defaults to Hours
    participation_type (Participation_Type): Defaults to In_Person
    qualification_code (str): Max 100 characters.
    credits_available (float): >= 0, stored rounded to two decimal places.
    credits_unit (str): Max 20 characters; null means "credits".
    qualification_type (Qualification_Type): Only accepted when the badge type is Qualification (422 otherwise).
        When the type changes away from Qualification it is cleared if not sent or sent as
        null, and the request returns 422 if a non-null value is sent.
    qualification_framework (Qualification_Framework): RQF, CQFW, SCQF, EQF or QFEmirates.
    qualification_level (str): Checked against the framework after the body is applied, so a
        framework-only change the stored level is not valid for is a 422, as is a null
        framework while a level remains. Changing or clearing it replaces or removes the
        badge's system-managed alignment; alignments of that framework in the body are ignored.
    grade (Badge_Grade): Pass, Merit, Distinction or Distinction*. Setting or changing it
        shows the new grade on every issued badge of this badge, including ones already
        issued, without emailing their recipients; clearing it shows the grade each was
        issued with again.
    field_of_study_id (int): An active tier 2 Ofqual Sector Subject Area id (a tier 1,
        inactive or unknown id is a 422); null clears it. Left alone when not sent, so a badge
        keeps an area Ofqual has since retired.

**Badge_Type**:

    Generic Types:

        Experience, Learning, Validation, Certification, Attendance, Work_Experience, Volunteering, Job,
        Apprenticeship, Course, Membership, Internship, Workshop, Campaigning, Activism, Other

    Navigatr Standard Types:

        Informal_Learning, Training, Certified, Qualification, Membership

**Source_Type**:

    Internal, Credly

**Badge_Cost**:

    Free, Paid, Other

**Badge_Level**:

    Generic Levels:

        Foundational, Intermediate, Advanced, Other

    Navigatr Standard Levels:

        Explore, Deepen, Apply, Teach, Lead

**Time_To_Earn**:

    Hours, Days, Weeks, Months, Years, Other

**Participation_Type**:

    In_Person, Hybrid, Online

**Qualification_Type**:

    Award, Certificate, Diploma

## Path parameters

- `badge_id` integer, required

## Headers

- `X-Access-Token` string, nullable

## Request body

- BadgeUpdate
  - `name` string, nullable
  - `design_standard` 'Generic' | 'Navigatr'
  - `type` 'Experience' | 'Learning' | 'Validation' | 'Certification' | 'Attendance' | 'Work_Experience' | 'Volunteering' | 'Job' | 'Apprenticeship' | 'Course' | 'Internship' | 'Workshop' | 'Campaigning' | 'Activism' | 'Other' | 'Informal_Learning' | 'Training' | 'Certified' | 'Qualification' | 'Membership'
  - `language` 'Arabic_Modern_Standard' | 'Bengali' | 'Bulgarian' | 'Chinese_Cantonese' | 'Chinese_Mandarin' | 'Chinese_Simplified' | 'Chinese_Traditional' | 'Croatian' | 'Czech' | 'Dutch' | 'English' | 'French' | 'German' | 'Greek' | 'Hungarian' | 'Irish_Gaeilge' | 'Italian' | 'Kurdish_Kurmanji' | 'Kurdish_Sorani' | 'Latvian' | 'Lithuanian' | 'Pashto' | 'Persian' | 'Polish' | 'Portuguese' | 'Punjabi' | 'Romanian' | 'Scottish_Gaelic_Gaidhlig' | 'Slovak' | 'Somali' | 'Spanish' | 'Tigrinya' | 'Turkish' | 'Ukrainian' | 'Urdu' | 'Welsh_Cymraeg'
  - `provider_ids` integer[], nullable
  - `community_ids` integer[], nullable
  - `recipient_type` 'User' | 'Organisation'
  - `description` string, nullable
  - `issuer_id` integer, nullable
  - `image_url` string, nullable
  - `image_url_2x` string, nullable
  - `image_url_original` string, nullable
  - `design_parameters` unknown
  - `source` 'Internal' | 'Credly' | 'Open_University' | 'Imported'
  - `earn_url` string, nullable
  - `external_url` string, nullable
  - `information_url` string, nullable
  - `embed` string, nullable
  - `external_id` string, nullable
  - `latitude` number, nullable
  - `longitude` number, nullable
  - `city` string, nullable
  - `country` string, nullable
  - `config` unknown
  - `address` string, nullable
  - `available_to_all` boolean, nullable
  - `availability` string, nullable
  - `end_date` string, date-time, nullable
  - `cost` 'Free' | 'Paid' | 'Other'
  - `level` 'Foundational' | 'Intermediate' | 'Advanced' | 'Other' | 'Explore' | 'Deepen' | 'Apply' | 'Teach' | 'Lead'
  - `time_to_earn` 'Hours' | 'Days' | 'Weeks' | 'Months' | 'Years' | 'Other'
  - `participation_type` 'Online' | 'Hybrid' | 'In_Person'
  - `qa_locked` boolean, nullable
  - `job_titles` string[], nullable
  - `specialized_occupations` string[], nullable
  - `title_names` string[], nullable
  - `is_demo` boolean, nullable
  - `certificates_enabled` boolean
  - `industries` string[], nullable
  - `occupation_groups` string[], nullable
  - `skill_category_names` string[], nullable
  - `edu_levels` string[], nullable
  - `qualification_code` string, nullable
  - `credits_available` number, nullable
  - `credits_unit` string, nullable
  - `qualification_type` 'Award' | 'Certificate' | 'Diploma'
  - `qualification_framework` 'RQF' | 'CQFW' | 'SCQF' | 'EQF' | 'QFEmirates'
  - `qualification_level` string, nullable
  - `grade` 'Pass' | 'Merit' | 'Distinction' | 'Distinction*'
  - `field_of_study_id` integer, nullable
  - `criteria` BadgeCriteria[], nullable
    - `external_id` string, nullable
    - `description` string, nullable
    - `type` 'Application' | 'Assessment' | 'Award' | 'Badge' | 'Course' | 'Credential' | 'Education_Experience' | 'Leadership' | 'Member' | 'Participant' | 'Pathway' | 'Payment' | 'Portfolio' | 'Presenter' | 'Project' | 'Professional_Experience' | 'Schedule_Registration' | 'Volunteer' | 'Other'
    - `external_url` string, nullable
    - `badge_id` integer, nullable
    - `id` integer, nullable
  - `alignments` BadgeAlignment[], nullable
    - `external_id` string, nullable
    - `name` string, nullable
    - `description` string, nullable
    - `url` string, nullable
    - `framework` string, nullable
    - `code` string, nullable
    - `id` integer, nullable
    - `badge_id` integer, nullable
  - `endorsements` BadgeEndorsement[], nullable
    - `external_id` string, nullable
    - `name` string, nullable
    - `description` string, nullable
    - `url` string, nullable
    - `image_url` string, nullable
    - `image_url_2x` string, nullable
    - `image_url_original` string, nullable
    - `id` integer, nullable
    - `badge_id` integer, nullable
  - `tags` BadgeTag[], nullable
    - `name` string, nullable
    - `external_id` string, nullable
    - `type` string, nullable
    - `source` string, nullable

## Response `200`

Successful Response

- Badge
  - `name` string, nullable
  - `design_standard` 'Generic' | 'Navigatr'
  - `type` 'Experience' | 'Learning' | 'Validation' | 'Certification' | 'Attendance' | 'Work_Experience' | 'Volunteering' | 'Job' | 'Apprenticeship' | 'Course' | 'Internship' | 'Workshop' | 'Campaigning' | 'Activism' | 'Other' | 'Informal_Learning' | 'Training' | 'Certified' | 'Qualification' | 'Membership'
  - `language` 'Arabic_Modern_Standard' | 'Bengali' | 'Bulgarian' | 'Chinese_Cantonese' | 'Chinese_Mandarin' | 'Chinese_Simplified' | 'Chinese_Traditional' | 'Croatian' | 'Czech' | 'Dutch' | 'English' | 'French' | 'German' | 'Greek' | 'Hungarian' | 'Irish_Gaeilge' | 'Italian' | 'Kurdish_Kurmanji' | 'Kurdish_Sorani' | 'Latvian' | 'Lithuanian' | 'Pashto' | 'Persian' | 'Polish' | 'Portuguese' | 'Punjabi' | 'Romanian' | 'Scottish_Gaelic_Gaidhlig' | 'Slovak' | 'Somali' | 'Spanish' | 'Tigrinya' | 'Turkish' | 'Ukrainian' | 'Urdu' | 'Welsh_Cymraeg'
  - `provider_ids` integer[], nullable
  - `community_ids` integer[], nullable
  - `recipient_type` 'User' | 'Organisation'
  - `description` string, nullable
  - `issuer_id` integer, nullable
  - `image_url` string, nullable
  - `image_url_2x` string, nullable
  - `image_url_original` string, nullable
  - `design_parameters` unknown
  - `source` 'Internal' | 'Credly' | 'Open_University' | 'Imported'
  - `earn_url` string, nullable
  - `external_url` string, nullable
  - `information_url` string, nullable
  - `embed` string, nullable
  - `external_id` string, nullable
  - `latitude` number, nullable
  - `longitude` number, nullable
  - `city` string, nullable
  - `country` string, nullable
  - `config` unknown
  - `address` string, nullable
  - `available_to_all` boolean, nullable
  - `availability` string, nullable
  - `end_date` string, date-time, nullable
  - `cost` 'Free' | 'Paid' | 'Other'
  - `level` 'Foundational' | 'Intermediate' | 'Advanced' | 'Other' | 'Explore' | 'Deepen' | 'Apply' | 'Teach' | 'Lead'
  - `time_to_earn` 'Hours' | 'Days' | 'Weeks' | 'Months' | 'Years' | 'Other'
  - `participation_type` 'Online' | 'Hybrid' | 'In_Person'
  - `qa_locked` boolean, nullable
  - `job_titles` string[], nullable
  - `specialized_occupations` string[], nullable
  - `title_names` string[], nullable
  - `is_demo` boolean, nullable
  - `certificates_enabled` boolean
  - `industries` string[], nullable
  - `occupation_groups` string[], nullable
  - `skill_category_names` string[], nullable
  - `edu_levels` string[], nullable
  - `qualification_code` string, nullable
  - `credits_available` number, nullable
  - `credits_unit` string, nullable
  - `qualification_type` 'Award' | 'Certificate' | 'Diploma'
  - `qualification_framework` 'RQF' | 'CQFW' | 'SCQF' | 'EQF' | 'QFEmirates'
  - `qualification_level` string, nullable
  - `grade` 'Pass' | 'Merit' | 'Distinction' | 'Distinction*'
  - `field_of_study_id` integer, nullable
  - `id` integer
  - `status` 'Initialising' | 'Draft' | 'Awaiting_Approval' | 'Published' | 'Deleted' | 'Expired'
  - `created_by` UserDetailPublic
    - `id` integer
    - `firstname` string, nullable, required
    - `lastname` string, nullable, required
    - `avatar_url` string, nullable
    - `avatar_url_2x` string, nullable
    - `avatar_url_original` string, nullable
    - `interests` string[], nullable
    - `noindex_enabled` boolean, nullable
    - `visibility` 'Public' | 'Private': Who may see a user's human-readable public pages (profile, badge and pathway assertion). Deliberately NOT a User_Status value: a Private user is still Active, they can sign in, earn badges and be issued to exactly as before. Also independent of `noindex_enabled`, which only asks search engines not to index a page that stays publicly reachable. Enforced in crud_user_detail.can_read, so every existing "view this user" gate inherits it.
    - `time_created` string, date-time
    - `time_updated` string, date-time, nullable
    - `seo_keywords` string[], nullable
    - `seo_title` string, nullable
    - `seo_description` string, nullable
    - `social_handle_linkedin` string, nullable
    - `social_handle_twitter` string, nullable
    - `social_handle_facebook` string, nullable
    - `social_handle_instagram` string, nullable
  - `submitted_by` UserDetailPublic
    - `id` integer
    - `firstname` string, nullable, required
    - `lastname` string, nullable, required
    - `avatar_url` string, nullable
    - `avatar_url_2x` string, nullable
    - `avatar_url_original` string, nullable
    - `interests` string[], nullable
    - `noindex_enabled` boolean, nullable
    - `visibility` 'Public' | 'Private': Who may see a user's human-readable public pages (profile, badge and pathway assertion). Deliberately NOT a User_Status value: a Private user is still Active, they can sign in, earn badges and be issued to exactly as before. Also independent of `noindex_enabled`, which only asks search engines not to index a page that stays publicly reachable. Enforced in crud_user_detail.can_read, so every existing "view this user" gate inherits it.
    - `time_created` string, date-time
    - `time_updated` string, date-time, nullable
    - `seo_keywords` string[], nullable
    - `seo_title` string, nullable
    - `seo_description` string, nullable
    - `social_handle_linkedin` string, nullable
    - `social_handle_twitter` string, nullable
    - `social_handle_facebook` string, nullable
    - `social_handle_instagram` string, nullable
  - `published_by` UserDetailPublic
    - `id` integer
    - `firstname` string, nullable, required
    - `lastname` string, nullable, required
    - `avatar_url` string, nullable
    - `avatar_url_2x` string, nullable
    - `avatar_url_original` string, nullable
    - `interests` string[], nullable
    - `noindex_enabled` boolean, nullable
    - `visibility` 'Public' | 'Private': Who may see a user's human-readable public pages (profile, badge and pathway assertion). Deliberately NOT a User_Status value: a Private user is still Active, they can sign in, earn badges and be issued to exactly as before. Also independent of `noindex_enabled`, which only asks search engines not to index a page that stays publicly reachable. Enforced in crud_user_detail.can_read, so every existing "view this user" gate inherits it.
    - `time_created` string, date-time
    - `time_updated` string, date-time, nullable
    - `seo_keywords` string[], nullable
    - `seo_title` string, nullable
    - `seo_description` string, nullable
    - `social_handle_linkedin` string, nullable
    - `social_handle_twitter` string, nullable
    - `social_handle_facebook` string, nullable
    - `social_handle_instagram` string, nullable
  - `updated_by` UserDetailPublic
    - `id` integer
    - `firstname` string, nullable, required
    - `lastname` string, nullable, required
    - `avatar_url` string, nullable
    - `avatar_url_2x` string, nullable
    - `avatar_url_original` string, nullable
    - `interests` string[], nullable
    - `noindex_enabled` boolean, nullable
    - `visibility` 'Public' | 'Private': Who may see a user's human-readable public pages (profile, badge and pathway assertion). Deliberately NOT a User_Status value: a Private user is still Active, they can sign in, earn badges and be issued to exactly as before. Also independent of `noindex_enabled`, which only asks search engines not to index a page that stays publicly reachable. Enforced in crud_user_detail.can_read, so every existing "view this user" gate inherits it.
    - `time_created` string, date-time
    - `time_updated` string, date-time, nullable
    - `seo_keywords` string[], nullable
    - `seo_title` string, nullable
    - `seo_description` string, nullable
    - `social_handle_linkedin` string, nullable
    - `social_handle_twitter` string, nullable
    - `social_handle_facebook` string, nullable
    - `social_handle_instagram` string, nullable
  - `issuer` BadgeIssuerPublic
    - `id` integer
    - `name` string, nullable
    - `type` 'Employer' | 'Learning_Provider' | 'Other'
    - `status` 'Active' | 'Suspended' | 'Deleted'
    - `external_url` string, nullable
    - `email` string, nullable
    - `image_url` string, nullable
    - `banner_url` string, nullable
    - `image_url_2x` string, nullable
    - `banner_url_2x` string, nullable
  - `ranking` integer, nullable
  - `time_created` string, date-time
  - `time_updated` string, date-time, nullable
  - `time_submitted` string, date-time, nullable
  - `time_published` string, date-time, nullable
  - `quality_assured_at` string, date-time, nullable
  - `time_issued` string, date-time, nullable
  - `postal_address` Address
    - `full_address` string, nullable
    - `name` string, nullable
    - `number` string, nullable
    - `street` string, nullable
    - `postcode` string, nullable
    - `locality` string, nullable
    - `city` string, nullable
    - `district` string, nullable
    - `region` string, nullable
    - `country` string, nullable
  - `created_by_id` integer, nullable
  - `submitted_by_id` integer, nullable
  - `published_by_id` integer, nullable
  - `updated_by_id` integer, nullable
  - `criteria` BadgeCriteria[], nullable
    - `external_id` string, nullable
    - `description` string, nullable
    - `type` 'Application' | 'Assessment' | 'Award' | 'Badge' | 'Course' | 'Credential' | 'Education_Experience' | 'Leadership' | 'Member' | 'Participant' | 'Pathway' | 'Payment' | 'Portfolio' | 'Presenter' | 'Project' | 'Professional_Experience' | 'Schedule_Registration' | 'Volunteer' | 'Other'
    - `external_url` string, nullable
    - `badge_id` integer, nullable
    - `id` integer, nullable
  - `tags` BadgeTag[], nullable
    - `name` string, nullable
    - `external_id` string, nullable
    - `type` string, nullable
    - `source` string, nullable
  - `alignments` BadgeAlignment[], nullable
    - `external_id` string, nullable
    - `name` string, nullable
    - `description` string, nullable
    - `url` string, nullable
    - `framework` string, nullable
    - `code` string, nullable
    - `id` integer, nullable
    - `badge_id` integer, nullable
  - `endorsements` BadgeEndorsement[], nullable
    - `external_id` string, nullable
    - `name` string, nullable
    - `description` string, nullable
    - `url` string, nullable
    - `image_url` string, nullable
    - `image_url_2x` string, nullable
    - `image_url_original` string, nullable
    - `id` integer, nullable
    - `badge_id` integer, nullable
  - `collections` CollectionLight[], nullable
    - `id` integer, required
    - `name` string, nullable
    - `badge_issuer_id` integer, nullable
  - `providers` ProviderLight[], nullable
    - `id` integer, required
    - `status` 'Active' | 'Suspended' | 'Deleted'
    - `type` 'Learning_Provider' | 'Training_Provider' | 'Awarding_Body' | 'Employer' | 'Local_Authority' | 'University' | 'College' | 'Charity' | 'Department' | 'Project' | 'Other'
    - `name` string, nullable
    - `short_name` string, nullable
    - `external_url` string, nullable
    - `is_verified` boolean, nullable
    - `verification_text` string, nullable
    - `verification_url` string, nullable
    - `is_demo` boolean, nullable
    - `open_access` boolean
    - `community_id` integer, nullable
    - `community` CommunityLight, required
      - `id` integer, required
      - `status` 'Active' | 'Suspended' | 'Deleted'
      - `type` 'City' | 'Region' | 'Local_Authority' | 'Membership_Organisation' | 'Awarding_Body' | 'Partnership' | 'Corporate' | 'Association' | 'University' | 'College' | 'Charity' | 'Other'
      - `name` string, nullable
      - `short_name` string, nullable
      - `is_verified` boolean, nullable
      - `image_url` string, nullable
      - `image_url_2x` string, nullable
      - `image_url_original` string, nullable
      - `linkedin_organisation_id` integer, nullable
      - `social_handle_linkedin` string, nullable
      - `social_handle_twitter` string, nullable
      - `social_handle_facebook` string, nullable
      - `social_handle_instagram` string, nullable
      - `url` string, nullable
    - `image_url` string, nullable
    - `banner_url` string, nullable
    - `image_url_2x` string, nullable
    - `banner_url_2x` string, nullable
    - `image_url_original` string, nullable
    - `banner_url_original` string, nullable
    - `qa_community_id` integer, nullable
    - `linkedin_organisation_id` integer, nullable
    - `social_handle_linkedin` string, nullable
    - `social_handle_twitter` string, nullable
    - `social_handle_facebook` string, nullable
    - `social_handle_instagram` string, nullable
    - `url` string, nullable
  - `interacted_with` boolean, nullable
  - `featured` boolean
  - `ai_generated` boolean
  - `url` string
  - `seo_keywords` string[], nullable
  - `seo_title` string, nullable
  - `seo_description` string, nullable
  - `field_of_study` SectorSubjectAreaEmbedded: A badge's field of study as embedded in badge reads and the Ofqual lookup (#1946). The website editor and the CLI read these names, so they are a contract.
    - `id` integer, required
    - `code` string, required
    - `name` string, required
    - `tier_1_name` string, nullable
    - `image_label` string, nullable
  - `display_level` string, nullable, required: The one level to show: the qualification level label when set, else `level` (#1915).

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Validation Error
- `423`: Locked

## Changes

- **2026-11-06** `04bf6727d360`: 1 info
  - added the optional property `quality_assured_at` to the response with the `200` status
- **2026-10-22** `5b575d75af2b`: 18 info
  - added the new optional request property `credits_available`
  - added the new optional request property `credits_unit`
  - added the new optional request property `field_of_study_id`
  - added the new optional request property `grade`
  - …14 more
- **2026-10-06** `d2127ead6e50`: 2 warning, 2 info
  - removed the request property `qa_required`
  - removed the optional property `qa_required` from the response with the `200` status
  - added the new optional request property `qa_locked`
  - added the optional property `qa_locked` to the response with the `200` status
- **2026-09-29** `88bdee3363ad`: 2 info
  - added the new optional request property `certificates_enabled`
  - added the optional property `certificates_enabled` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/navigatr/apis/navigatr-api/changes/v1/badge/:badge_id/put.md)

---

[API](https://skmtc.dev/navigatr/apis/navigatr-api.md) - [All operations](https://skmtc.dev/navigatr/apis/navigatr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/navigatr/apis/navigatr-api/revisions/efbd3c328549?raw)