Certificate Template Management

Retrieve the List of Certificate Templates

This API retrieves the list of an issuer's certificate templates in JSON format. It is accessed via a GET request to the endpoint [API-URL]/issuer/XXX/templates, where XXX is the issuer's identifier. You can find your issuer ID here.

Optional parameters:

• template-name: Filters the response to only return certificate templates whose names contain the provided string (case-insensitive).

Example: https://api.bcdiploma.com/issuer/2/templates?template-name=en

Retrieve the Definition of a Certificate Template

This API retrieves the definition of a certificate template for an issuer via a GET request to the endpoint [API-URL]/issuer/XXX/template/YYY/json, where XXX is the issuer's identifier and YYY is the template identifier.

Example request: https://api.bcdiploma.com/issuer/2/template/1x04/json

Retrieve the List of Variable Fields of a Certificate Template

This API retrieves the variable fields of a certificate template for an issuer via a GET request to the endpoint [API-URL]/issuer/XXX/template/YYY/fields, where XXX is the issuer's identifier and YYY is the template identifier.

By default, the response is returned as text, with fields separated by ;. By adding ?Content-Type=application%2Fjson to the GET request, the result will be returned in JSON format.

Example request: https://api.bcdiploma.com/issuer/2/template/1x04/fields?Content-Type=application%2Fjson

Create and Update a Microcredential Template

Microcredential templates can be added or updated via a POST request to the endpoint [API-URL]/template/mc.

The request body is a multipart form containing the following parts:

• json: The JSON containing the template definition. Required for creation and update.

• badgeImage: A file containing the main image of the microcredential. Required for creation and optional for updates. Supported formats: PNG and SVG. PNG optimal size: 240px square.

• partnerImage: A file containing the partner's logo. Supported format: PNG. Optional.

• issuerImage: A file containing the issuer's logo. Supported format: PNG. Optional.

Creating a Microcredential Template

The request body for creating a microcredential template is a multipart form that must include parts for badgeImage and json. The json part, which contains the template definition, is a JSON object containing the following elements:

Required:

• mode: In "creation" mode, must have the value add.
• label: The title of the template. Can be a simple string or a JSON object with titles in multiple languages.
• json: The texts and dynamic fields for the template. To reduce payload size, the template fields are encoded (A, B, C, etc.). A reference table mapping these codes to fields is provided below.
• DefaultLanguage: The template's default language in ISO-2 format. Must match language codes present in the json element.
• badge: a JSON object that uses language codes as keys, and the filename(s) specified in the badgeImage part of the multipart form, for each template language (even if the image is the same across all languages).

Optional:

• partnerLogo: a JSON object that uses language codes as keys, and the filename(s) specified in the partnerImage part of the multipart form, for each template language.
• issuerLogo: a JSON object that uses language codes as keys, and the filename(s) specified in the issuerImage part of the multipart form, for each template language.
• notification: List of email addresses to notify after the template's creation, separated by commas.
• cstyle: Describes the desired layout and style for the template. This element's functionality is detailed in a dedicated section below.

On success, the endpoint returns the identifier of the new template as a string, e.g., 1x49.

Example of a valid json part for creating a microcredential template:

• With a bilingual title
• Bilingual, with en as the default language
• Allowing different badge and partner images per language
• With a 3-column layout, inspired by the "Midnight Vision" theme available in the back office.
• With email notification upon successful creation

{
  "mode": "add",
  "label": {
    "en": "BCdiploma Expert",
    "fr": "Expert BCdiploma"
  },
  "json": {
    "A": {
      "en": "Issuing body:",
      "fr": "Émetteur :"
    },
    "T": "Leaston University",
    "B": {
      "en": "Partner endorsement:",
      "fr": "Partenaire :"
    },
    "E": {
      "en": "Other partners:",
      "fr": "Autres partenaires :"
    },
    "F": "Blockchain Certified Data",
    "G": {
      "en": "Micro-certification issued to",
      "fr": "Micro-certification délivrée à"
    },
    "I": {
      "en": "on:",
      "fr": "le :"
    },
    "K": {
      "en": "Expiration date:",
      "fr": "Date d'expiration :"
    },
    "M": {
      "en": "Outcomes",
      "fr": "Résultats"
    },
    "description": {
      "en": "Holders of this micro-certification have a thorough knowledge of the world of digital credentials and associated open standards such as Open Badges. Micro-credential holders also understand the concept of the BCdiploma templates and know how to implement it to build customized micro-credentials for any institution.",
      "fr": "Les titulaires de cette micro-certification ont une connaissance approfondie du monde des attestations numériques et des normes ouvertes associées, telles que les Open Badges. Les titulaires de cette micro-certification comprennent également le concept des modèles BCdiploma et savent comment les mettre en œuvre pour créer des micro-credentials personnalisés pour n'importe quelle institution."
    },
    "N": {
      "en": "Competency / Skills",
      "fr": "Compétences / Aptitudes"
    },
    "skills": {
      "en": "Blockchain basics;Micro-Credentials;Digital Credentials;Open Badges",
      "fr": "Blockchain basics;Digital Credentials;Micro-Credentials;Open Badges"
    },
    "O": {
      "en": "Assessment",
      "fr": "Évaluation"
    },
    "criteria": {
      "en": "Completion of the BCdiploma backoffice training session including issuing and sharing micro-credentials on the blockchain.",
      "fr": "Participation à la session de formation au backoffice de BCdiploma, incluant l'émission et le partage de micro-credentials sur la blockchain."
    },
    "Q": {
      "en": "Component of",
      "fr": "Composant de"
    }
  },
  "DefaultLanguage": "en",
  "badge": {
    "en": "badge_en.svg",
    "fr": "badge_fr.svg"
  },
  "partnerLogo": {
    "en": "partner.png",
    "fr": "partner.png"
  },
  "issuerLogo": {
    "en": "issuer.png",
    "fr": "issuer.png"
  },
  "cstyle": "{l:'threeCol',R:{f:'Raleway',g:'#25225BFF'},T:{w:500,s:'32px',g:'#FFFFFF00',c:'#FFFFFFFF'},I:{c:'#D1D4D5'},U:{w:700,s:'16px',c:'#6259F4FF'},P:{w:400,s:'16px',c:'#FFFFFFFF'},N:{w:700,s:'24px',c:'#FFFFFFFF'},K:{w:400,s:'16px',g:'#FFFFFF00',c:'#FFFFFFFF',b:'1px #6259F4FF',r:'5px'},L:{w:400,s:'16px',c:'#6259F4FF'},S:{g:'#000000FF'}}",
  "notification": "support@bcdiploma.com"
}

