Developer Platform (April 2024)

Grades (grade objects, categories, values, schemes)

«  Groups   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Course content (content objects, tables of content)  »

Attributes

GRADEOBJ_T

Grade objects support several different means of assessment. We organize these into a list of grade object types and use the term GRADEOBJ_T to stand in for an appropriate integer value.

Grade object type

Value

Numeric

1

PassFail

2

SelectBox

3

Text

4

Calculated

5 ^

Formula

6 ^

FinalCalculated

7 ^

FinalAdjusted

8 ^

Category

9 ^

^ Direct creation of these types through these APIs is not supported.

GRADINGSYSTEM_T

Each org unit is configured with a grading system that is used by all grade objects in the org unit. These string labels identify the various grading systems:

Grading system

Final grade calculation

Points

Sum of the points from each grade object.

Weighted

Weighted sum of the points from each grade object.

Formula

Determined by custom formula.

Points and Weighted

The points method simply sums up the raw points of each grade object (for example, test one worth 10 points and test two worth 15 points produces a sum of 15 points towards the final grade).

The weighted method treats each grade object as a percentage of the final grade (so, test one could comprise 30% of the final grade, and test two could comprise 15% of the final grade: together, they account for 45% of the final grade).

Formula

The calculation of the final grade gets done according to a custom formula, and all the grade items and categories use the Points method within this formula.

Grade.GradeObject

A grade object describes a single point of assessment for an org unit, containing the parameters within which participants will get assessed. The framework supports the creation of four different types of GradeObjects, each with slightly different properties.

Providing grade object data blocks. The following blocks demonstrate what the framework API returns to callers. When you must provide grade object data blocks into the framework API, abide by these restrictions:

  • Do not provide an Id field.

  • The CategoryId field should contain a valid category ID value for an existing grade category, or a value of 0.

  • The Description field should use the RichTextInput field type, and not the RichText type sent back on output by the service.

  • The GradeScheme field for numeric or pass-fail grade objects should match an existing grade scheme ID for the org unit, but can be null if the grade object has no associated scheme.

    The GradeScheme field for select-box grade objects must have an associated scheme ID; it cannot be null for select-box grade objects.

  • The MaxPoints field (for grade objects that have one) must have a value that ranges between 0.01 and 9999999999.

  • The Name field must not be the same as any current grade object in the org unit’s gradebook.

    The Name field may not contain any of these characters: / “ * < > + = | , %

    Both the Name and ShortName field must be 128 unicode characters or fewer in length.

Default Category ID values. When the service provides you with a grade object block, it may provide you with a CategoryId value of 0 if the grade object has no associated grade category, instead of providing you with null – you should be able to cope with receiving both values, and recognize that in either case, the grade object has no associated category (do not attmept to fetch a grade category with a category ID of 0, as one won’t be findable: this is also true of the call to retrieve all grade categories).

IsHidden default value. If not provided with input actions, this field will default to a value of False.

Numeric. Numeric grade objects look like this:

{
    "MaxPoints": <number:decimal>,
    "CanExceedMaxPoints": <boolean>,
    "IsBonus": <boolean>,
    "ExcludeFromFinalGradeCalculation": <boolean>,
    "GradeSchemeId": <number:D2LID>|null,
    "Id": <number:D2LID>,  // Not on input actions
    "Name": <string>,
    "ShortName": <string>,
    "GradeType": "Numeric",
    "CategoryId": <number:D2LID>|null,
    "Description": { <composite:RichText> },  // { <composite:RichTextInput> } on input actions
    "GradeSchemeUrl": <string:APIURL>,  // Not on input actions
    "Weight": <number:decimal>,  // Not on input actions
    "AssociatedTool": { <composite:AssociatedTool> }|null,
    "IsHidden": <bool>
}
GradeSchemeUrl

Contains the URL for an API action to retrieve the grade scheme associated with the grade object. Retrieving this URL will return a GradeScheme object.

AssociatedTool

Describes the tool object associated with this grade object.

