Developer Platform (February 2023)

Enrollments

«  Awards   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Organization structure (Org units, structure)  »

These attributes and actions collect together functionality around enrollments: assigning users to the various defined organizational units.

Controlling access to enrollments. Note that system permissions can provide quite fine-grained control over what enrollments users are allowed to see. The permissions for a user’s role control that user’s ability to retrieve enrollment information in two ways:

Attributes

Enrollment.ClasslistUser

Structure for the enrolled user’s information that the service exposes through the classlist API.

{
    "Identifier": <string:D2LID>,
    "ProfileIdentifier": <string>,
    "DisplayName": <string>,
    "Username": <string>|null,
    "OrgDefinedId": <string>|null,
    "Email": <string>|null,
    "FirstName": <string>|null,
    "LastName": <string>|null,
    "RoleId": <number:D2LID>|null,
    "LastAccessed": <string:UTCDateTime>|null,
    "IsOnline": <boolean>,
    "ClasslistRoleDisplayName": <string>  // Added as of LMS v20.22.12
}
Username, OrgDefinedId, Email, RoleId, LastAccessed

The back-end service can constrain the visibility of these properties through configuration of the Classlist tool. If these values are configured to be eligible to appear in the classlist for an org unit, then the API can return these values to the calling user (also assuming that the calling user’s role has permission to see those values).

ClasslistRoleDisplayName

This field will be an empty string if the role referenced does not have the setting: Display this role in the classlist.

Enrollment.CreateEnrollmentData
{
    "OrgUnitId": <number:D2LID>,
    "UserId": <number:D2LID>,
    "RoleId": <number:D2LID>
}
Enrollment.EnrollmentData
{
    "OrgUnitId": <number:D2LID>,
    "UserId": <number:D2LID>,
    "RoleId": <number:D2LID>,
    "IsCascading": <boolean>
}
Enrollment.MyOrgUnitInfo
{
    "OrgUnit": { <composite:Enrollment.OrgUnitInfo> },
    "Access": {
        "IsActive": <boolean>,
        "StartDate": <string:UTCDateTime>|null,
        "EndDate": <string:UTCDateTime>|null,
        "CanAccess": <boolean>,
        "ClasslistRoleName": <string>|null,
        "LISRoles": [ <string>, ... ],
        "LastAccessed": <string:UTCDateTime>|null
    },
    "PinDate": <string:UTCDateTime>|null
}
StartDate

If present, presents the start date of the org unit.

EndDate

If present, presents the end date of the org unit.

ClasslistRoleName

If present, presents the name of the D2L enrollment role as it is configured to appear in the classlist.

LISRoles

If present, provides the list of standard 1EdTech LIS roles that are configured for the D2L enrollment role to get sent to an LTI® Tool on an LTI launch.

LastAccessed

If present, presents the date the user last accessed the org unit.

PinDate

Date that this enrollment was pinned to appear at the top of the list of a user’s enrollments.

Enrollment.MyOrgUnitAccessInfo
{
    "OrgUnitId": <number:D2LID>,
    "AccessInfo": {
        "IsActive": <boolean>,
        "StartDate": <string:UTCDateTime>|null,
        "EndDate": <string:UTCDateTime>|null,
        "CanAccess": <boolean>,
        "ClasslistRoleName": <string>|null,
        "LISRoles": [ <string>, ... ],
        "LastAccessed": <string:UTCDateTime>|null
    }
}
StartDate

If present, presents the start date of the org unit.

EndDate

If present, presents the end date of the org unit.

ClasslistRoleName

If present, presents the name of the D2L enrollment role as it is configured to appear in the classlist.

LISRoles

If present, provides the list of standard 1EdTech LIS roles that are configured for the D2L enrollment role to get sent to an LTI Tool on an LTI Launch.

LastAccessed

If present, presents the date the user last accessed the org unit.

Enrollment.OrgUnitInfo
{
    "Id": <number:D2LID>,
    "Type": { <composite:OrgUnit.OrgUnitTypeInfo> },
    "Name": <string>,
    "Code": <string>|null,
    "HomeUrl": <string:URL>|null,
    "ImageUrl": <string:APIURL>|null
}
Code

In rare cases, an org unit may have no code set for it; in that case, you may get null for the code on actions that retrieve this structure. This is most likely to happen for the root organization org unit only.

HomeUrl

The value will be null when the user cannot access the org unit.

ImageUrl

A value will only be provided for course offerings that have an image set; in all other situations the value will be null.

