Create 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.
design_parameters (object): Optional field. An object or null. Its `qa` (the QA mark, a bool) may be set to true only by a platform admin (403 otherwise); false, null or omitted is accepted from anyone.
qualification_code (str): Optional field, max 100 characters. Emitted in Open Badges 3.0 as otherIdentifier.
credits_available (float): Optional field, >= 0, stored rounded to two decimal places. Also used for CPD points.
credits_unit (str): Optional field, max 20 characters. What credits_available counts; null means "credits".
qualification_type (Qualification_Type): Optional field. Only accepted when type is Qualification (422 otherwise).
qualification_framework (Qualification_Framework): Optional field. RQF, CQFW, SCQF, EQF or QFEmirates. Defaults to RQF only when a qualification_level is sent without it; sent as null with a level is a 422.
qualification_level (str): Optional field. Must be valid for the framework (RQF and CQFW: Entry 1-3 and 1-8; SCQF 1-12; EQF and QFEmirates 1-8), 422 otherwise. Adds one system-managed alignment for the framework, replacing any alignment of that framework in the body.
grade (Badge_Grade): Optional field. Pass, Merit, Distinction or Distinction*. Shown on every issued badge of this badge, which cannot then be issued with a different grade.
field_of_study_id (int): Optional field, any badge type. An active tier 2 Ofqual Sector Subject Area id from GET /sector_subject_area (a tier 1, inactive or unknown id is a 422). Returned embedded as field_of_study and emitted in Open Badges 3.0 as fieldOfStudy.

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 unless the subtitle query param is also passed - 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.

title / subtitle (str, optional query params): the artwork text saved in design_parameters at creation, before any render, in both this and the AI route. They override the same keys in the body's design_parameters. Per key: omit to leave the body's value as sent, pass "" to remove it (title then falls back to the auto-filled field of study and qualification type on a Qualification badge that has both, else the badge name; subtitle to the auto-filled qualification line, if any), pass any other string to save it. A subtitle supplied here is the caller's own, so it is not subject to the saved-subtitle guard. Not validated against the render limits below (each param is capped at 200 characters); the renderer fits a title on at most 2 lines of 23 characters (17 on a Training badge); a subtitle is upper-cased and cut to 22 characters, then wrapped at 22 per line (16 on a Training badge). An over-long second line is cut to end in "...". Those are character counts calibrated for common English letters, so wide letters can still overflow: keep the title to one or two short words. A forced line break in the TITLE is the two-character sequence backslash-n stored in the string (%5Cn in the query string; no JSON escaping applies to a query parameter); the segment before it is not length-checked, and a real newline is drawn inline over the subtitle. The marker does not work in a subtitle, which is upper-cased before the check. Saved whether or not generate_image is set, so the website's first-view render uses them. Internal-source, Navigatr-standard badges only (422 otherwise, with or without generate_image): external-source badges carry their own image and Generic badges have no framework render.

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

Qualification_Type:

Award, Certificate, Diploma