PassFail. Pass-fail grade objects look like this:

{
    "MaxPoints": <number:decimal>,
    "IsBonus": <boolean>,
    "ExcludeFromFinalGradeCalculation": <boolean>,
    "GradeSchemeId": <number:D2LID>|null,
    "Id": <number:D2LID>,  // Not on input actions
    "Name": <string>,
    "ShortName": <string>,
    "GradeType": "PassFail",
    "CategoryId": <number:D2LID>|null,
    "Description": { <composite:RichText> },  // { <composite:RichTextInput> } on input actions
    "Weight": <number:decimal>,  // Not on input actions
    "GradeSchemeUrl": <string:APIURL>,  // Not on input actions
    "AssociatedTool": { <composite:AssociatedTool> }|null,
    "IsHidden": <bool>
}
GradeSchemeUrl

Contains the URL for an API action to retrieve the grade scheme associated with the grade object. Retrieving this URL will return a GradeScheme object.

AssociatedTool

Describes the tool object associated with this grade object.

SelectBox. Select-box grade objects look like this:

{
    "MaxPoints": <number:decimal>,
    "IsBonus": <boolean>,
    "ExcludeFromFinalGradeCalculation": <boolean>,
    "GradeSchemeId": <number:D2LID>,  // Cannot be null on input actions
    "Id": <number:D2LID>,  // Not on input actions
    "Name": <string>,
    "ShortName": <string>,
    "GradeType": "SelectBox",
    "CategoryId": <number:D2LID>|null,
    "Description": { <composite:RichText> },  // { <composite:RichTextInput> } on input actions
    "Weight": <number:decimal>,  // Not on input actions
    "GradeSchemeUrl": <string:APIURL>,  // Not on input actions
    "AssociatedTool": { <composite:AssociatedTool> }|null,
    "IsHidden": <bool>
}
GradeSchemeUrl

Contains the URL for an API action to retrieve the grade scheme associated with the grade object. Retrieving this URL will return a GradeScheme object.

AssociatedTool

Describes the tool object associated with this grade object.

Text. Text grade objects look like this:

{
    "Id": <number:D2LID>,  // Not on input actions
    "Name": <string>,
    "ShortName": <string>,
    "GradeType": "Text",
    "CategoryId": <number:D2LID>|null,
    "Description": { <composite:RichText> },  // { <composite:RichTextInput> } on input actions
    "Weight": <number:decimal>,  // Not on input actions
    "AssociatedTool": { <composite:AssociatedTool> }|null,
    "IsHidden": <bool>
}
AssociatedTool

Describes the tool object associated with this grade object.

Grade.AssociatedTool

Included in grade objects to indicate the underlying tool and tool item associated with the grade object.

{
    "ToolId": <number:D2LID>,
    "ToolItemId": <number:D2LID>
}

Grade categories

Grade.GradeObjectCategory

This data block contains a GradeObjectCategoryData block while adding an Id field and a Grades array field:

{
    "Id": <number:D2LID>,
    "Grades": [ <Grade.GradeObject>, ... ],
    "Name": <string>,
    "ShortName": <string>,
    "CanExceedMax": <boolean>,
    "ExcludeFromFinalGrade": <boolean>,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "Weight": <number:decimal>|null,
    "MaxPoints": <number:decimal>|null,
    "AutoPoints": <boolean>|null,
    "WeightDistributionType": <number>|null,
    "NumberOfHighestToDrop": <number>|null,
    "NumberOfLowestToDrop": <number>|null
}
Grade.GradeObjectCategoryData

This data block contains all the fundamental values for a generic grade object category.

{
    "Name": <string>,
    "ShortName": <string>,
    "CanExceedMax": <boolean>,
    "ExcludeFromFinalGrade": <boolean>,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "Weight": <number:decimal>|null,
    "MaxPoints": <number:decimal>|null,
    "AutoPoints": <boolean>|null,
    "WeightDistributionType": <number>|null,
    "NumberOfHighestToDrop": <number>|null,
    "NumberOfLowestToDrop": <number>|null
}

