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 ofIssued 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.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
-
GET
/d2l/api/bas/
(version)/orgunits/
(orgUnitId)/associations/
¶ Retrieve an org unit’s associations.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org Unit ID.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid filters.
403 Forbidden – No permission to view associations.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
Return. This action returns an
ObjectListPage
JSON block containing a list ofAssociations
.
-
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
200 OK – Action succeeded.
403 Forbidden – No permission to view an association.
404 Not Found – Association not found for the provided org unit.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid filters.
403 Forbidden – No permission to view earnable awards.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
Return. This action returns an
ObjectListPage
JSON block containing a list ofMyAssociations
.
-
GET
/d2l/api/bas/
(version)/orgunits/
(orgUnitId)/associations/availableToManage/
¶ Retrieve awards that have been, or could be, associated with an org unit.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org Unit ID.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid filters.
403 Forbidden – No permission to view or manage associations with an org unit.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
Return. This action returns an
ObjectListPage
JSON block containing a list ofAwardAssociations
.
-
POST
/d2l/api/bas/
(version)/orgunits/
(orgUnitId)/associations/
¶ Associate an award with an org unit.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org Unit ID.
- JSON Parameters
AssociationCreate (
Awards.AssociationCreate
) – Data for new association.
- Permissions
See Badges, Associate Badges or See Certificates, Associate Certificates (depending on award type)
- Status Codes
201 Created – Action succeeded.
400 Bad Request – Association between this award and org unit already exists, or invalid
Awards.AssociationCreate
details.403 Forbidden – No permission to view or associate awards.
404 Not Found – No such award.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
AssociationUpdate (
Awards.AssociationUpdate
) – Updated data for association.
- Permissions
See Badges, Associate Badges or See Certificates, Associate Certificates (depending on award type)
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Invalid
Awards.AssociationUpdate
details.403 Forbidden – No permission to view or update award associations with an org unit.
404 Not Found – No such association.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
awardId (D2LID) – Award ID.
- Permissions
See Badges, Manage Own Badges or Manage Badges, or See Certificates, Manage Certificates or Manage Own Certificates (depending on award type)
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view or manage awards.
404 Not Found – No such award, or award already deleted.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
-
GET
/d2l/api/bas/
(version)/awards/
¶ Retrieve awards available across the organization.
- Parameters
version (D2LVERSION) – API version.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid filters
403 Forbidden – No permission to view awards.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
Return. This action returns an
ObjectListPage
JSON block containing a list ofAward
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
version (D2LVERSION) – API version.
awardId (D2LID) – Award ID.
- Permissions
See Badges or See Certificates (depending on award type)
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view an award.
404 Not Found – No such award.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
- JSON Parameters
AwardCreate (
Awards.AwardCreate
) – Data for new award.
- Permissions
See Badges, Manage Own Badges or Manage Badges, or See Certificates, Manage Certificates or Manage Own Certificates (depending on award type)
- Status Codes
201 Created – Action succeeded.
400 Bad Request – Invalid
Awards.AwardCreate
details403 Forbidden – No permission to view or manage awards.
404 Not Found – Award refers to an image or certificate template path that can’t be found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
awardId (D2LID) – Award ID.
- JSON Parameters
AwardUpdate (
Awards.AwardUpdate
) – Updated data for award.
- Permissions
See Badges, Manage Own Badges or Manage Badges, or See Certificates, Manage Certificates or Manage Own Certificates (depending on award type)
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Invalid
Awards.AwardUpdate
details403 Forbidden – No permission to view or manage awards.
404 Not Found – No such award, or award properties contain an image or certificate template path that can’t be found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org Unit ID.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid filters.
403 Forbidden – No permission to view awards.
404 Not Found – No such org unit
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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 theUser'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.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org Unit ID.
- Permissions
See Badges or See Certificates
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view configuration.
404 Not Found – No such org unit.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
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
200 OK – Action succeeded.
400 Bad Request – Attempted to revoke an issued award that is already revoked.
403 Forbidden – No permission to revoke award.
404 Not Found – No such issued award.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid Award type (AWARD_T) was provided.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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/users/
(userId)/
¶ Retrieve the awards issued to a user.
- Parameters
version (D2LVERSION) – API version.
userId (D2LID) – User ID.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid filters.
403 Forbidden – No permission to view awards.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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 ofIssued Awards
.
-
GET
/d2l/api/bas/
(version)/orgunits/
(orgUnitId)/revocableawards/
¶ Retrieve the awards for a user that the calling user can revoke.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org Unit ID.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid filters.
403 Forbidden – No permission to view revocable awards.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
Return. This action returns an
ObjectListPage
JSON block containing a list ofAwards
.
-
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
200 OK – Action succeeded.
400 Bad Request – Invalid filters.
403 Forbidden – No permission to view revocable awards.
404 Not Found – No such user enrolled in org unit.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org Unit ID.
- JSON Parameters
IssuedAwardCreate (
Awards.IssuedAwardCreate
) – Data for the award to issue.
- 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.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
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
IssuedAwardUpdate (
Awards.IssuedAwardUpdate
) – Data for the award to update.
- 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.
429 Too Many Requests – API call-rate limit exceeded.
- 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
200 OK – Action succeeded.
400 Bad Request – Service unable to delete the file.
403 Forbidden – No permission to manage icons.
404 Not Found – No such icon.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
200 OK – Action succeeded.
400 Bad Request – Service unable to delete the file.
403 Forbidden – No permission to manage certificate templates.
404 Not Found – No such certificate template.
429 Too Many Requests – API call-rate limit exceeded.
- Permissions
Manage Certificate Templates
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
-
GET
/d2l/api/bas/
(version)/library/icons/
¶ Retrieve the icons contained in the library.
- Parameters
version (D2LVERSION) – API version.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid filters.
403 Forbidden – No permission to view icons.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
Return. This action returns an
ObjectListPage
JSON block containing a list offile 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
200 OK – Action succeeded.
403 Forbidden – No permission to view icon.
404 Not Found – No such icon.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
- 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
200 OK – Action succeeded.
400 Bad Request – Invalid filters.
403 Forbidden – No permission to view certificate templates.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.
Return. This action returns an
ObjectListPage
JSON block containing a list offile 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
200 OK – Action succeeded.
403 Forbidden – No permission to view certificate template.
404 Not Found – No such certificate template.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
- JSON Parameters
LibraryInputFileInfo (
Awards.LibraryInputFileInfo
) – Data for the new icon.
- Permissions
Manage Icon Library (Organization)
- Status Codes
201 Created – Action succeeded.
400 Bad Request – Invalid data provided.
403 Forbidden – No permission to manage the icon library.
409 Conflict – Attempted to upload an icon with a file name that already exists.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
version (D2LVERSION) – API version.
- JSON Parameters
LibraryInputFileInfo (
Awards.LibraryInputFileInfo
) – Data for the new certificate template.
- Permissions
Manage Certificate Templates (Organization)
- Status Codes
201 Created – Action succeeded.
400 Bad Request – Invalid data provided.
403 Forbidden – No permission to manage certificate templates.
409 Conflict – Attempted to upload a certificate template with a file name that already exists
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
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.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
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
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.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.1 – Route first appears in LMS v20.19.7.
1.0 – Obsolete as of LMS v20.21.1.