Updating a Microcredential Template

The request body for updating a microcredential template is a multipart form that must include a json part. This json part, containing the template definition, is a JSON object containing the following elements:

Required:

• mode: In update mode, must have the value update.
• id: The ID of the template to be updated.
• json: The texts and dynamic fields for the template. To reduce payload size, only texts and dynamic fields requiring updates may be included.
• DefaultLanguage: The default language for the template in ISO-2 format. Must match language codes present in the json element.

Optional: label, badge, partnerLogo, notification, cstyle

Example of a valid json part for updating a microcredential template:

• With an updated title for the microcredential
• Without updating the template definition

{
  "mode": "update",
  "id": "1x49",
  "label": "BCdiploma Expert",
  "json": {},
  "DefaultLanguage": "en"
}

Reference Table for Code/Field Used in Microcredential Data Model Description

To reduce payload, the field names constituting a microcredential template are replaced by codes (letters or words) in the json expected during template creation or update. A reference table for these codes is provided below. Most fields are required. The endpoint will return a 400 error if required fields are missing.

Customizing Template Layout and Style via "cstyle"

The layout (choice of number of columns or custom layout provided by BCdiploma if available) and style (font, colors, sizes of graphical elements) of your template can be managed via API using the cstyle element in the multipart form's json part.

The cstyle element consists of a layout element describing the chosen layout and style elements allowing formatting adjustments. The layout element can have the following values:

• oneCol: single-column layout
• legacy: two-column layout
• threeCol: three-column layout
• CUSTOM_LAYOUT: custom layout provided by BCdiploma teams, if available. This layout does not support style element modifications.

You may include only elements you wish to override from the default configuration in the cstyle element.

Default layout and style for microcredential templates created via back office are detailed below, along with all available components and CSS attributes modifiable via API.

{
  "layout": "legacy",
  "root": {
    "fontFamily": "Roboto",
    "background": "#f7f7f7"
  },
  "title": {
    "fontWeight": 300,
    "fontSize": "32px",
    "background": "#FFF",
    "color": "#005E7A"
  },
  "splitter": {
    "color": "#D1D4D5"
  },
  "subTitle": {
    "fontWeight": 700,
    "fontSize": "16px",
    "color": "#005E7A"
  },
  "paragraph": {
    "fontWeight": 400,
    "fontSize": "16px",
    "color": "#002432"
  },
  "graduateName": {
    "fontWeight": 700,
    "fontSize": "24px",
    "color": "#002432"
  },
  "skill": {
    "fontWeight": 400,
    "fontSize": "18px",
    "background": "#fff",
    "color": "#005E7A",
    "border": "1px #005E7A",
    "borderRadius": "0px"
  },
  "link": {
    "fontWeight": 400,
    "fontSize": "16px",
    "color": "#005E7A"
  },
  "section": {
    "background": "#FFF"
  }
}

To reduce payload size, the cstyle element uses compressed JSON5 syntax with short codes corresponding to the template's graphical elements and CSS attributes. Here is the reference table for these codes. Note that uppercase codes correspond to template components, while lowercase codes correspond to CSS attributes of these components.

The equivalent "cstyle" format for the default layout and style is as follows:

{l:'legacy',R:{f:'Roboto',g:'#f7f7f7'},T:{w:300,s:'32px',g:'#FFF',c:'#005E7A'},I:{c:'#D1D4D5'},U:{w:700,s:'16px',c:'#005E7A'},P:{w:400,s:'16px',c:'#002432'},N:{w:700,s:'24px',c:'#002432'},K:{w:400,s:'18px',g:'#fff',c:'#005E7A',b:'1px #005E7A',r:'0px'},L:{w:400,s:'16px',c:'#005E7A'},S:{g:'#FFF'}}"

Note on Usable Fonts for Template Styles

The list of fonts available for use in template styles can be accessed here.