Grade schemes

Grade.GradeScheme
{
    "Id": <number:D2LID>,
    "Name": <string>,
    "ShortName": <string>,
    "Ranges": [ // Array of GradeSchemeRange blocks
        {
            "PercentStart": <number:decimal>,
            "Symbol": <string>,
            "AssignedValue": <number:decimal>|null,
            "Colour": <string>
        },
        { <composite:GradeSchemeRange> }, ...
    ]
}

Grade values

Grade.GradeValue

The framework can provide grade values slightly differently depending upon whether the underlying grade object type is a computable value, or not (basically, only Text (4) grade types are not computable).

Basic. All grade values will share at least these properties:

{
    "UserId": <string:D2LID>,  // Available in LE unstable API contract
    "OrgUnitId": <string:D2LID>,  // Available in LE unstable API contract
    "DisplayedGrade": <string>,
    "GradeObjectIdentifier": <string:D2LID>,
    "GradeObjectName": <string>,
    "GradeObjectType": <number:GRADEOBJ_T>,
    "GradeObjectTypeName": <string>|null,
    "Comments": { <composite:RichText> },
    "PrivateComments": { <composite:RichText> },
    "LastModified": <string:UTCDateTime>|null,
    "LastModifiedBy": <string:D2LID>|null,
    "ReleasedDate": <string:UTCDateTime>|null
}
ReleaseDate

If your grade value block is a final grade that has been released and you have the appropriate permissions, it will return the value. Otherwise, it will return null.

Computable. Computable grade values can have additional properties; computable value structures have all the basic properties, and also add these:

{
    "PointsNumerator": <number>|null,
    "PointsDenominator": <number>|null,
    "WeightedDenominator": <number>|null,
    "WeightedNumerator": <number>|null
}

Note

Nullable grade values for these fields in the computable grade value structures indicate (when null) a default grade value state before a grade value has actually been assessed.

Grade.UserGradeValue

Contains a User and a GradeValue.

{
   "User": { <composite:User> },
   "GradeValue": { <composite:GradeValue> }|null
}
GradeValue

If the user currently has no grade value set, this will be null.

Grade.IncomingGradeValue

As with grade objects, the framework handles incoming grade values slightly differently depending upon the grade object type associated with the grade value (these APIs support incoming grade values for the first four grade object types).

Basic. All incoming grade value structures share at least these common properties:

{
    "Comments": { <composite:RichTextInput> },
    "PrivateComments": { <composite:RichTextInput> },
}

You should provide the basic properties that are appropriate to the API version level you’re using (for example, if you’re using the v1.14 APIs, use all the basic properties introduced with that version and older, such as, v1.13, v1.12, and so on).

Comments and PrivateComments

Note that both these properties use the RichTextInput structure for incoming grade values.

With LE v1.13 of the API and later, you should include these properties with incoming grade value structures of all types, and leave the comment text as an empty string if you intend to have no comment or privately-visible comment associated with the grade value.

With older versions of the API, you should not include these two properties at all in incoming grade value structures.

Grade values have additional properties depending on their type.

Numeric. When providing numeric grade values grade values, you should make a JSON block that includes both the basic common properties appropriate for your API contract version and these additional properties:

{
    // Appropriate basic common properties here
    "GradeObjectType": 1,
    "PointsNumerator": <number:decimal>
}

PassFail. When providing pass-fail grade values, you should make a JSON block that includes both the basic common properties appropriate for your API contract version and these additional properties:

{
    // Appropriate basic common properties here
    "GradeObjectType": 2,
    "Pass": <boolean>
}

SelectBox. When providing select-box grade values, you should make a JSON block that includes both the basic common properties appropriate for your API contract version and these additional properties:

{
    // Appropriate basic common properties here
    "GradeObjectType": 3,
    "Value": <string>
}

Text. When providing text grade values, you should make a JSON block that includes both the basic common properties appropriate for your API contract version and these additional properties:

{
    // Appropriate basic common properties here
    "GradeObjectType": 4,
    "Text": <string>
}
Grade.IncomingFinalAdjustedGradeValue

If you use the API to provide a final adjusted grade value for a user, then use a block like this:

{
    "PointsNumerator": <number:decimal>,
    "PointsDenominator": <number:decimal>
}

Course completion

Grade.CourseCompletion
{
    "OrgUnitId": <number:D2LID>,
    "CompletionId": <number:D2LID>,
    "UserId": <number:D2LID>,
    "CompletedDate": <string:UTCDateTime>,
    "ExpiryDate": <string:UTCDateTime>|null
}
Grade.CourseCompletionCreationData
{
    "UserId": <number:D2LID>,
    "CompletedDate": <string:UTCDateTime>,
    "ExpiryDate": <string:UTCDateTime>|null
}
ExpiryDate

Course created with an expiry date if this property is not null.

Grade.CourseCompletionUpdateData
{
    "CompletedDate": <string:UTCDateTime>,
    "ExpiryDate": <string:UTCDateTime>|null
}
ExpiryDate

Course adjusted to have an expiry date if this property is not null.

Grade Statistics

Grade.GradeStatisticsInfo
{
    "OrgUnitId": <number:D2LID>,
    "GradeObjectId": <number:D2LID>,
    "Minimum": <number:decimal>|null,
    "Maximum": <number:decimal>|null,
    "Average": <number:decimal>|null,
    "Mode": [ <number:decimal>, ... ],
    "Median": <number:decimal>|null,
    "StandardDeviation": <number:decimal>|null,
}

Grade Setup

Grade.GradeSetupInfo
{
    "GradingSystem": <string:GRADINGSYSTEM_T>,
    "IsNullGradeZero": <boolean>,
    "DefaultGradeSchemeId": <number:D2LID>
}

Bulk Grade Exemptions

Grade.BulkGradeObjectExemption
{
    "GradeObjectCategory": { <composite:BulkGradeObjectCategory> }|null,
    "GradeObjectId": <number:D2LID>,
    "GradeObjectName": <string>,
    "GradeObjectType": <number:GRADEOBJ_T>,
    "GradeValue": { <composite:GradeObjectValue> },
    "IsExempt": <boolean>|null
}
Grade.BulkGradeObjectExemptionConflict
{
    "UserId": <number:D2LID>,
    "Exemption": { <composite:BulkGradeObjectExemption> },
    "GradingSystem": <number:GRADINGSYSTEM_T>
}
Grade.BulkGradeObjectExemptionResult
{
    "Items": [ <composite:BulkGradeObjectExemption>, ... ],
    "ExemptionAccessDate": <string:UTCDateTime>
}
ExemptionAccessDate

The time the BulkGradeObjectExemptionResult is originally requested. Used for conflict checking prior to updating exemption data.

Grade.BulkGradeObjectExemptionUpdate
{
    "ExemptedIds": [ <number:D2LID>, ... ],
    "UnexemptedIds": [ <number:D2LID>, ... ],
    "ExemptionAccessDate": <string:UTCDateTime>
}
ExemptedIds

IDs of grade objects to exempt.

UnexemptedIds

IDs of grade objects to unexempt.

ExemptionAccessDate

The back-end service will determine that there is a conflict if a grade object has been updated since the ExemptionAccessDate. In this case, it will not update the grade object’s exemption data and will create a BulkGradeObjectExemptionConflict result for the grade object. The back-end service will update grade objects not in conflict, even if some of the grade objects in the bulk request are in conflict

Grade.GradeObjectValue
{
   "PointsNumerator": <number:decimal>|null,
   "PointsDenominator": <number:decimal>|null,
   "WeightedNumerator": <number:decimal>|null,
   "WeightedDenominator": <number:decimal>|null,
   "GradeText": <string>|null,
   "SchemeRangeId": <number:D2LID>|null,
   "DisplayValue": <string>
}
GradeText