Enrollment.OrgUnitUser
{
    "User": { <composite:User.User> },
    "Role": { <composite:Enrollment.RoleInfo> }
}
Enrollment.RoleInfo
{
    "Id": <number:D2LID>,
    "Code": <string>|null,
    "Name": <string>
}
Enrollment.UserOrgUnit
{
    "OrgUnit": { <composite:Enrollment.OrgUnitInfo> },
    "Role": { <composite:Enrollment.RoleInfo> },
    "IsCascading": <boolean>,  // Appears in LP's unstable contract
    "EnrolledByUserId": <number:D2LID>|null,  // Appears in LP's unstable contract
    "EnrolledByUserDate": <string:UTCDateTime>|null  // Appears in LP's unstable contract
}
EnrolledByUserId

If the enrollment was directly made by a user, provides the user ID of the person who created this enrollment. If the enrollment was made by other methods such as an auto enrollment of a cascading role, the field will be null.

EnrolledByUserDate

If the enrollment was directly made by a user, provides the date when this enrollment was created. If the enrollment was made by other methods such as an auto enrollment of a cascading role, the field will be null.

Auditors

Auditors are users that have permission to audit the presence of other users (auditees). In these structures, the properties AuditorId and AuditeeId are actually just the User ID values for the users involved: we use the Auditor and Auditee terms to make it clear which position the user occupies in this relationship.

Audit.AuditedUser

Structure mapping a single auditee to the people auditing that person.

{
    "AuditeeId": <number:D2LID>,
    "DisplayName": <string>,
    "Auditors": [ <Audit.UsersAuditor>, ... ]
}
Audit.Auditee

Information for an enrolled user who can be audited.

{
    "AuditeeId": <number:D2LID>,
    "DisplayName": <string>
}
Audit.Auditor

Structure mapping a single auditor to the enrolled auditees the person is auditing.

{
    "AuditorId": <number:D2LID>,
    "DisplayName": <string>,
    "Auditees": [ <Audit.Auditee>, ... ]
}
Audit.UsersAuditor

Information for an individual who can audit an enrolled user.

{
    "AuditorId": <number:D2LID>,
    "DisplayName": <string>
}

Actions

DELETE /d2l/api/lp/(version)/enrollments/orgUnits/(orgUnitId)/users/(userId)

Delete a user’s enrollment in a provided org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

enrollment:orgunit:delete

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Return. Unlike most delete actions, this action returns an EnrollmentData JSON block showing the enrollment status just before this action deleted the user’s enrollment.

DELETE /d2l/api/lp/(version)/enrollments/users/(userId)/orgUnits/(orgUnitId)

Delete a user’s enrollment in a provided org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • userId (D2LID) – User ID.

  • orgUnitId (D2LID) – Org unit ID.

Oauth2 Scopes:

enrollment:orgunit:delete

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Return. Unlike most delete actions, this action returns an EnrollmentData JSON block showing the enrollment status just before this action deleted the user’s enrollment

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

Retrieve the enrolled users in the classlist for an org unit.

Parameters:
Oauth2 Scopes:

enrollment:orgunit:read

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.1.

Return. This action returns a JSON array of ClasslistUser data blocks. Note that the data blocks returned here respect the org unit’s privacy settings with respect to the Username, OrgDefinedId, Email, FirstName, LastName and the contents of the DisplayName properties (typically, the display-name gets formed from the user’s first and last names, and privacy settings govern the visibility of those items).

Warning

Some orgunits can have very large numbers of enrolled users, so the classlist can be a quite large collection. We advise you to make very careful use of this API call because it asks for an unbounded set of results. We strongly recommend you use the paged version of this call instead.

GET /d2l/api/le/(version)/(orgUnitId)/classlist/paged/

Retrieve the enrolled users in the classlist for an org unit.

Parameters:
Query Parameters:

  • onlyShowShownInGrades – (Optional) If true, retrieve only gradeable users; false by default.

  • searchTerm (string) – (Optional) Search term to look for.

Oauth2 Scopes:

enrollment:orgunit:read

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.1.

Input. You can provide a searchTerm query parameter string to filter results returned; the back-end service looks for fields that contain your search term in these ClasslistUser fields: Username, OrgDefinedId, FirstName, LastName.

Return. This action returns an object list page JSON block containing a list of ClasslistUser blocks, sorted first (ascending) by the users’ first names, then by their last names (see User.LegalPreferredNames for detail on how last names are chosen for sorting), and then by the users’ Identifier values.

GET /d2l/api/lp/(version)/enrollments/myenrollments/

Retrieve the list of all enrollments for the current user.

