Developer Platform (November 2019)

Awards

«  Lockers   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Enrollments (groups, sections, auditors)  »

Contents

Awards is Brightspace’s Badging and Certification tracking tool. This provides the ability to create awards, associate them with courses or org units within Brightspace, issue them to learners who have met the set criteria and collect data regarding the awards various learners have earned.

Attributes

AWARD_T

Awards come in two types: badges and certificates. We use the term AWARD_T to stand in for an appropriate integer value:

Award object type

Value

Badge

1

Certificate

2

You can use either the type name or the value.

CLASSLIST_SORT_T

The classlist can be sorted by award count, first name, last name, or credit score; we use the term CLASSLIST_SORT_T to stand in for an appropriate string value:

Classlist sort type

Value

AwardCount

1

FirstName

2

LastName

3

CreditScore

4

You can use either the type name or the value.

EXPIRY_CALCULATION_T

Expiry can be calculated in one of several ways and you can use either the type name or the value to calculate expiry. By default the value of Never needs to be specified. We use the term EXPIRY_CALCULATION_T to stand in for an appropriate integer value:

Expiry calculation type

Value

Never

1

Fixed

2

Relative

3

RelativeDayOfMonth

4
Never

The service ignores any date/time values (Minute, Hour, Day, etc.)

Fixed

You must provide values for the following date/time values: Day, Month, and Year; you may provide a date in the past.

Relative

You must provide a value for one of Day, Week, Month, or Year. Values must be between 1 and 999 inclusive.

Relative Day of Month

You must provide values for Day and Month. Day must be between 1 and 31 inclusive. Month must be between 1 and 999 inclusive. If the Month doesn’t have Day specified, the expiry date will be the last day of the month at the time of day the award is issued.

EXPIRY_NOTIFICATION_T

Expiry notification can be calculated in one of several ways. This type is used to indicate how far ahead of the expiry date an expiry notification should be sent. We use the term EXPIRY_NOTIFICATION_T to stand in for an appropriate integer value:

Expiry notification type

Value

Days

1

Weeks

2

Months

3

Years

4

You can use either the type name or the value.

AwardDateTime

A string value that you should treat similar to an ISO 8061 formatted date-time string in the Z (UTC+0) time zone, with the exception that the value is prefixed with a U and does not contain the trailing Z.

For example, ISO 8601 "2046-05-20T13:15:30.067Z" becomes "U2046-05-20T13:15:30.067".

Associations

Awards.Association

When you use an action that retrieves award associations, the service returns a block like this:

{
    "AssociationId": <number:D2LID>,
    "OrgUnitId": <number:D2LID>,
    "ConditionSet": {
        "ConditionSetId": <number:D2LID>,
        "ConditionSetType": <number:D2LID>|null,
        "ReleaseConditions": [
            { <composite:Awards.ReleaseCondition> },
            { <composite:Awards.ReleaseCondition> }, ...
        ]
    },
    "Credit": <number:decimal>|null,
    "HiddenAward": <boolean>,
    "Award": { <composite:Awards.Award> }
}
Awards.MyAssociation

When you use an action that retrieves the award associations that a user may earn, the service returns a block like this:

{
    "AssociationId": <number:D2LID>,
    "OrgUnitId": <number:D2LID>,
    "ConditionSet": {
        "ConditionSetId": <number:D2LID>,
        "ConditionSetType": <number:D2LID>|null,
        "ReleaseConditions": [
            { <composite:Awards.ReleaseCondition> },
            { <composite:Awards.ReleaseCondition> }, ...
        ]
    },
    "Credit": <number:decimal>|null,
    "HiddenAward": <boolean>,
    "Award": { <composite:Awards.Award> },
    "Issued": <boolean>
}
Awards.AwardAssociated

When you use an action that retrieves awards that can be or have been associated with a course, the service returns a block like this:

{
    "AssociationId": <number:D2LID>|null,
    "Award": { <composite:Awards.Award> }
}
Awards.AssociationCreate

When you use an action to associate an award with an org unit, the service expects you to send a block like this:

{
    "AwardId": <number:D2LID>,
    "Credit": <number:decimal>|null,
    "HiddenAward": <boolean>
}
Credit

If credit has a value, that value must be a positive number.

Awards.AssociationUpdate

When you use an action that updates an award’s association with an org unit, the service accepts a block like this:

{
    "Credit": <number:decimal>|null,
    "HiddenAward": <boolean>
}
Credit

If credit has a value, that value must be a positive number.

Awards.ReleaseCondition
{
    "ConditionId": <number>,
    "ConditionText": <string>
}

Award

Awards.Award

When you use an action that retrieves award details, the service returns a block like this:

{
    "AwardId": <number:D2LID>,
    "CreatedBy": <number:D2LID>,
    "Title": <string>,
    "Description": <string>,
    "ExpiryCalculation": { <composite:Awards.ExpiryCalculation> },
    "ExpiryNotification": { <composite:Awards.ExpiryNotification> },
    "IssuerName": <string>,
    "IssuerUrl": <string:URL>,
    "IssuerContact": <string>,
    "AwardType": <number:AWARD_T>,
    "CertificateData": { <composite:Awards.FileData> },
    "ImageData": { <composite:Awards.FileData> },
    "IsDeleted": <boolean>
}
CertificateData

This property is always null for awards of type Badge (AwardType property has value ‘1’).

Awards.AwardCreate

When you use an action that creates an award, the service accepts a block like this:

{
    "AwardType": <number:AWARD_T>,
    "Title": <string>, //must not be null; max 128 characters
    "Description": <string>, //must not be null; max 512 characters
    "ExpiryCalculation": { <composite:Awards.ExpiryCalculation> },
    "ExpiryNotification": { <composite:Awards.ExpiryNotification> },
    "IssuerName": <string>, //must not be null; max 128 characters
    "IssuerUrl": <string:URL>, //must be a valid url; max 128 characters
    "IssuerContact": <string>, //must be a valid email address; max 128 characters
    "Certificate": { <composite:Awards.InputFileInfo> },
    "Image": { <composite:Awards.InputFileInfo> }
}
Certificate

This property can be null or can be omitted entirely for awards of type Badge (AwardType property has value ‘1’) but is required for awards of type Certificate (AwardType property has value ‘2’).

Awards.AwardUpdate

When you use an action that updates an award, the service accepts a block like this:

{
    "Title": <string>, //must not be null; max 128 characters
    "Description": <string>, //must not be null; max 512 characters
    "ExpiryCalculation": { <composite:Awards.ExpiryCalculation> },
    "ExpiryNotification": { <composite:Awards.ExpiryNotification> },
    "IssuerName": <string>, //must not be null; max 128 characters
    "IssuerUrl": <string:URL>, //must be a valid url; max 128 characters
    "IssuerContact": <string>, //must be a valid email address; max 128 characters
    "Certificate": { <composite:Awards.InputFileInfo> },
    "Image": { <composite:Awards.InputFileInfo> }
}
Certificate

This property can be null or can be omitted entirely for awards of type Badge (AwardType property has value ‘1’) but is required for awards of type Certificate (AwardType property has value ‘2’).

Awards.ExpiryCalculation
{
    "ExpiryCalculationType": <number:EXPIRY_CALCULATION_T>,
    "Minute": <number>|null,
    "Hour": <number>|null,
    "Day": <number>|null,
    "Week": <number>|null,
    "DayOfWeek": <number>|null,
    "Month": <number>|null,
    "Year": <number>|null
}
ExpiryCalculationType

You must provide this value, the default is Never (EXPIRY_CALCULATION_T).

Awards.ExpiryNotification
{
    "ExpiryNotifyValue": <number:decimal>|null,
    "ExpiryNotifyType": <number:EXPIRY_NOTIFICATION_T>|null
}
ExpiryNotifyValue

You must provide an ExpiryNotifyValue if ExpiryNotifyType has a value. The ExpiryNotifyValue must be between 1 and 999 inclusive.

Configuration

Awards.Configuration

When you use an action that requests configuration details, the service returns a block like this:

{
    "Permissions": {
        "SeeAwards": <boolean>,
        "EarnAwards": <boolean>,
        "AssociateAwards": <boolean>,
        "IssueAwards": <boolean>,
        "RevokeIssuedAwards": <boolean>,
        "ManageMyAwards": <boolean>,
        "ManageAllAwards": <boolean>,
        "SeeBadges": <boolean>,
        "AssociateBadges": <boolean>,
        "EarnBadges": <boolean>,
        "IssueBadges": <boolean>,
        "RevokeIssuedBadges": <boolean>,
        "ManageMyBadges": <boolean>,
        "ManageAllBadges": <boolean>,
        "SeeCertificates": <boolean>,
        "AssociateCertificates": <boolean>,
        "EarnCertificates": <boolean>,
        "IssueCertificates": <boolean>,
        "RevokeIssuedCertificates": <boolean>,
        "ManageMyCertificates": <boolean>,
        "ManageAllCertificates": <boolean>,
        "ManageLibraryIcons": <boolean>,
        "ManageLibraryCertificateTemplates": <boolean>,
        "DownloadOtherUsersCertificates": <boolean>
    },
    "DefaultIssuerName": <string>,
    "DefaultIssuerUrl": <string>,
    "DefaultIssuerContact": <string>,
    "D2LProfileIntegrationEnabled": <boolean>,
    "IconCreationUrl": <string>,
    "DefaultClasslistSortField": <string>,
    "DefaultClasslistSortAscending": <boolean>,
    "UserTimezone": <string>
}

IssuedAward

Awards.IssuedAward

When you use an action that retrieves an issued award, the service returns a block like this:

{
     "IssuedId": <number:D2LID>,
     "OrgUnitId": <number:D2LID>,
     "Criteria": <string>,
     "Evidence": <string>,
     "IssuedDate": <string:AwardDateTime>,
     "ExpiryDate": <string:AwardDateTime>|null,
     "IssuedByUserId": <number:D2LID>,
     "IssuedToUserId": <number:D2LID>,
     "Credit": <number:decimal>|null,
     "Share": {
         "SentToProfile": <boolean>,
         "SentToMozilla": <boolean>,
         "SentToEportfolio": <boolean>,
         "SharedObjectId": <number:D2LID>|null,
         "WithProfile": <boolean>,
         "WithMozilla": <boolean>,
         "WithEportfolio": <boolean>
     },
     "Award": { <composite:Awards.Award> }
}
SharedObjectId

The ePortfolio item the award is shared to.

IssuedByUserId

The user ID of the person who issued the award.

IssuedToUserId

The user ID of the person to issue the award to.

Share

This property contains a list of sharing types describing the sharing relationship with respect to another corresponding service endpoint. If the type name starts with “With”, this indicates that you can share the award to the corresponding service; if the type starts with “SentTo”, this indicates the back-end has already shared the award to the corresponding service.

Awards.IssuedAwardCreate

When you use an action that issues an award, the service accepts a block like this:

{
    "AwardId": <number:D2LID>,
    "IssuedToUserId": <number:D2LID>,
    "Criteria": <string>,
    "Evidence": <string>,
    "IssuedDate": <string:AwardDateTime>|null  // Added with LMS version 20.19.07
}
IssuedToUserId

The user ID of the person to issue the award to.

Criteria

May not be null or an empty string.

Evidence

May not be null or an empty string.

IssuedDate

If null is provided, the issued date will default to now.

Awards.IssuedAwardUpdate
{
    "IssuedDate": <string:UTCDateTime>,
    "ExpiryDate": <string:UTCDateTime>|null
}
Awards.UserIssuedAwardSummary

When you use an action that retrieves the summary of awards issued to a user, the service returns a block like this:

{
     "UserId": <number:D2LID>,
     "OrgUnitId": <number:D2LID>,
     "ProfileImage": <string:URL>,
     "DisplayName": <string>,
     "FirstName": <string>,
     "LastName": <string>,
     "TotalAwardCount": <number>,
     "TotalCreditCount": <number:decimal>,
     "Rank": <number>,
     "IssuedAwards": { <composite:Api.ObjectListPage<Awards.IssuedAward>> }
}
IssuedAwards

This property is an ObjectListPage containing a list of Issued Awards.

Credits

Awards.CreditSummary

When you use an action that returns the credit summary by Award Type, the service returns a block like this:

{
    "BadgeCreditSummary": <number:decimal>|null,
    "CertificateCreditSummary": <number:decimal>|null
}

Library

Awards.FileData

When you use an action that returns file data, the service returns a block like this:

{
    "Name": <string>,
    "Path": <string>
}
Awards.LibraryInputFileInfo

When you use an action that sets file data as part of interacting with the icon or certificate template libraries, the service accepts a block like this:

{
    "Name": <string>,
    "Content": <string>
}
Name

Name of file, including file extension.

Content

Base64-encoded file data.

Awards.InputFileInfo

When you use an action that sets file data as part of a create or update award action, the service accepts a block like this:

{
    "LibraryFileName": <string>,
    "FilePath": <string>,
    "Name": <string>,
    "Content": <string>
}
LibraryFileName

The name of a file that exists in the library, including file extension.

FilePath

Path to the file (same value as the Path property in a FileData block).

Name

Name of file, including file extension.

Content

Base64-encoded file data.

You must provide a LibraryFileName, FilePath, or both Name and Content. When creating an icon/certificate, the service will first try to create a new file based on the Name and Content. If Name and Content are null or have been omitted, the LibraryFileName will be used next. Finally the FilePath will be used for the icon/template.

Actions

Included in the details for each route is a list of permissions. The user making the call must have the specified permissions or the route will return Forbidden. For all routes that don’t include org unit context, the permissions will be checked against every role the user has across the organization to determine if the user has permission for that action.

Awards API routes return a 201 Created status when anything is created. When trying to create something that already exists, 409 Conflict is returned.

Associations

Associations are created to associate an award with an org unit. An award can have associations with multiple org units.

DELETE /d2l/api/bas/(version)/orgunits/(orgUnitId)/associations/(associationId)

Delete an award’s association with an org unit.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org Unit ID.

  • associationId (D2LID) – Award Association ID.

Permissions

See Badges, Associate Badges or See Certificates, Associate Certificates (depending on award type)

Status Codes

  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to view or manage associations.

  • 404 Not Found – Association not found for the provided org unit.

API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

GET /d2l/api/bas/(version)/orgunits/(orgUnitId)/associations/

Retrieve an org unit’s associations.

Parameters
Query Parameters

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • limit (number) – Optional. Number of records to return between 1 and 200 (default is 100).

  • offset (number) – Optional. Number of records to skip, defaults to 0.

  • search (string) – Optional. Filter results to those with matches between search string and org unit’s name, or associated award’s title or description.

Permissions

See Badges or See Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an ObjectListPage JSON block containing a list of Associations.

GET /d2l/api/bas/(version)/orgunits/(orgUnitId)/associations/(associationId)

Retrieve an association.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org Unit ID.

  • associationId (D2LID) – Award Association ID.

Permissions

See Badges or See Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an Association JSON block.

GET /d2l/api/bas/(version)/associations/availableToEarn/

Retrieve associated awards that the calling user may earn and has already earned.

Parameters
Query Parameters

  • orgUnitId (D2LID) – Optional. Filter by Org Unit ID, defaults to all.

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • limit (number) – Optional. Number of records to return between 1 and 200 (default is 100).

  • offset (number) – Optional. Number of records to skip, defaults to 0.

  • search (string) – Optional. Filter results to those with matches between search string and org unit’s name, or associated award’s title or description.

Permissions

See Badges, Earn Badges or See Certificates, Earn Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an ObjectListPage JSON block containing a list of MyAssociations.

GET /d2l/api/bas/(version)/orgunits/(orgUnitId)/associations/availableToManage/

Retrieve awards that have been, or could be, associated with an org unit.

Parameters
Query Parameters

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • limit (number) – Optional. Number of records to return between 1 and 200 (default is 100).

  • offset (number) – Optional. Number of records to skip, defaults to 0.

  • search (string) – Optional. Filter results to those with matches between search string and org unit’s name, or associated award’s title or description.

  • showMine (boolean) – Optional. If present and true, retrieve only associations to awards created by the calling user; otherwise, ignore award creator’s identity (default).

Permissions

See Badges, Associate Badges or See Certificates, Associate Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an ObjectListPage JSON block containing a list of AwardAssociations.

POST /d2l/api/bas/(version)/orgunits/(orgUnitId)/associations/

Associate an award with an org unit.

Parameters
JSON Parameters
Permissions

See Badges, Associate Badges or See Certificates, Associate Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an Association JSON block.

PUT /d2l/api/bas/(version)/orgunits/(orgUnitId)/associations/(associationId)

Update an award association.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org Unit ID.

  • associationId (D2LID) – Award Association ID.

JSON Parameters
Permissions

See Badges, Associate Badges or See Certificates, Associate Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an Association JSON block.