Has a non-null value for GradeText grade objects.

SchemeRangeId

Has a non-null value for SelectBox grade objects.

DisplayValue

The grade formatted according to the org unit’s display settings. Empty for GradeText grade objects. Use GradeText as the display value in this case.

Grade.BulkGradeObjectCategory
{
    "Id": <number:D2LID>,
    "Name": <string>
}

Actions

DELETE /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)

Delete a specific grade object for a particular org unit.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectID (D2LID) – Grade object ID.

Oauth2 Scopes:

grades:gradeobjects:delete

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

GET /d2l/api/le/(version)/(orgUnitId)/grades/

Retrieve all the current grade objects for a particular org unit.

Parameters:
Oauth2 Scopes:

grades:gradeobjects:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a JSON array of GradeObject blocks.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)

Retrieve a specific grade object for a particular org unit.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

Oauth2 Scopes:

grades:gradeobjects:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a GradeObject JSON block.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/access/

Retrieve a list of users with access to a specified grade.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

Query Parameters:
  • userId (D2LID) – Optional. Retrieve access for a single user.

  • roleId (D2LID) – Optional. Retrieve access for users with the given role.

Oauth2 Scopes:

grades:access:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a object list page containing the resulting UserAccess blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).

POST /d2l/api/le/(version)/(orgUnitId)/grades/

Create a new grade object for a particular org unit.

Parameters:
JSON Parameters:
Oauth2 Scopes:

grades:gradeobjects:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. This action expects a grade object of one of the first four grade object types.

Return. This action returns a GradeObject JSON block for the grade object that the service just created, so you can quickly retrieve the grade object ID.

PUT /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)

Update a specific grade object.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

JSON Parameters:
Oauth2 Scopes:

grades:gradeobjects:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. This action expects a grade object of one of the first four grade object types. Note that your provided block’s data replaces all the associated grade object’s data on the service.

Return. This action returns a GradeObject JSON block for the grade object that the service just updated.

Grade categories

DELETE /d2l/api/le/(version)/(orgUnitId)/grades/categories/(categoryId)

Delete a specific grade category for a provided org unit.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • categoryId (D2LID) – Grade category ID.

Oauth2 Scopes:

grades:gradecategories:delete

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

GET /d2l/api/le/(version)/(orgUnitId)/grades/categories/

Retrieve a list of all grade categories for a provided org unit.

Parameters:
Oauth2 Scopes:

grades:gradecategories:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action retrieves a JSON array of GradeObjectCategory blocks.

GET /d2l/api/le/(version)/(orgUnitId)/grades/categories/(categoryId)

Retrieve a specific grade category for a provided org unit.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • categoryId (D2LID) – Grade category ID.

Oauth2 Scopes:

grades:gradecategories:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action retrieves a GradeObjectCategory JSON block.

POST /d2l/api/le/(version)/(orgUnitId)/grades/categories/

Create a new grade category for a provided org unit.

Parameters:
JSON Parameters:
Oauth2 Scopes:

grades:gradecategories:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns the newly created grade object category in a GradeObjectCategory JSON block, so that you can quickly gather its grade category ID.

Grade schemes

GET /d2l/api/le/(version)/(orgUnitId)/grades/schemes/

Retrieve all the grade schemes for a provided org unit.

Parameters:
Oauth2 Scopes:

grades:gradeschemes:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a JSON array of GradeScheme blocks.

GET /d2l/api/le/(version)/(orgUnitId)/grades/schemes/(gradeSchemeId)

Retrieve a particular grade scheme.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeSchemeId (D2LID) – Grade scheme ID.

Oauth2 Scopes:

grades:gradeschemes:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a GradeScheme JSON block.

Grade values

Default grade values. Each user can have a grade value associated with each grade object. If you try to retrieve a computable grade value for a user for whom a grade has not been set, the API may return a “default” grade value object instead of a 404. In this case, the computable properties for the grade value that the LMS has not yet been able to calculate (the numerator and denominator properties for the grade value) will be set to null, and you should be prepared to handle such values.