Parameters:
Query Parameters:

  • orgUnitTypeId (CSV of D2LIDs) – Optional. Filter list to specific org unit types.

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

  • sortBy (string) – Optional. Sort by key-expression (see description).

  • isActive (bool) – Optional. Filter on the org unit’s isActive property and select only records that match your provided parameter value.

  • startDateTime (UTCDateTime) – Optional. Start of time window to examine.

  • endDateTime (UTCDateTime) – Optional. End of time window to examine.

  • canAccess (bool) – Optional. Filter on the org unit’s Access.CanAccess property and select only records that match your provided parameter value.

Oauth2 Scopes:

enrollment:own_enrollment:read

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

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

sortBy

This action uses the sortBy query parameter to control the sorting of items retrieved:

  • By default, this action sorts results in ascending order by org unit ID.

  • You can indicate you want to sort in descending order with a key by using a minus sign (for example, -OrgUnitId).

  • You can sort by multiple keys, by using the query parameter more than once; sortation happens in the order you provide the parameters (for example: &sortBy=-OrgUnitId&sortBy=OrgUnitName).

  • You can use these keys for sorting: EndDate, PinDate, OrgUnitTypeId, OrgUnitName, StartDate.

endDateTime and startDateTime

These parameters describe a time range that will match against any org units that have a start date occurring before the endDateTime and an end date occurring after the startDateTime (so that the time range you provide overlaps with the time span for the org unit). Note that org units without start dates are assumed to have a start date earlier than any other time, while org units without end dates are assumed to have an end date later than any other time.

Return. This action returns a paged result set containing the resulting MyOrgUnitInfo data blocks for the segment following your bookmark parameter (or the first segment if the parameter is empty or missing). If the request included sortBy, the same sortBy parameters must be specified with the bookmark parameter when fetching the next page.

Note

This action uses the org unit’s Id property enclosed within the MyOrgUnitInfo block as the paging control value. You can fetch the segment of results following any org unit’s entry in the entire data set by passing that org unit’s Id as the bookmark value.

GET /d2l/api/lp/(version)/enrollments/myenrollments/(orgUnitId)

Retrieve the enrollment details for the current user in the provided org unit.

Parameters:
Oauth2 Scopes:

enrollment:own_enrollment:read

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Return. This action returns a MyOrgUnitInfo JSON block.

GET /d2l/api/lp/(version)/enrollments/myenrollments/(orgUnitId)/access

Retrieve abbreviated enrollment details for the current user in the provided org unit.

Parameters:
Oauth2 Scopes:

enrollment:own_enrollment:read

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Return. This action returns a MyOrgUnitAcessInfo JSON block.

GET /d2l/api/lp/(version)/enrollments/myenrollments/(orgUnitId)/parentOrgUnits

Retrieve enrollment details of all parent org units of the provided org unit in which the current user is enrolled.

Parameters:
Query Parameters:

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

Oauth2 Scopes:

enrollment:own_enrollment:read

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Input. You can 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 MyOrgUnitInfo data blocks for the segment following your bookmark parameter (or the first segment if the parameter is empty or missing).

Note

This action uses the org unit’s Id property enclosed within the MyOrgUnitInfo block as the paging control value. You can fetch the segment of results following any org unit’s entry in the entire data set by passing that org unit’s Id as the bookmark value.

GET /d2l/api/lp/(version)/enrollments/orgUnits/(orgUnitId)/users/

Retrieve the collection of users enrolled in the identified org unit.

Parameters:
Query Parameters:

  • roleId (D2LID) – Optional. Filter list to a specific user role.

  • isActive (bool) – Optional. Filter list to only active or inactive users.

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

Oauth2 Scopes:

enrollment:orgunit:read

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Input. You can 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 OrgUnitUser data blocks for the segment following your bookmark parameter (or the first segment if the parameter is empty or missing).

Note

This action employs the user’s Identifier property enclosed within the OrgUnitUser block as the paging control value. You can fetch the segment of results following any user’s entry in the entire data set by passing that user’s Identifier as the bookmark value.

Support for the isActive query parameter was added to this action as of LP API v1.26.

GET /d2l/api/lp/(version)/enrollments/orgUnits/(orgUnitId)/users/(userId)

Retrieve enrollment details for a user in the provided org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

enrollment:orgunit:read

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Return. This action returns an EnrollmentData JSON block.

Note

This call is equivalent to the route that fetches by specifying the user first, and then the org unit.

GET /d2l/api/lp/(version)/enrollments/users/(userId)/orgUnits/

Retrieve a list of all enrollments for the provided user.