Award

DELETE /d2l/api/bas/(version)/awards/(awardId)

Delete an award.

Parameters
Permissions

See Badges, Manage Own Badges or Manage Badges, or See Certificates, Manage Certificates or Manage Own Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

GET /d2l/api/bas/(version)/awards/

Retrieve awards available across the organization.

Parameters
Query Parameters

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • limit (number) – Optional. Number of records to return between 1 and 200 (defaults to 100).

  • offset (number) – Optional. Number of records to skip, defaults to 0.

  • search (string) – Optional. Filter results to those with matches between search string and org unit’s name, or award’s title or description.

Permissions

See Badges or See Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an ObjectListPage JSON block containing a list of Award JSON blocks. Note that this action returns all awards, including the awards currently in a deleted state (awards whose IsDeleted property is true).

GET /d2l/api/bas/(version)/awards/(awardId)

Retrieve a particular award.

Parameters
Permissions

See Badges or See Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an Award JSON block.

POST /d2l/api/bas/(version)/awards/

Create a new award.

Parameters
JSON Parameters
Permissions

See Badges, Manage Own Badges or Manage Badges, or See Certificates, Manage Certificates or Manage Own Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an Award JSON block.

PUT /d2l/api/bas/(version)/awards/(awardId)

Update an award.

Parameters
JSON Parameters
Permissions

See Badges, Manage Own Badges or Manage Badges, or See Certificates, Manage Certificates or Manage Own Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an Award JSON block.

Classlist

GET /d2l/api/bas/(version)/orgunits/(orgUnitId)/classlist/

Retrieve the users in the classlist who are able to earn awards along with their first ten awards.

Parameters
Query Parameters

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • limit (number) – Optional. Limits the number of users returned between 1 and 200 (defaults to 100).

  • offset (number) – Optional. Number of records to skip, defaults to 0.

  • search (string) – Optional. Filter results to those with matches between search string and a user’s first or last name containing this value.

  • includeExpired (boolean) – Optional. If present and true, include expired awards in the results.

  • sectionId (D2LID) – Optional. Filters the results based on a section from the provided the org unit.

  • sortField (CLASSLIST_SORT_T) – Optional. Order the users by a given field, defaults to config value (d2l.Tools.Awards.DefaultClasslistSortField).

  • sortFieldIsAscending (boolean) – Optional. If present and true, the users are listed in ascending order, defaults to config value (d2l.Tools.Awards.ClasslistSortAscending).

  • fetchLatest (boolean) – Optional. If present and true, retrieves the classlist users latest ten awards, instead of their first ten.

Permissions

See Badges or See Certificates

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Input. The users are sorted based on the sortField and sortFieldIsAscending parameters. The sorting of ascending or decending is done based on the sort field followed by last name then first name if the given sort field isn’t enough to determine ordering. When using FirstName or LastName as the sort field, the user’s rank is determined by AwardCount.

Return. This action returns an ObjectListPage JSON block containing a list of the User's Issued Awards values. Only awards of types (AWARD_T) that the calling user can view are returned.

GET /d2l/api/bas/(version)/orgunits/(orgUnitId)/classlist/users/(userId)

Retrieve the ten oldest awards for a classlist user.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org Unit ID.

  • userId (D2LID) – User ID.

Query Parameters

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • sortField (CLASSLIST_SORT_T) – Optional. Ranks the user by a given field, defaults to config value (d2l.Tools.Awards.DefaultClasslistSortField).

Permissions

See Badges or See Certificates

Status Codes

  • 200 OK – Action succeeded.

  • 400 Bad Request – Invalid filters.

  • 403 Forbidden – Attempted to get an Award of a type (AWARD_T) the requesting user is not allowed to see or retrieve a user who can’t earn awards.

  • 404 Not Found – Attempted to use an invalid org unit, the user is not in the class list, or the user can’t earn awards.

API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Input. When using FirstName or LastName as the sort field, the user’s rank is determined by AwardCount.

Return. This action returns a JSON block containing the User Issued Award Summary.

Configuration

GET /d2l/api/bas/(version)/orgunits/(orgUnitId)/myConfiguration

Retrieve the user’s current configuration.

Parameters
Permissions

See Badges or See Certificates

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns a JSON block containing the user’s configuration.

Issued Award