Final grade values. Note that final grade values can be managed before being released. If the calling user has permission to see grades but not to manage them, they may not get a value back when calling the final grade actions if the grades have not yet been released. Calling users that can manage grades, however, can use the final grade actions to retrieve final grade values before release, provided some value has been set for them. The kind of value the back-end service returns depends upon how the org unit’s gradebook has been configured to provide final grades (whether to release the final grades as calculated, or as adjusted).

GET /d2l/api/le/(version)/(orgUnitId)/grades/final/values/myGradeValue

Retrieve the final grade value for the current user context.

Parameters:
Oauth2 Scopes:

grades:own_grades:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a GradeValue JSON block containing the final calculated grade value for the current user context.

GET /d2l/api/le/(version)/grades/final/values/myGradeValues/

Retrieve a list of final grade values for the current user context across a number of org units.

Parameters:
Query Parameters:
  • orgUnitIdsCSV (CSV of D2LIDs) – List of org units to check (limited to 100 or fewer).

Oauth2 Scopes:

grades:own_grades:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. When calling this action, you must provide a list of org unit IDs that amount to some or all of the calling user’s active enrollments.

Return. This action returns an ObjectListPage JSON block containing a list of final calculated grade values sorted by the OrgUnitIds that match the provided query parameter filters.

GET /d2l/api/le/(version)/(orgUnitId)/grades/final/values/(userId)

Retrieve the final grade value for a particular user.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Query Parameters:
  • gradeType (string) – Optional. Force return of final calculated or adjusted grade (see description).

Oauth2 Scopes:

grades:gradevalues:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. This action can take an optional query parameter:

gradeType

If you do not provide a gradeType query parameter, this action fetches the final adjusted/calculated grade as configured in course settigs.

If you provide calculated for this parameter, the action will always return the final calculated grade. If you provide adjusted for this parameter, the action will always return the final adjusted grade.

Return. This action returns a GradeValue JSON block containing the final calculated grade value for the provided user.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/values/

Retrieve each user’s grade value for a particular grade object.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

Query Parameters:
  • sort (string) – Optional. Sort by firstname, lastname, grade value, or lastmodified (see description).

  • pageSize (number) – Optional. Number of objects to return in each data page (see description).

  • isGraded (boolean) – Optional. Filter to graded or not graded users (see description).

  • searchText (string) – Optional. Show only users that match this string inside first and last names.

Oauth2 Scopes:

grades:gradevalues:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. This action can take a number of optional sort and filter parameters:

isGraded

If you do not provide an isGraded query parameter, this action fetches back a list of all users to whom the grade object applies, whether they have yet been graded or not.

If you provide true for this parameter, the action filters the list to show only graded users; if you provide false for this parameter, the action filters the list to show only ungraded users.

sort

You can control the sorting key field, and the direction of the sort, by using the key name in combination with a minus sign (to make the sort descending instead of ascending). Thus, to do an ascending sort by graded user’s first name you use ?sort=firstname; to do a descending sort by grade value, you use ?sort=-grade.

If you don’t provide the parameter, this action behaves as if you had provided ?sort=lastname (ascending sort by graded user’s SortLastName (LastName in version < 1.60)).

Note that setting the sorting key field to lastname sorts by the user’s SortLastName, if present, as of API version 1.60. If not present, or if the version is < 1.60, it sorts by the user’s LastName. See User.LegalPreferredNames for more information.

pageSize

You can also request an adjustment to the size of the data pages retrieved with this action: by default, the data pages will contain at most 20 items; you can use the pageSize query parameter to request up to 200 items per page.

Return. This action returns an ObjectListPage JSON block containing a list of user grade values for your provided grade object.

Note

Valid grade object types. Valid grade object types for this route are Numeric, PassFail and SelectBox. If this route is called with a grade object of any other type, a 400 status code will be returned.

Sorting and searching. When searching and/or sorting you are subject to user privacy controls. If you try to sort by last name or first name, and your calling user context does not have permission to see the relevant field, then this action falls back to sorting by grade.

