---
title: "Create Badge"
method: POST
path: "/v1/badge/"
tags: ["Badge"]
---

# Create Badge

`POST /v1/badge/`

Creates a new badge. This is metadata describing a **Badge** provided on a digital credentialing platform. A **provider_id**
can be specified for internal and Open University badges. That provider will have access to edit and issue the badge. More providers can be added later by
platform admins.

    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): Mandatory field.
    recipient_type (Recipient_Type): Optional field. Defaults to User.
    source (Source_Type): Optional field. Defaults to Internal. Other options are Credly and Open_University. If External, external_id and external_url are mandatory.
    external_id (str): Optional field. The unique ID on the external platform. If the badge already exists on Navigatr, it will be updated. If not, it will be created. External ID is required for all external badges.
    external_url (str): Optional field. URL of the badge on the external platform. External URL is required for all external badges.
    earn_url (str): Optional field. URL to earn the badge. Defaults to None.
    information_url (str): Optional field. A link to display additional information about this badge. Defaults to None.
    cost (Badge_Cost): Optional field. Defaults to Free
    level (Badge_Level): Optional field. Defaults to Foundational
    time_to_earn (Time_To_Earn): Optional field. Defaults to Hours
    participation_type (Participation_Type): Optional field. Defaults to In_Person
    end_date (datetime): Optional field. Defaults to None
    time_created (datetime): Optional field. Defaults to the current time. For external badges, set the time created to match with the external platform.
    tags (List[Tag]): Optional field. Defaults to None.
    criteria (List[Criteria]): Optional field. Defaults to None.
    alignments (List[Alignment]): Optional field. Defaults to None.
    endorsements (List[Endorsement]): Optional field. Defaults to None.

generate_image (bool): Query param, defaults to False. If True, renders and uploads the
Navigatr Badge Framework image immediately after creation, using provider_id's default
branding. Requires design_standard=Navigatr, source=Internal (the default), no explicit
image_url/image_url_2x/image_url_original, and no design_parameters.subtitle override in
the body - any mismatch 422s up front, before any write. A failure in the render itself
(e.g. the provider's logo URL is unreachable) does not fail badge creation - the badge is
still created without an image.

**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

**Source_Type**:

    Internal, Credly, Open_University

**Recipient_Type**:

    User, Organisation

**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

## Query parameters

- `provider_id` integer
- `generate_image` boolean

## Headers

- `X-Access-Token` string, nullable

## Request body

- BadgeCreate
  - `name` string, required
  - `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', required
  - `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, required
  - `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
  - `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_required` boolean, nullable
  - `job_feed_enabled` boolean, nullable
  - `job_feed_levels` JobLevel[], nullable
  - `job_feed_companies` string[], nullable
  - `job_titles` string[], nullable
  - `is_demo` boolean, nullable
  - `industries` string[], nullable
  - `occupation_groups` string[], nullable
  - `skill_category_names` string[], nullable
  - `edu_levels` string[], nullable
  - `featured` boolean
  - `ai_generated` boolean
  - `time_created` string, date-time
  - `criteria` BadgeCriteriaCreate[], nullable
    - `external_id` string, nullable
    - `description` string, required
    - `type` 'Application' | 'Assessment' | 'Award' | 'Badge' | 'Course' | 'Credential' | 'Education_Experience' | 'Leadership' | 'Member' | 'Participant' | 'Pathway' | 'Payment' | 'Portfolio' | 'Presenter' | 'Project' | 'Professional_Experience' | 'Schedule_Registration' | 'Volunteer' | 'Other', required
    - `external_url` string, nullable
    - `badge_id` integer, nullable
  - `alignments` BadgeAlignmentCreate[], nullable
    - `external_id` string, nullable
    - `name` string, required
    - `description` string, required
    - `url` string, required
    - `framework` string, nullable
    - `code` string, nullable
  - `endorsements` BadgeEndorsementCreate[], nullable
    - `external_id` string, nullable
    - `name` string, required
    - `description` string, required
    - `url` string, nullable
    - `image_url` string, nullable
    - `image_url_2x` string, nullable
    - `image_url_original` string, nullable
  - `tags` BadgeTagCreate[], nullable
    - `name` string, required
    - `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_required` boolean, nullable
  - `job_feed_enabled` boolean, nullable
  - `job_feed_levels` JobLevel[], nullable
  - `job_feed_companies` string[], nullable
  - `job_titles` string[], nullable
  - `is_demo` boolean, nullable
  - `industries` string[], nullable
  - `occupation_groups` string[], nullable
  - `skill_category_names` string[], nullable
  - `edu_levels` string[], 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
    - `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
    - `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
    - `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
    - `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
  - `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

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `422` — Unprocessable Content

---

[API](https://skmtc.net/navigatr/apis/navigatr-api.md) · [All operations](https://skmtc.net/navigatr/apis/navigatr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/navigatr/navigatr-api/revisions/4039d06e340b/schema)