Badge

Update Badge

Changed on Nov 6, 2026

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

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)
Auth
OAuth 2
Password
Token URL/v1/token
TypeScript
https://skmtc.dev/navigatr/apis/navigatr-api/docs/v1/badge/:badge_id/put.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

badge_idinteger required

Headers

X-Access-Tokenstring nullable

Request body

namestring nullable

design_standard'Generic' | 'Navigatr'

provider_idsinteger[] nullable

community_idsinteger[] nullable

recipient_type'User' | 'Organisation'

descriptionstring nullable

issuer_idinteger nullable

image_urlstring nullable

image_url_2xstring nullable

image_url_originalstring nullable

design_parametersunknown

source'Internal' | 'Credly' | 'Open_University' | 'Imported'

earn_urlstring nullable

external_urlstring nullable

information_urlstring nullable

embedstring nullable

external_idstring nullable

latitudenumber nullable

longitudenumber nullable

citystring nullable

countrystring nullable

configunknown

addressstring nullable

available_to_allboolean nullable

availabilitystring nullable

end_datestring date-time nullable

cost'Free' | 'Paid' | 'Other'

participation_type'Online' | 'Hybrid' | 'In_Person'

qa_lockedboolean nullable

job_titlesstring[] nullable

specialized_occupationsstring[] nullable

title_namesstring[] nullable

is_demoboolean nullable

certificates_enabledboolean

industriesstring[] nullable

occupation_groupsstring[] nullable

skill_category_namesstring[] nullable

edu_levelsstring[] nullable

qualification_codestring nullable

credits_availablenumber nullable

credits_unitstring nullable

qualification_type'Award' | 'Certificate' | 'Diploma'

qualification_framework'RQF' | 'CQFW' | 'SCQF' | 'EQF' | 'QFEmirates'

qualification_levelstring nullable

grade'Pass' | 'Merit' | 'Distinction' | 'Distinction*'

field_of_study_idinteger nullable

Example request

{
  "description": "This badge is awarded to earners who have demonstrated their knowledge of all letters of the English alphabet.",
  "image_url": "https://media.navigatr.app/image.webp",
  "image_url_2x": "https://media.navigatr.app/image_2x.webp",
  "address": "123 Example Street, Leeds, West Yorkshire, England, LS1 EXA",
  "availability": "This badge is available to students of the University of Leeds",
  "end_date": "2023-11-18T13:33:01.201Z",
  "qualification_code": "603/1234/5",
  "credits_available": 60,
  "credits_unit": "credits",
  "qualification_level": "3",
  "field_of_study_id": 3,
  "criteria": [
    {
      "external_id": "ABCD-EFG-HIJK-LMNOPQRS",
      "description": "Earners must have completed a three stage interview process before they can earn this badge.",
      "external_url": "https://apply.org"
    }
  ],
  "alignments": [
    {
      "external_id": "123-45678-90",
      "name": "Null Badging Standard - Example Layer",
      "description": "This badge has been mapped to the Example Layer of the Null Badging Standard",
      "url": "https://Null_Badging/Example.org"
    }
  ],
  "endorsements": [
    {
      "external_id": "zyxw-vut-srq-ponmlkjih",
      "name": "Endorsement Example",
      "description": "This is an example of a badge endorsement",
      "url": "https://Endorsement/Example.org",
      "image_url": "https://media.navigatr.app/endorsement.webp",
      "image_url_2x": "https://media.navigatr.app/endorsement_2x.webp",
      "image_url_original": "https://media.navigatr.app/endorsement_original.webp"
    }
  ],
  "tags": [
    {
      "name": "Test Driven Development"
    }
  ]
}

Response

Successful Response

namestring nullable

design_standard'Generic' | 'Navigatr'

provider_idsinteger[] nullable

community_idsinteger[] nullable

recipient_type'User' | 'Organisation'

descriptionstring nullable

issuer_idinteger nullable

image_urlstring nullable

image_url_2xstring nullable

image_url_originalstring nullable

design_parametersunknown

source'Internal' | 'Credly' | 'Open_University' | 'Imported'

earn_urlstring nullable

external_urlstring nullable

information_urlstring nullable

embedstring nullable

external_idstring nullable

latitudenumber nullable

longitudenumber nullable

citystring nullable

countrystring nullable

configunknown

addressstring nullable

available_to_allboolean nullable

availabilitystring nullable

end_datestring date-time nullable

cost'Free' | 'Paid' | 'Other'

participation_type'Online' | 'Hybrid' | 'In_Person'

qa_lockedboolean nullable

job_titlesstring[] nullable

specialized_occupationsstring[] nullable

title_namesstring[] nullable

is_demoboolean nullable

certificates_enabledboolean

industriesstring[] nullable

occupation_groupsstring[] nullable

skill_category_namesstring[] nullable

edu_levelsstring[] nullable

qualification_codestring nullable

credits_availablenumber nullable

credits_unitstring nullable

qualification_type'Award' | 'Certificate' | 'Diploma'

qualification_framework'RQF' | 'CQFW' | 'SCQF' | 'EQF' | 'QFEmirates'

qualification_levelstring nullable

grade'Pass' | 'Merit' | 'Distinction' | 'Distinction*'

field_of_study_idinteger nullable

idinteger

rankinginteger nullable