GET /d2l/api/le/(version)/(orgUnitId)/grades/final/values/

Retrieve each user’s final grade value for a particular org unit.

Parameters:
Query Parameters:
  • sort (string) – Optional. Sort by firstname, lastname, grade value, or lastmodified (see description).

  • pageSize (number) – Optional. Number of objects to return in each data page (see description).

  • isGraded (boolean) – Optional. Filter to graded or not graded users (see description).

  • searchText (string) – Optional. Show only users that match this string inside first and last names.

Oauth2 Scopes:

grades:gradevalues:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. This action can take a number of optional sort and filter parameters:

isGraded

If you do not provide an isGraded query parameter, this action fetches back a list of all users to whom the grade object applies, whether they have yet been graded or not.

If you provide true for this parameter, the action filters the list to show only graded users; otherwise, if you provide false for this parameter or do not include it, the action filters the list to show only ungraded users.

sort

You can control the sorting key field, and the direction of the sort, by using the key name in combination with a minus sign (to make the sort descending instead of ascending). Thus, to do an ascending sort by graded user’s first name you use ?sort=firstname; to do a descending sort by grade value, you use ?sort=-grade.

If you don’t provide the parameter, this action behaves as if you had provided ?sort=lastname (ascending sort by graded user’s SortLastName (LastName in version < 1.60)).

Note that setting the sorting key field to lastname sorts by the user’s SortLastName, if present, as of API version 1.60. If not present, or if the version is < 1.60, it sorts by the user’s LastName. See User.LegalPreferredNames for more information.

pageSize

You can also request an adjustment to the size of the data pages retrieved with this action: by default, the data pages will contain at most 20 items; you can use the pageSize query parameter to request up to 200 items per page.

Return. This action returns an ObjectListPage JSON block containing a list of user grade values for the final grade object.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/values/(userId)

Retrieve a specific grade value for a particular user assigned in an org unit.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

grades:gradevalues:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a GradeValue JSON block.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/values/myGradeValue

Retrieve a specific grade value for the current user context assigned in a particular org unit.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

Oauth2 Scopes:

grades:own_grades:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a GradeValue JSON block.

GET /d2l/api/le/(version)/(orgUnitId)/grades/values/myGradeValues/

Retrieve all the grade objects for the current user context assigned in a particular org unit.

Parameters:
Oauth2 Scopes:

grades:own_grades:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a JSON array of GradeValue blocks.

GET /d2l/api/le/(version)/(orgUnitId)/grades/values/(userId)/

Retrieve all the grade objects for a particular user assigned in an org unit.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

grades:gradevalues:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a JSON array of GradeValue blocks.

POST /d2l/api/le/(version)/(orgUnitId)/grades/final/calculated/(userId)

Recalculate final grade value for provided user in org unit.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

grades:gradevalues:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

POST /d2l/api/le/(version)/(orgUnitId)/grades/final/calculated/all

Recalculate all final grade values for provided org unit.

Parameters:
Oauth2 Scopes:

grades:gradevalues:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

PUT /d2l/api/le/(version)/(orgUnitId)/grades/final/values/(userId)

Set the adjusted final grade value for provided user in org unit.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

JSON Parameters:
Oauth2 Scopes:

grades:gradevalues:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

PUT /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/values/(userId)

Provide a specific grade value for a particular user.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID

  • userId (D2LID) – User ID.

JSON Parameters:
Oauth2 Scopes:

grades:gradevalues:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. This action expects an IncomingGradeValue aligned with one of the first four grade object types. Note that your provided block’s data replaces all the associated grade value data on the service.

Course completion

DELETE /d2l/api/le/(version)/(orgUnitId)/grades/courseCompletion/(completionId)

Delete a course completion.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • completionId (D2LID) – Completion ID.

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

GET /d2l/api/le/(version)/(orgUnitId)/grades/courseCompletion/

Retrieve all the course completion records for an org unit.

