Developer Platform (December 2024)

Awards

«  Lockers   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Enrollments  »

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 8601 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>,
    "Criteria": <string>|null  // Added with BAS API v1.2
}
Criteria

This property can be set/updated, and retrieved, with version 1.2 of the API. It is not changeable, or visible, with earlier versions of the API.

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> },
    "Criteria": <string>|null  // Added with BAS API v1.2
}
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’).

Criteria

This property can be set/updated, and retrieved, with version 1.2 of the API. It is not changeable, or visible, with earlier versions of the API.

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> },
    "Criteria": <string>|null  // Added with BAS API v1.2, optional
}
Criteria

This property can be set/updated, and retrieved, with version 1.2 of the API. It is not changeable, or visible, with earlier versions of the API. Note that once set, this property cannot be unset. Omissions or null values will be ignored.

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> },
     "CertificateId": <string>|null  // Added as of LMS v20.24.4
}
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.

CertificateId

With LMS v20.24.4 or later, for issued awards of type certificate, this field contains the certificate Id of the certificate. Otherwise, this field’s value will be null. The certificate identifier is unique within the back-end 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:UTCDateTime>|null
}
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:
API Versions:

  • 1.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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 (Organization) or See Certificates (Organization) (depending on award type).

Status Codes:
API Versions:

  • 1.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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:
API Versions:

  • 1.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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:
Permissions:

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

Status Codes:
API Versions:

  • 1.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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

GET /d2l/api/bas/(version)/issued/certificates/(certificateId)

Retrieve an Issued Award of type Certificate based on the Certificate Id.

Parameters:

  • version (D2LVERSION) – API version.

  • certificateId (string) – Certificate identifier.

Permissions:

See Certificate and Download Other Users Certificates or be the certificate’s owner.

Oauth2 Scopes:

awards:certificate:read

Status Codes:
API Versions:

  • 1.3+ – Route first appears in LMS v20.24.4.

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

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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

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

Issue an award to a user.

Parameters:
JSON Parameters:
Query Parameters:

  • useIssueDateToCalcExpiry (boolean) – Optional (false by default). If present and true, use issue date to calculate expiry date; otherwise, use action invocation date for calculation.

Permissions:

See Badges, Issue Badges or See Certificates, Issue Certificates.

Status Codes:
API Versions:

  • 1.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

Input. Note that with version 1.0 of this action, the back-end service ignores any value you provide for the IssuedDate in the provided JSON and will set the issued date to the UTC date-time value of “now”. With version 1.1 of this action, the back-end service uses the optional useIssueDateToCalcExpiry query parameter to determine what to do: if you provide this query parameter and set it to true, the back-end service will use the IssuedDate in your provided JSON to calculate the award’s expiry date; otherwise, the back-end service will use the date-time value of “now”.

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:
API Versions:

  • 1.2+ – Route first appears in LMS v20.19.7.

  • 1.1 – Deprecated as of 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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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:
API Versions:

  • 1.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

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:
API Versions:

  • 1.2+ – Route first appears in LMS v20.23.7.

  • 1.1 – Deprecated as of LMS v20.24.1.

  • 1.0 – Obsolete as of LMS v20.21.1.

«  Lockers   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Enrollments  »