time_createdstring date-time

time_updatedstring date-time nullable

time_submittedstring date-time nullable

time_publishedstring date-time nullable

quality_assured_atstring date-time nullable

time_issuedstring date-time nullable

created_by_idinteger nullable

submitted_by_idinteger nullable

published_by_idinteger nullable

updated_by_idinteger nullable

interacted_withboolean nullable

featuredboolean

ai_generatedboolean

urlstring

seo_keywordsstring[] nullable

seo_titlestring nullable

seo_descriptionstring nullable

display_levelstring nullable required

The one level to show: the qualification level label when set, else level (#1915).

Example response

{
  "name": "Learn your ABCs",
  "description": "This badge is awarded to earners who have demonstrated their knowledge of all letters of the English alphabet.",
  "image_url": "https://media.navigatr.app/image.webp",
  "image_url_2x": "https://media.navigatr.app/image_2x.webp",
  "address": "123 Example Street, Leeds, West Yorkshire, England, LS1 EXA",
  "availability": "This badge is available to students of the University of Leeds",
  "end_date": "2023-11-18T13:33:01.201Z",
  "qualification_code": "603/1234/5",
  "credits_available": 60,
  "credits_unit": "credits",
  "qualification_level": "3",
  "field_of_study_id": 3,
  "created_by": {
    "firstname": "John",
    "lastname": "Doe",
    "avatar_url": "https://media.navigatr.app/avatar.webp",
    "avatar_url_2x": "https://media.navigatr.app/avatar_2x.webp",
    "avatar_url_original": "https://media.navigatr.app/avatar_original.webp",
    "interests": [
      "Coding, Web Development, Engineering"
    ]
  },
  "submitted_by": {
    "firstname": "John",
    "lastname": "Doe",
    "avatar_url": "https://media.navigatr.app/avatar.webp",
    "avatar_url_2x": "https://media.navigatr.app/avatar_2x.webp",
    "avatar_url_original": "https://media.navigatr.app/avatar_original.webp",
    "interests": [
      "Coding, Web Development, Engineering"
    ]
  },
  "published_by": {
    "firstname": "John",
    "lastname": "Doe",
    "avatar_url": "https://media.navigatr.app/avatar.webp",
    "avatar_url_2x": "https://media.navigatr.app/avatar_2x.webp",
    "avatar_url_original": "https://media.navigatr.app/avatar_original.webp",
    "interests": [
      "Coding, Web Development, Engineering"
    ]
  },
  "updated_by": {
    "firstname": "John",
    "lastname": "Doe",
    "avatar_url": "https://media.navigatr.app/avatar.webp",
    "avatar_url_2x": "https://media.navigatr.app/avatar_2x.webp",
    "avatar_url_original": "https://media.navigatr.app/avatar_original.webp",
    "interests": [
      "Coding, Web Development, Engineering"
    ]
  },
  "criteria": [
    {
      "external_id": "ABCD-EFG-HIJK-LMNOPQRS",
      "description": "Earners must have completed a three stage interview process before they can earn this badge.",
      "external_url": "https://apply.org"
    }
  ],
  "tags": [
    {
      "name": "Test Driven Development"
    }
  ],
  "alignments": [
    {
      "external_id": "123-45678-90",
      "name": "Null Badging Standard - Example Layer",
      "description": "This badge has been mapped to the Example Layer of the Null Badging Standard",
      "url": "https://Null_Badging/Example.org"
    }
  ],
  "endorsements": [
    {
      "external_id": "zyxw-vut-srq-ponmlkjih",
      "name": "Endorsement Example",
      "description": "This is an example of a badge endorsement",
      "url": "https://Endorsement/Example.org",
      "image_url": "https://media.navigatr.app/endorsement.webp",
      "image_url_2x": "https://media.navigatr.app/endorsement_2x.webp",
      "image_url_original": "https://media.navigatr.app/endorsement_original.webp"
    }
  ],
  "providers": [
    {
      "name": "Horace's Haberdashery Academy",
      "short_name": "HHA",
      "community": {
        "name": "Fordwich Town Council",
        "short_name": "FTC",
        "image_url": "https://media.navigatr.app/Fordwich.webp",
        "image_url_2x": "https://media.navigatr.app/Fordwich_2x.webp",
        "image_url_original": "https://media.navigatr.app/Fordwich_original.webp",
        "url": "https://navigatr.app/community/5/fordwich-town-council"
      },
      "image_url": "https://media.navigatr.app/HHA.webp",
      "banner_url": "https://media.navigatr.app/HHA_banner.webp",
      "image_url_2x": "https://media.navigatr.app/HHA_2x.webp",
      "banner_url_2x": "https://media.navigatr.app/HHA_banner_2x.webp",
      "image_url_original": "https://media.navigatr.app/HHA_original.webp",
      "banner_url_original": "https://media.navigatr.app/HHA_banner_original.webp",
      "url": "https://navigatr.app/provider/2922/horaces-haberdashery"
    }
  ],
  "url": "https://navigatr.app/badge/12345/Learn-Your-ABCs"
}

Changes

Nov 6, 202604bf6727d360 Revision changes
- info
  added the optional property to the response with the status
Oct 22, 20265b575d75af2b Revision changes
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the required property to the response with the status

Operation history (9 revisions)