Parameters:
Query Parameters:

  • orgUnitTypeId (CSV of D2LIDs) – Optional. Filter list to specific org unit types.

  • roleId (D2LID) – Optional. Filter list to a specific user role.

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

Oauth2 Scopes:

enrollment:orgunit:read

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Input. You can 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 UserOrgUnit data blocks for the segment following your bookmark parameter (or the first segment if the parameter is empty or missing).

Note

This action employs the org unit’s Id property enclosed within the UserOrgUnit block as the paging control value. You can fetch the segment of results following any org unit’s entry in the entire data set by passing that org unit’s Id as the bookmark value.

GET /d2l/api/lp/(version)/enrollments/users/(userId)/orgUnits/(orgUnitId)

Retrieve enrollment details in an org unit for the provided user.

Parameters:

  • version (D2LVERSION) – API version.

  • userId (D2LID) – User ID.

  • orgUnitId (D2LID) – Org unit ID.

Oauth2 Scopes:

enrollment:orgunit:read

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Return. This action returns an EnrollmentData JSON block.

Note

This call is equivalent to the route that fetches by specifying the org unit first, and then the user.

POST /d2l/api/lp/(version)/enrollments/

Create or update a new enrollment for a user.

Parameters:
JSON Parameters:
Oauth2 Scopes:

enrollment:orgunit:create

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Input. If the user doesn’t already have an enrollment in the applicable org unit, this action creates a new enrollment; if the user does already have an enrollment in the org unit, this action updates the enrollment in place to use the new role.

Return. This action returns an EnrollmentData JSON block for the newly enrolled user.

Pinning

An org unit that is pinned appears sorted tom the top of the list of courses presented to the user in the service’s web user interface. These routes let you add and remove pins from a user’s enrolled org units.

DELETE /d2l/api/lp/(version)/enrollments/myenrollments/(orgUnitId)/pin

Remove the pin from the provided org unit.

Parameters:
Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

DELETE /d2l/api/lp/(version)/enrollments/orgUnits/(orgUnitId)/users/(userId)/pin

Remove the pin from the provided org unit for specific user.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

POST /d2l/api/lp/(version)/enrollments/myenrollments/(orgUnitId)/pin

Pin an org unit to the top of the list of a user’s enrollments.

Parameters:
Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Return. This action returns a MyOrgUnitInfo JSON block.

POST /d2l/api/lp/(version)/enrollments/orgUnits/(orgUnitId)/users/(userId)/pin

Pin an org unit to the top of the list for a user’s enrollments.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Status Codes:
API Versions:

  • 1.35+ – Route first appears in LMS v20.22.1.

  • 1.31-1.34 – Deprecated as of LMS v20.23.1.

  • 1.30- – Obsolete as of LMS v20.23.1.

Auditors

In these routes, when we use the terms AuditorId and AuditeeId, as parameters or JSON properties, these are actually the UserId values for the appropriate users. Users auditing, or being audited, will not have separate IDs for that relationship.

DELETE /d2l/api/le/(version)/auditing/auditors/(auditorId)/auditees/

Remove an auditee from the list of users that an auditor is auditing.

Parameters:
JSON Parameters:

  • AuditeeId (D2LID as single JSON number) – Auditee to remove.

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.1.

Input. Note that you must pass a single JSON number in the body of this request; for example, if you want to remove user with ID 1234 from the an auditor’s list of auditees, your POST body would be:

1234
GET /d2l/api/le/(version)/auditing/auditees/(auditeeId)

Retrieve information for an auditee.

Parameters:
Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.1.

Return. This action returns a AuditedUser JSON block.

GET /d2l/api/le/(version)/auditing/auditors/(auditorId)

Retrieve information for an auditor.

Parameters:

  • version (D2LVERSION) – API version.

  • auditorId – Auditor ID.

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.1.

Return. This action returns a Auditor JSON

block.

GET /d2l/api/le/(version)/auditing/auditors/(auditorId)/auditees/

Retrieve the list of users an auditor is auditing.

Parameters:
Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.1.

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

POST /d2l/api/le/(version)/auditing/auditors/(auditorId)/auditees/

Add a user to the list of those an auditor is auditing.

Parameters:
JSON Parameters:

  • AuditeeId (D2LID as single JSON number) – Auditee to add.

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

  • 1.40- – Obsolete as of LMS v20.22.1.

Input. Note that you must pass a single JSON number in the body of this request; for example, if you want to remove user with ID 1234 from the an auditor’s list of auditees, your POST body would be:

1234

The auditee ID you provide must be a valid user, and may not be the same ID as the auditor ID owning the list (that is, users cannot audit themselves).

«  Awards   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Organization structure (Org units, structure)  »