DELETE /d2l/api/bas/(version)/issued/(issuedId)

Revoke an issued award.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org Unit ID.

  • issuedId (D2LID) – Issued ID.

Permissions

See Badges, Revoke Badges or See Certificates, Revoke Certificates (depending on award type)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

GET /d2l/api/bas/(version)/creditSummary

Retrieve the credit summary for the calling user’s issued awards.

Parameters
Query Parameters

  • orgUnitId (D2LID) – Optional. Filter by Org Unit ID, defaults to all.

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • includeExpired (boolean) – Optional. If present and true, include expired awards in the results.

  • search (string) – Optional. Filter results to those with matches between search string and org unit’s name, or issued award’s title or description.

Permissions

See Badges (Organization) or See Certificates (Organization) or See Badges or See Certificates

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns a JSON block containing the User's Credit Summary.

GET /d2l/api/bas/(version)/issued/users/(userId)/

Retrieve the awards issued to a user.

Parameters
Query Parameters

  • orgUnitId (D2LID) – Optional. Filter by the org unit.

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • limit (number) – Optional. Number of records to return between 1 and 200 (defaults to 100).

  • offset (number) – Optional. Number of records to skip, defaults to 0.

  • includeExpired (boolean) – Optional. If present and true, include expired awards in the results.

  • search (string) – Optional. Filter results to those with matches between search string and org unit’s name, or issued award’s title or description.

Permissions

See Badges (Organization) or See Certificates (Organization)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Input. If both userId and orgUnitId are provided, the user must be enrolled in the provided org unit.

Return. This action returns an ObjectListPage JSON block containing a list of Issued Awards.

GET /d2l/api/bas/(version)/orgunits/(orgUnitId)/revocableawards/

Retrieve the awards for a user that the calling user can revoke.

Parameters
Query Parameters

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • limit (number) – Optional. Number of records to return between 1 and 200 (defaults to 100).

  • offset (number) – Optional. Number of records to skip, defaults to 0.

  • search (string) – Optional. Filter results to those with matches between search string and org unit’s name, or issued award’s title or description.

Permissions

See Badges, Revoke Badges or See Certificates, Revoke Certificates

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an ObjectListPage JSON block containing a list of Awards.

GET /d2l/api/bas/(version)/orgunits/(orgUnitId)/revocableawards/(userId)/

Retrieve the issued awards for a specified user that can be revoked by the calling user.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org Unit ID.

  • userId (D2LID) – User ID.

Query Parameters

  • awardType (AWARD_T) – Optional. Filter by award type, defaults to all.

  • includeExpired (boolean) – Optional. If present and true, include expired awards in the results.

  • search (string) – Optional. Filters results based on an issued award’s title or description, defaults to empty.

Permissions

See Badges, Revoke Badges or See Certificates, Revoke Certificates

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns a JSON block containing a list of Issued Awards.

POST /d2l/api/bas/(version)/orgunits/(orgUnitId)/issued/

Issue an award.

Parameters
JSON Parameters
Permissions

See Badges, Issue Badges or See Certificates, Issue Certificates

Status Codes

  • 201 Created – Action succeeded.

  • 400 Bad Request – Attempted to issue an award that is not associated with the org unit, the award has already been issued to the target user, or the target user is not enrolled in the org unit.

  • 403 Forbidden – No permission to issue awards, the user can’t earn the award type, or you tried to issue an award to yourself.

  • 404 Not Found – Attempted to issue an award that does not exist.

API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns a JSON block containing the Issued Award.

PUT /d2l/api/bas/(version)/orgunits/(orgUnitId)/issued/(issuedId)

Update an issued award.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org Unit ID.

  • issuedId (D2LID) – Issued award ID.

JSON Parameters
Permissions

See Badges, Issue Badges or See Certificates, Issue Certificates

Status Codes

  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to issue awards.

  • 404 Not Found – Attempted to update an award that does not exist in the org unit.

  • 410 Gone – Attempted to update a revoked award.

API Versions

  • 1.1 – Route first appears in LMS v20.19.08.

Return. This action returns a JSON block containing the Issued Award.

Library

DELETE /d2l/api/bas/(version)/library/icons/(fileName)

Delete named icon from library.

Parameters

  • version (D2LVERSION) – API version.

  • fileName (string) – File name including file extension.

Permissions

Manage Icon Library

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

