v1

latestOpenAPI 3.1.02026-08-0653126213.6 KB

Badge

Issue Badge

Create a badge assertion and issue a badge to a user (or organisation).

Issuing to an organisation follows the same functionally as issuing to a user, except that the user will be accepting the badge on behalf of their organisation.

Required:

provider_id - Assertions are issued from a provider. This ID must be one of the badge's providers.

If the user ID is known (the user has a Navigatr account):

recipient_id

If the user ID is not known (the user may or may not have a Navigatr account):

recipient_email
recipient_firstname
recipient_lastname

If the user QR code is known (the user has a Navigatr account):

qr_id

If the user's Spydus library card barcode ID is known (the user has a Navigatr account):

spydus_barcode_id

If the assertion is for an organisation:

recipient_organisation - Name of the organisation (as it should appear on the assertion).

Optional:

issue_date - the date when the assertion will become valid.
end_date - the date when this assertion should expire.
evidence_text - a plain text field to add evidence e.g. Recipient completed the course XYZ on ABC.
evidence_url - a URL linking to the evidence. It should be a valid URL, otherwise the badge will not be issued.
score - the score the user achieved. This is used to determine if the badge should be issued. Leave blank if the badge should be issued regardless of the score.
min_score - the minimum score required to issue the badge. If the score is lower than this, the badge will not be issued. Leave blank if the badge should be issued regardless of the score.

put/v1/badge/{badge_id}/issue

Path parameters

badge_idinteger required

Headers

X-Access-Tokenstring nullable

Request body

provider_idinteger required

qr_idstring

spydus_barcode_idstring

recipient_idinteger

recipient_firstnamestring

recipient_lastnamestring

recipient_organisationstring

recipient_emailstring

issue_datestring date-time

end_datestring date-time

evidence_textstring

evidence_urlstring

scoreinteger

min_scoreinteger

Response

Successful Response

recipient_emailstring nullable

recipient_firstnamestring nullable

recipient_lastnamestring nullable

recipient_organisationstring nullable

recipient_idinteger nullable

end_datestring date-time nullable

image_urlstring nullable

image_url_2xstring nullable

image_url_originalstring nullable

narrativestring nullable

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

external_idstring nullable

external_urlstring nullable

badge_issuer_idinteger nullable

provider_idinteger nullable

issue_datestring date-time nullable

time_verifiedstring date-time nullable

idinteger

seo_keywordsstring[] nullable

seo_titlestring nullable

seo_descriptionstring nullable

time_createdstring date-time

time_updatedstring date-time nullable

created_by_idinteger nullable

updated_by_idinteger nullable

reject_codestring nullable required

revocation_reasonstring nullable

urlstring nullable

badge_idinteger nullable

reminder_emails_sentinteger nullable

time_claimedstring date-time nullable

Example response

{
  "recipient_email": "example@user.com",
  "recipient_firstname": "Jane",
  "recipient_lastname": "Doe",
  "recipient_organisation": "XYZ Limited",
  "end_date": "2023-12-02T15:33:32.561Z",
  "image_url": "https://media.navigatr.app/image.webp",
  "image_url_2x": "https://media.navigatr.app/image_2x.webp",
  "evidence": [
    {
      "name": "Badge Completion Certificate",
      "description": "This digital certificate is awarded to users that complete the course associated with this badge",
      "genre": "Literacy",
      "value": "https://evidence.com/certificate.webp"
    }
  ],
  "issue_date": "2022-12-02T15:33:32.561Z",
  "time_verified": "2022-12-02T15:33:32.561Z",
  "recipient": {
    "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"
    ]
  },
  "provider": {
    "name": "Horace's Haberdashery Academy",
    "short_name": "HHA",
    "description": "HHA is the foremost provider of haberdashery education in the UK.",
    "community": {
      "name": "Fordwich Town Council",
      "short_name": "FTC",
      "description": "This is an example of a description of Fordwich Town Council.",
      "external_url": "https://Fordwich_Town_Council.org",
      "address": "23 Not Real Road, Fordwich, Kent, CT4 88R",
      "colour": "#844A82",
      "image_url": "https://media.navigatr.app/Fordwich.webp",
      "banner_url": "https://media.navigatr.app/Fordwich_banner.webp",
      "image_url_2x": "https://media.navigatr.app/Fordwich_2x.webp",
      "banner_url_2x": "https://media.navigatr.app/Fordwich_banner_2x.webp",
      "image_url_original": "https://media.navigatr.app/Fordwich_2x.webp",
      "banner_url_original": "https://media.navigatr.app/Fordwich_banner_2x.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",
    "brand_colours": [
      "#FFFF00"
    ],
    "url": "https://navigatr.app/provider/2922/horaces-haberdashery"
  },
  "badge": {
    "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",
    "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"
  },
  "url": "https://navigatr.app/badge/assertion/123",
  "time_claimed": "2022-12-02T15:33:32.561Z",
  "change_request": [
    {
      "changes": [
        {
          "value": "Joe"
        }
      ],
      "note": "Married last year, updating my surname"
    }
  ]
}