Parameters:
Query Parameters:
  • userId (D2LID) – Optional. User ID.

  • startExpiry (UTCDateTime) – Optional. Start of expiration range to query.

  • endExpiry (UTCDateTime) – Optional. End of expirtation range to query.

  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. You can limit the scope of this query by providing an optional start and/or end date to clamp the search. You can also limit the scope of this query by providing an optional User ID (to fetch only course completions for that user within the org unit).

You can also use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. This action returns a paged result set containing the resulting CourseCompletion data blocks for the segment following your bookmark parameter (or the first segment if the parameter is empty or missing).

GET /d2l/api/le/(version)/grades/courseCompletion/(userId)/

Retrieve all the course completion records for a user.

Parameters:
Query Parameters:
  • startExpiry (UTCDateTime) – Optional. Start of expiration range to query.

  • endExpiry (UTCDateTime) – Optional. End of expirtation range to query.

  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. You can limit the scope of this query by providing an optional start and/or end date to clamp the search.

You can also use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. This action returns a paged result set containing the resulting CourseCompletion data blocks for the segment following your bookmark parameter (or the first segment if the parameter is empty or missing).

POST /d2l/api/le/(version)/(orgUnitId)/grades/courseCompletion/

Create a new course completion for an org unit.

Parameters:
JSON Parameters:
Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a CourseCompletion JSON block with the newly created course completion record.

PUT /d2l/api/le/(version)/(orgUnitId)/grades/courseCompletion/(completionId)

Update an existing course completion.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • completionId (D2LID) – Completion ID.

JSON Parameters:
Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a CourseCompletion JSON block with the updated course completion record.

Grade statistics

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/statistics

Get statistics for a specified grade item.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId – Grade object ID.

Oauth2 Scopes:

grades:gradestatistics:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a GradeStatisticsInfo JSON block.

Grade setup

GET /d2l/api/le/(version)/(orgUnitId)/grades/setup/

Retrieve the grades configuration for the org unit.

Parameters:
Oauth2 Scopes:

grades:gradesettings:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a GradeSetupInfo JSON block.

PUT /d2l/api/le/(version)/(orgUnitId)/grades/setup/

Update the grades configuration for the org unit.

Parameters:
Oauth2 Scopes:

grades:gradesettings:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. This action expects a GradeSetupInfo JSON block.

Return. This action returns a GradeSetupInfo JSON block.

Grade exemptions

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/exemptions/

Retrieve all the exempt users for a provided grade.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

Oauth2 Scopes:

grades:gradeobjects:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action retrieves a JSON array of User blocks.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/exemptions/(userId)

Determine if a user is exempt from a grade.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

grades:gradeobjects:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a User JSON block.

POST /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/exemptions/(userId)

Exempt a user from a grade.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

grades:gradeobjects:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a User JSON block.

DELETE /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/exemptions/(userId)

Remove a user’s exemption from a grade.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • gradeObjectId (D2LID) – Grade object ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

grades:gradeobjects:delete

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Bulk grade exemptions

GET /d2l/api/le/(version)/(orgUnitId)/grades/exemptions/(userId)

Retrieve all the grade objects for a provided user in a provided org unit with exemption status included.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

grades:gradeobjects:read

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Return. This action returns a BulkGradeObjectExemptionResult JSON block.

POST /d2l/api/le/(version)/(orgUnitId)/grades/exemptions/(userId)

Attempt to exempt or unexempt a set of grades for a user.

Parameters:
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

grades:gradeobjects:write

Status Codes:
API Versions:
  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66Deprecated as of LMS v20.24.1.

  • 1.60-Obsolete as of LMS v20.24.1.

Input. This action expects a BulkGradeObjectExemptionUpdate. If a grade has been changed since the provided ExemptionAccessDate, a conflict will be added to the result set and that grade will not be exempted or unexempted.

Return. This action retrieves a JSON array of BulkGradeObjectExemptionConflict blocks.

«  Groups   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Course content (content objects, tables of content)  »