DELETE /d2l/api/bas/(version)/library/templates/(fileName)

Delete named certificate template from library.

Parameters

  • version (D2LVERSION) – API version.

  • fileName (string) – File name including file extension.

Status Codes
Permissions

Manage Certificate Templates

API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

GET /d2l/api/bas/(version)/library/icons/

Retrieve the icons contained in the library.

Parameters
Query Parameters

  • limit (number) – Optional. Number of records to return between 1 and 200 (defaults to 100).

  • offset (number) – Optional. Number of records to skip, defaults to 0.

  • search (string) – Optional. Filter results to those with matches between search string and icon’s file name.

Permissions

See Certificates (Organization), Manage Own Certificates (Organization) or Manage Certificates (Organization), or Manage Certificate Templates (Organization), or See Badgess (Organization), Manage Own Badgess (Organization) or Manage Badges (Organization), or Manage Icon Library (Organization)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an ObjectListPage JSON block containing a list of file data.

GET /d2l/api/bas/(version)/library/icons/(fileName)

Retrieve named icon from the library.

Parameters

  • version (D2LVERSION) – API version.

  • fileName (string) – File name including file extension.

Permissions

See Certificates (Organization), Manage Own Certificates (Organization) or Manage Certificates (Organization), or Manage Certificate Templates (Organization), or See Badgess (Organization), Manage Own Badgess (Organization) or Manage Badges (Organization), or Manage Icon Library (Organization)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns the icon file.

GET /d2l/api/bas/(version)/library/templates/

Retrieve the certificate templates contained in the library.

Parameters
Query Parameters

  • limit (number) – Optional. Number of records to return between 1 and 200 (defaults to 100).

  • offset (number) – Optional. Number of records to skip, defaults to 0.

  • search (string) – Optional. Filter results to those with matches between search string and certificate template’s file name.

Permissions

See Certificates (Organization), Manage Own Certificates (Organization) or Manage Certificates (Organization), or Manage Certificate Templates (Organization)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns an ObjectListPage JSON block containing a list of file data.

GET /d2l/api/bas/(version)/library/templates/(fileName)

Retrieve named certificate template from the library.

Parameters

  • version (D2LVERSION) – API version.

  • fileName (string) – File name including file extension.

Permissions

See Certificates (Organization), Manage Own Certificates (Organization) or Manage Certificates (Organization), or Manage Certificate Templates (Organization)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns the pdf file.

POST /d2l/api/bas/(version)/library/icons/

Add an icon to the library.

Parameters
JSON Parameters
Permissions

Manage Icon Library (Organization)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns a JSON block containing a file data.

POST /d2l/api/bas/(version)/library/templates/

Add a certificate template to the library.

Parameters
JSON Parameters
Permissions

Manage Certificate Templates (Organization)

Status Codes
API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

Return. This action returns a JSON block containing a file data.

Profile

DELETE /d2l/api/bas/(version)/issued/(issuedId)/sharing/profile

Remove an issued award from the calling user’s profile.

Parameters

  • version (D2LVERSION) – API version.

  • issuedId (D2LID) – ID of the issued award to be removed.

Permissions

Manage Own Profile (Organization), See Badges or See Certificates (depending on award type)

Status Codes

  • 200 OK – Action succeeded.

  • 400 Bad Request – Issued award does not belong to the calling user, the award is not shared, or the award has been revoked.

  • 403 Forbidden – Profile integration is not enabled or no permission to view award.

  • 404 Not Found – No issued award found matching the provided id.

API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

PUT /d2l/api/bas/(version)/issued/(issuedId)/sharing/profile

Share an issued award on the calling user’s profile.

Parameters

  • version (D2LVERSION) – API version.

  • issuedId (D2LID) – Issued ID to be shared.

Permissions

Manage Own Profile (Organization) and See Badges or See Certificates (depending on award type)

Status Codes

  • 201 Created – Action succeeded.

  • 400 Bad Request – Issued award does not belong to the calling user, the award has already been shared, or the issued award has been revoked.

  • 403 Forbidden – Profile integration is not enabled or no permission to view award.

  • 404 Not Found – No issued award found matching the provided id.

API Versions

  • 1.0 – Route first appears in LMS v10.6.7.

«  Lockers   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Enrollments (groups, sections, auditors)  »