Developer Platform (November 2024)

Users (user data, whoami)

«  IPSIS   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Settings for user accounts  »

Users are the people participating in the Learning Platform’s services. There are a few actions that operate directly upon user entities themselves, but most often they appear as factors in various other actions, identified by their associated UserId property (for example, the actions you’d use to find the courses a user is enrolled in are associated more directly with the enrollment and course resources).

Attributes

User.User

This structure gets used as a composite to include in resource blocks returned by a variety of services (for example, enrollments).

{
    "Identifier": <string>|null,
    "DisplayName": <string>|null,
    "EmailAddress": <string>|null,
    "OrgDefinedId": <string>|null,
    "ProfileBadgeUrl": <string:APIURL>|null,
    "ProfileIdentifier": <string>|null,
    "UserName": <string>|null  // Added with LMS v20.22.2
}
Identifier

This property can be missing depending on permissions afforded the caller’s context. If it’s missing, then it’s likely that the rest of the properties will also be null.

ProfileBadgeUrl

If the user has a profile image, this property contains the URL for an API action to retrieve it; otherwise, this property may be null.

User.BatchUserCreateError

This structure gets used to report back errors on specific user-creation problems within batch user creation actions.

{
   "UserName": <string>,
   "StatusError": <number>,
   "StatusMessage": <string>
}
UserName

This is the UserName of the user that failed to be created as part of a batch user creation action.

StatusError

An HTTP error code indicating what type of error caused the user to fail to be created.

StatusMessage

A string containing error messages describing why a user failed to be created.

User.CreateUserData

When you use an action to create a user, you pass in a block of new-user data like this:

{
    "OrgDefinedId": <string>|null,
    "FirstName": <string>,
    "MiddleName": <string>|null,
    "LastName": <string>,
    "ExternalEmail": <string>|null,
    "UserName": <string>,
    "RoleId": <number>,
    "IsActive": <boolean>,
    "SendCreationEmail": <boolean>,
    "Pronouns": <string>|null
}
ExternalEmail

Your block of new-user data must either have a null value (if the user has no external email address) or it must have a well-formed email address in this field (if present, the service depends upon this email address to send password reset and/or account creation email to the new user). If you’re creating a utility user account, then you should provide the email address of an administration contact for that utility account.

FirstName, LastName

When creating a new user, the back-end service uses the first and last name fields to populate the legal first and last name of the user. If the user also has preferred versions of these names, you must set those separately after creating the user with their legal names.

These fields both must be valid name strings for users: they cannot be solely composed of whitespace.

OrgDefinedId

If your back-end service has the d2l.Settings.OrgHasOrgDefinedId configuration variable set on, then org-defined IDs for user records, if they are set (not null), should be unique across the organization.

Pronouns

Sets the system-defined pronouns for the user. If you provide null for this field, the created user will have an empty value for the system-defined pronouns.

User.LegalPreferredNames

When you have permission to see the distinction between a user’s legal and preferred names, you can view and set these name values with a block like this:

{
    "LegalFirstName": <string>,
    "LegalLastName": <string>,
    "PreferredFirstName": <string>|null,
    "PreferredLastName": <string>|null,
    "SortLastName": <string>|null
}
LegalFirstName, LegalLastName

Users must always have legal names; when setting names, you must always provide a value for the two Legal name fields.

These fields both must be valid name strings for users: they cannot be solely composed of whitespace.

PreferredFirstName, PreferredLastName

Users need not have preferred names; when setting names, you may provide null for one or both of the Preferred name fields to note that the user has no preferred version of that name other than their legal name(s).

If not null, these fields both must be valid name strings for users: they cannot be solely composed of whitespace.

SortLastName

This field provides a way to set the last name by which the back end service will sort users for presentation in various lists.

When a value is present, the back-end service uses the SortLastName in place of place of PreferredLastName or LegalLastName as the last name sorting key.

However, users need not have a SortLastName; when setting names, you may provide null for the SortLastName field to note that the user has no SortLastName different from their other last names. In this case the back end service will use one of the PreferredLastName or LegalLastName as the last name sorting key.

If not null, this field must be a valid name string for users: it cannot be solely composed of whitespace.

User.Pronouns

When you use an action to retrieve or update a user’s pronoun data, you use a JSON block like this:

{
    "UserDefinedPronouns": <string>|null,
    "SystemDefinedPronouns": <string>|null,  // Only on retrieve actions
    "ShowPronouns": <boolean>,
    "UseUserDefinedPronouns": <boolean>
}
ShowPronouns

If true, user agrees to have their pronoun choices visible in the back-end service UI for others to see.

SystemDefinedPronouns

The back-end service only sends this field to API clients, it does not accept this field on update actions.

UseUserDefinedPronouns

If true, the back-end service permits users to define and display their own pronoun choices set in the UserDefinedPronouns field. If false, the back-end service will only display the choices set in the SystemDefinedPronouns field.

User.PronounsVisibility

When you use an action to retrieve or update a user’s pronoun visibility preference, you use a JSON block like this:

{
    "ShowPronouns": <boolean>
}
User.UpdateUserData

When you use an action to update a user’s data, you pass in a block like this:

{
    "OrgDefinedId": <string>,
    "FirstName": <string>,
    "MiddleName": <string>|null,
    "LastName": <string>,
    "ExternalEmail": <string>|null,
    "UserName": <string>,
    "Activation": { <composite:User.UserActivationData> },
    "Pronouns": <string>|null
}
FirstName, LastName

If the user has preferred names set, then the back-end service uses these property values to update the user’s preferred names; otherwise, these property values update the user’s legal names. To update both sets of names precisely, use the update route with the LegalPreferredNames structure.

These fields both must be valid name strings for users: they cannot be solely composed of whitespace.

Pronouns

Sets the system-defined pronouns for the user. If you provide null for this field, the previously set value will not be touched. If you want to reset the system-defined pronouns to empty for a user, you should provide an empty string (“”) value for this field.

User.UserActivationData
{
    "IsActive": <boolean>
}
User.UserData

When you use an action with the User Management service to retrieve a user’s data, the service passes you back a data block like this (notice that it’s different to the User.WhoAmIUser information block provided by the WhoAmI service actions):

{
    "OrgId": <number:D2LID>,
    "UserId": <number:D2LID>,
    "FirstName": <string>,
    "MiddleName": <string>|null,
    "LastName": <string>,
    "UserName": <string>,
    "ExternalEmail": <string>|null,
    "OrgDefinedId": <string>|null,
    "UniqueIdentifier": <string>,
    "Activation": { <composite:User.UserActivationData> },
    "DisplayName": <string>,
    "LastAccessedDate": <string:UTCDateTime>|null,
    "Pronouns": <string>
}
LastAccessedDate

If the user has accessed the back-end service, this property carries the date-time for the most recent access; if the user has yet to have accessed the back-end service, this property carries the date-time the record for the user was created.

Pronouns

This field will contain the system-definend pronouns for the user unless the user has chosen to set and display their own pronoun choices; in this latter case, this field will contain the user-defined pronoun choices. Additionally, if the user has chosen not to display pronouns at all, this field will be empty.

User.UserPasswordData
{
    "Password": <string>
}
User.WhoAmIUser

This user information block is the one handled by the WhoAmI service actions (notice that it’s different to the User.UserData information block handled by the User Management service actions).

{
    "Identifier": <string:D2LID>,
    "FirstName": <string>,
    "LastName": <string>,
    "UniqueName": <string>,
    "ProfileIdentifier": <string>,
    "Pronouns": <string>
}
Pronouns

This field carries the currently chosen pronoun values by the user.

UniqueName

This field carries the same value as the UniqueIdentifier field in the User.UserData structure.

Integrations

User.GoogleAppsLinkingItem

This block describes the linking relationship between a D2L user and a Google Apps user.

{
    "UserName": <string>,
    "ExternalUserName": <string>,
    "Domain": <string>,
    "ShouldNotify": <boolean>
}
UserName

The user’s D2L UserName property.

ExternalUserName

The user’s name in the Google Apps records (for example, Dale.Witherspoon).

Domain

The Google Apps domain for the user (for example, gmail.com).

Should Notify

If true, notify the user that the linkage has taken place, when it succeeds.

Notifications

ALERTCATEGORY_T

The backend service lets you filter alerts based on their category, and we use a numeric value to indicate the filtering policy to follow:

Alert Category

Value

Subscription

0

Update

1

Message

2
NOTIFICATION_FREQUENCY_T

Frequency at which notifications get sent to the user:

Frequency Category

Value

Never

0

Daily

1

Weekly

2
Alerts.Alert

This block contains identifying data for a user alert.

{
    "Id": <number:D2LID>,
    "OrgUnitId": <number:D2LID>,
    "Category": <ALERTCATEGORY_T>,
    "Title": <string>,
    "Message": <string>,
    "MessageURL": <string>|null,
    "IconURL": <string>|null,
    "AlertDateTime": <string:UTCDateTime>,
    "FeedMessageSubjectType": <string>|null,
    "FeedMessageSubjectId": <string>|null
}
MessageURL

The URL that the alert is referring to. For example, for an assignment feedback alert, this will be the URL that links to the assignment feedback page.

IconURL

The URL for the icon that can be displayed.

FeedMessageSubjectType

The type of the alert subject. For example, for an alert about new content being created, this will be “ContentCreated”.

FeedMessageSubjectId

The ID of the alert subject. For example, for an alert about new content being created, this will be the ID of the content object that was created. Note that this is a string field, and is not necessarily a D2LID.

Notifications.CarrierOutput

This block contains identifying data for a carrying channel for delivering notification messages to the user (for example, email, SMS, Campus Life, and so forth).

{
    "CarrierId": <string:GUID>,
    "DisplayName": <string>
}
Notifications.SubscriptionOutput

This block contains identifying data for a single subscription to a particular type of messages provided by a particular LMS tool (for example, Dropbox, News, and so forth).

{
    "MessageTypeId": <string:GUID>,
    "ToolName": <string>,
    "MessageTypeDescription": <string>,
    "Subscribed": <boolean>
}
Notifications.UserNotificationSettingsData

This block contains a user’s notification settings.

{
    "SummaryFrequency": <number:NOTIFICATION_FREQUENCY_T>,
    "IncludeGradeValue": <boolean>,
    "AllowFutureCoursesToSend": <boolean>
}

Profiles

User.UserProfile

This block contains a user’s personal profile data.

{
    "Nickname": <string>,
    "Birthday": {
        "Month": <number>,
        "Day": <number>
    },
    "HomeTown": <string>,
    "Email": <string>,
    "HomePage": <string>,
    "HomePhone": <string>,
    "BusinessPhone": <string>,
    "MobilePhone": <string>,
    "FaxNumber": <string>,
    "Address1": <string>,
    "Address2": <string>,
    "City": <string>,
    "Province": <string>,
    "PostalCode": <string>,
    "Country": <string>,
    "Company": <string>,
    "JobTitle": <string>,
    "HighSchool": <string>,
    "University": <string>,
    "Hobbies": <string>,
    "FavMusic": <string>,
    "FavTVShows": <string>,
    "FavMovies": <string>,
    "FavBooks": <string>,
    "FavQuotations": <string>,
    "FavWebSites": <string>,
    "FutureGoals": <string>,
    "FavMemory": <string>,
    "SocialMediaUrls": [  // Array of SocialMediaUrl blocks
        {
            "Name": <string>,
            "Url": <string:URL>
        },
        { <composite:SocialMediaUrl> }, ...
    ],
    "ProfileIdentifier": <string>
}
User.UserProfileUpdateData

This block contains a user’s updatable personal profile data.

{
    "Nickname": <string>,
    "Birthday": {
        "Month": <number>,
        "Day": <number>
    },
    "HomeTown": <string>,
    "Email": <string>,
    "HomePage": <string>,
    "HomePhone": <string>,
    "BusinessPhone": <string>,
    "MobilePhone": <string>,
    "FaxNumber": <string>,
    "Address1": <string>,
    "Address2": <string>,
    "City": <string>,
    "Province": <string>,
    "PostalCode": <string>,
    "Country": <string>,
    "Company": <string>,
    "JobTitle": <string>,
    "HighSchool": <string>,
    "University": <string>,
    "Hobbies": <string>,
    "FavMusic": <string>,
    "FavTVShows": <string>,
    "FavMovies": <string>,
    "FavBooks": <string>,
    "FavQuotations": <string>,
    "FavWebSites": <string>,
    "FutureGoals": <string>,
    "FavMemory": <string>,
    "SocialMediaUrls": [  // Array of SocialMediaUrl blocks
        {
            "Name": <string>,
            "Url": <string:URL>
        },
        { <composite:SocialMediaUrl> }, ...
    ]
}

Profile images. As they’re binary data, profile images get provided, or fetched, directly and not as part of the UserProfile JSON structure. Clients can provide any valid image file that’s typically renderable in a browser (for example, JPEG, GIF, or PNG). The back-end service expects to receive a file named “profileImage”, but is not case-sensitive (so “PROFILEIMAGE” will also work, as will “ProfileImage”).

The actions that retrieve a user’s profile image let you specify an expected size, prompting the service to re-size the image to a useful dimension. You may want to perform ad-hoc testing against your back-end service to determine the best sizes to ask for: the service will send you back an image that’s at least as large on each side (in pixels) as the size value you provide.

Currently, the default size for the profile image is 300 pixels in height and width.

Roles

User.Role

This block describes a user role that you can assign to an enrolled user.

{
    "Identifier": <string>,
    "DisplayName": <string>,
    "Code": <string>,
    "Description": <string>,  // Available in LP's unstable contract
    "RoleAlias": <string>,  // Available in LP's unstable contract
    "IsCascading": <boolean>,  // Available in LP's unstable contract
    "AccessFutureCourses": <boolean>,  // Available in LP's unstable contract
    "AccessInactiveCourses": <boolean>,  // Available in LP's unstable contract
    "AccessPastCourses": <boolean>,  // Available in LP's unstable contract
    "ShowInGrades": <boolean>,  // Available in LP's unstable contract
    "ShowInUserProgress": <boolean>,  // Available in LP's unstable contract
    "InClassList": <boolean>,  // Available in LP's unstable contract
}
User.RoleCopyData

This block provides the parameters necessary for copying an existing role.

{
    "RoleName": <string>
}
1EdTechConfig.LISRole

This block describes an LIS role. The 1EdTech Consortium publishes valid values for all properties in this code block as part of their Learning Tools Interoperability Advantage Implementation Guide.

{
    "Handle": <string>,
    "Urn": <string:URN>
}
1EdTechConfig.LISRoleMapping

This block describes a map between a D2L user role and an LIS role (on LTI® launches, the service includes this LIS role in the list of roles sent that corresponds to the launching user’s enrolled D2L role).

{
    "D2LRoleId": <string>,
    "LISRoleUrn": <string:URN>
}

Global User Mapping

GlobalUserMapping.MapIdentifier

For updating and retrieval, the back-end service uses this structure to carry a global user map identifier for a user that can identify that user across a consortium of Brightspace tenants:

{
    "Identifier": <string:D2LID>
}

User Relationships

User parental relationships are links between users that indicate that a user is either a parent or a child in the backend service. Requests to create or delete parental relationships must be accompanied by a JSON object. Each relationship should be mapped according to the template below.

User.ParentalRelationship

This block encodes a parent-child relationship between two Brightspace users.

{
    "ParentId": <string:D2LID>,
    "ChildId": <string:D2LID>
}
User.ParentalRelationshipMapping

When retrieving or setting parent-child relationships for one or more users, API callers use a JSON structure like this:

{
    "userMappings": [
        { <composite:ParentalRelationship> },
        { <composite:ParentalRelationship> }, ...
    ]
}

User Attributes

Attributes.UserAttributeDefinitions

This block describes all user attributes and their configurations.

{
    "UserAttributeDefinitions": [
        {
            "AttributeId": <string>,
            "Name": <string>,
            "Type": <string>,
            "AllowMulti": <boolean>
        }
    ]
}
Type

Type defines the expected data type for that attribute. Type can be one of the following:

Type

Description

date

<string>, Date formatted as yyyy-mm-dd

string

<string>

org_unit

<string:D2LID>, Org unit ID

user

<string:D2LID>, User ID
AllowMulti

Allows multiple values to be set for this attribute.

Attributes.UserAttributes

For updating and retrieving user attributes. Only attributes that are configured with AllowMulti support will accept multiple values. To remove a user attribute, set the value to be an empty array. Attributes in responses are limited to those that have a value set.

{
    "UserId": <number:D2LID>,
    "Attributes": [
        {
            "AttributeId": <string>,
            "Value": [ <string>, ... ]
        }, ...
    ]
}
Value

Note that to unset an attribute with no value, send an empty array ([]) for this field.

Actions

DELETE /d2l/api/lp/(version)/users/(userId)

Delete a particular user.

Parameters:
Oauth2 Scopes:

users:userdata:delete

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

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

  • 1.34- – Obsolete as of LMS v20.24.1.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all user fields via User Information Privacy.

GET /d2l/api/lp/(version)/users/

Retrieve data for one or more users.

Parameters:
Query Parameters:

  • orgDefinedId (string) – Optional. Org-defined identifier to look for.

  • userName (string) – Optional. User name to look for.

  • externalEmail (string) – Optional. External email address to look for.

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

Oauth2 Scopes:

users:userdata:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. You can use this action in a number of different ways, depending upon the query parameters you provide. If you provide more than one of these parameters, this action selects among them in this order, regardless of the order you provide them in your URL:

  1. orgDefinedId. Find all users that have this org-defined ID string. Fetch the results in a JSON array.

  2. userName. Find the single user that has this user name.

  3. externalEmail. Find all users that exactly match this external email address string. Fetch the results in a JSON array.

  4. bookmark. Use a paged result set to return the results. Fetch the segment of results immediately following your bookmark.

If you provide none of these query parameters, this action behaves as if you’d passed an empty value for the bookmark parameter: it fetches the first segment of results.

Return. If you use this action to find a single user’s data by userName, this route action a single UserData JSON block if successful, and a 404 Not Found if it cannot find a matching user.

If you use this action to find data for the users matching your provided orgDefinedId or externalEmail, this action returns a JSON array of UserData blocks (if only one user matches, the call returns a single-element array), and a 404 Not Found if it cannot find a matching user.

If you do not provide externalEmail, orgDefinedId, or userName parameter, then this action returns a paged result set containing the resulting user data blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing), or an empty result set if it cannot find a matching user.

Note that this action uses the UserId property 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 UserId as the bookmark value.

Note

This action is subject to user privacy controls. If the caller provides no query parameters, this method returns only the users with roles the caller’s role has permission to see, and additionally, will send back values only for the fields that the calling user role has permission to see (like first name, last name, and so forth). If the caller attempts to use the userName or orgDefinedId query parameters on this call, then the caller must have permission to see those fields or the service will reject the call with a 403 (no permission).

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

Retrieve data for a particular user.

Parameters:
Oauth2 Scopes:

users:userdata:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a UserData JSON block.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all user fields via User Information Privacy.

GET /d2l/api/lp/(version)/users/mypronouns

Retrieve the current user’s pronoun choices.

Parameters:
Oauth2 Scopes:

users:own_pronoun:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a Pronouns JSON block for the current user context.

GET /d2l/api/lp/(version)/users/mypronouns/visibility

Retrieve the current user’s pronoun visilbity preference.

Parameters:
Oauth2 Scopes:

users:own_pronoun:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a PronounsVisibility JSON block for the current user context.

GET /d2l/api/lp/(version)/users/(userId)/names

Retrieve legal, preferred, and sort names for a particular user.

Parameters:
Oauth2 Scopes:

users:userdata:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a LegalPreferredNames JSON block.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all user fields via User Information Privacy.

GET /d2l/api/lp/(version)/users/whoami

Retrieve the current user context’s user information.

Parameters:
Oauth2 Scopes:

users:profile:read users:own_profile:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a WhoAmIUser JSON block for the current user context.

Note

The calling user context requires at least one of the users:profile:read or users:own_profile:read scopes.

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

Create a new user entity.

Parameters:
JSON Parameters:
Oauth2 Scopes:

users:userdata:create

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a UserData JSON block for the newly created user, to give you immediate access to the user’s UserId property.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all user fields via User Information Privacy.

POST /d2l/api/lp/(version)/users/batch/

Create a batch of new user entities.

Parameters:
JSON Parameters:

  • newUsers (JSON array of CreateUserData blocks.) – List of new users to create.

Oauth2 Scopes:

users:userdata:create

Status Codes:
API Versions:

  • 1.45+ – Route first appears in LMS v20.23.11.

Input. For this action, provide a simple JSON array of CreateUserData JSON blocks. Note that you may only pass a maximum of 500 users to create at once. The back-end service processes each entry in the list individually, and functionality for each is consistent with the action to create a single user.

Return. This action returns a JSON block containing an array of UserData blocks for all successfully created users, and an array of BatchUserCreateError blocks for any failed user-creation attempts:

{
   "CreatedUsers": [
      { <composite:User.UserData> },
      { <composite:User.UserData> },
      { <composite:User.UserData> }, ...
   ],
   "Errors": [
      { <composite:User.BatchUserCreateError> },
      { <composite:User.BatchUserCreateError> },
      { <composite:User.BatchUserCreateError> }, ...
   ]
}

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all user fields via User Information Privacy.

PUT /d2l/api/lp/(version)/users/mypronouns

Update the current user’s pronoun choices.

Parameters:
JSON Parameters:

  • Pronouns (User.Pronouns) – Updated pronoun choices for current user.

Oauth2 Scopes:

users:own_pronoun:update

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Note that the Pronouns JSON block you send for this action does not include the SystemDefinedPronouns field that will appear in the returned updated structure.

Return. This action returns a Pronouns JSON block to show the updated values for the current user.

PUT /d2l/api/lp/(version)/users/mypronouns/visibility

Update the current user’s pronoun visilbity preference.

Parameters:
JSON Parameters:
Oauth2 Scopes:

users:own_pronoun:update

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a PronounsVisibility JSON block to show the updated pronoun visibility preference for the current user.

PUT /d2l/api/lp/(version)/users/(userId)

Update data for a particular user.

Parameters:
JSON Parameters:
Oauth2 Scopes:

users:userdata:update

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Note that your provided block’s data replaces all the associated user’s data on the service, with one exception: if your UpdateUserData structure’s Pronouns field has a null value, the previously set value will not be touched.

Return. This action returns a UserData JSON block for the user’s updated data.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all user fields via User Information Privacy.

PUT /d2l/api/lp/(version)/users/(userId)/names

Update legal, preferred, and sort name data for a particular user.

Parameters:
JSON Parameters:
Oauth2 Scopes:

users:userdata:update

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Note that your provided block’s data replaces all the associated user’s name data on the service.

Return. This action returns a LegalPreferredNames JSON block for the user’s updated name data.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all user fields via User Information Privacy.

Activation

GET /d2l/api/lp/(version)/users/(userId)/activation

Retrieve a particular user’s activation settings.

Parameters:
Oauth2 Scopes:

users:activation:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a UserActivationData JSON block with the user’s current activation status.

PUT /d2l/api/lp/(version)/users/(userId)/activation

Update a particular user’s activation settings.

Parameters:
JSON Parameters:
Oauth2 Scopes:

users:activation:update

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Integrations

Integration actions involve integrating D2L’s notion of a user record with some external system’s notion of a user, to help unify or bridge across user namespaces in disparate systems.

POST /d2l/api/gae/(version)/linkuser

Link a user to a Google Apps user account.

Parameters:
JSON Parameters:
Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.4.11.

Notifications

These routes give some control over subscription and notification number settings.

DELETE /d2l/api/lp/(version)/notifications/instant/carriers/(carrierId)/subscriptions/(messageTypeId)

Delete the subscription for messages of a particular type, delivered by a particular carrier.

Parameters:

  • version (D2LVERSION) – API version.

  • carrierId (GUID) – Notification carrier ID.

  • messageTypeId (GUID) – Message type ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

DELETE /d2l/api/lp/(version)/notifications/instant/carriers/(carrierId)/subscriptions/(messageTypeId)/users/(userId)

Unsubscribe to notification messages of a particular type, delivered by a particular carrier, for a particular user.

Parameters:

  • version (D2LVERSION) – API version.

  • carrierId (GUID) – Notification carrier ID.

  • messageTypeId (GUID) – Message type ID.

  • userId (D2LID) – User ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

GET /d2l/api/lp/(version)/alerts/user/(userId)

Retrieve a list of alerts for the given user.

Parameters:
Query Parameters:

  • category (ALERTCATEGORY_T) – Optional. The Alert type category or if not present, all categories.

Oauth2 Scopes:

alerts:alerts:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

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

GET /d2l/api/lp/(version)/notifications/instant/carriers/

Retrieve all the carrier channels for delivering notification messages.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Returns. This action returns a JSON array of CarrierOutput data blocks.

GET /d2l/api/lp/(version)/notifications/instant/carriers/(carrierId)/subscriptions/

Retrieve all the current subscriptions for notification messages.

Parameters:

  • version (D2LVERSION) – API version.

  • carrierId (GUID) – Notification carrier ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Returns. This action returns a JSON array of SubscriptionOutput data blocks.

GET /d2l/api/lp/(version)/notifications/instant/carriers/(carrierId)/subscriptions/users/(userId)/

Retrieve all the subscriptions for notification messages for the provided user.

Parameters:

  • version (D2LVERSION) – API version.

  • carrierId (GUID) – Notification carrier ID.

  • userId (D2LID) – User ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Returns. This action returns a JSON array of SubscriptionOutput data blocks.

GET /d2l/api/lp/(version)/notifications/instant/users/(userId)/settings

Retrieve the notification settings for the provided user.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns the UserNotificationSettingsData JSON data block containing the notification settings for your provided user.

PUT /d2l/api/lp/(version)/notifications/instant/carriers/(carrierId)/subscriptions/(messageTypeId)

Subscribe to notification messages of a particular type, delivered by a particular carrier.

Parameters:

  • version (D2LVERSION) – API version.

  • carrierId (GUID) – Notification carrier ID.

  • messageTypeId (GUID) – Message type ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

PUT /d2l/api/lp/(version)/notifications/instant/carriers/(carrierId)/subscriptions/(messageTypeId)/users/(userId)

Subscribe to notification messages of a particular type, delivered by a particular carrier, for a particular user.

Parameters:

  • version (D2LVERSION) – API version.

  • carrierId (GUID) – Notification carrier ID.

  • messageTypeId (GUID) – Message type ID.

  • userId (D2LID) – User ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

PUT /d2l/api/lp/(version)/notifications/instant/users/(userId)/settings

Update the notification settings for the provided user.

Parameters:
JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Passwords

These routes give you some control over a user’s password. Note that the calling user context must have the appropriate permissions for password management for these calls to be useful.

DELETE /d2l/api/lp/(version)/users/(userId)/password

Clear a particular user’s password.

Parameters:
Oauth2 Scopes:

users:password:delete

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

This action deletes a user’s current password.

POST /d2l/api/lp/(version)/users/(userId)/password

Reset a particular user’s password.

Parameters:
Oauth2 Scopes:

users:password:write

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

This action prompts the service to send a password-reset email to the provided user.

PUT /d2l/api/lp/(version)/users/(userId)/password

Update a particular user’s password.

Parameters:
JSON Parameters:
Oauth2 Scopes:

users:password:write

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

The site admin for the back-end service can configure the characteristics for a valid password, and the API doesn’t provide a way to fetch these characteristics; rather than checking for a valid password form on the client side, we suggest that callers notice invalid new passwords based on the 400 error returned (invalid password provided) and then suggest the user should contact the site admin for guidance on how to submit a well-formed password.

Profiles

Profile actions involve a user’s personal profile resource. Note that the UserProfile ProfileIdentifier is used to identify a particular user’s personal profile. You may also use the ProfileIdentifier property found in the User.WhoAmIUser and User.User resources. Unlike D2LID values, a user’s ProfileId is an opaque string value.

DELETE /d2l/api/lp/(version)/profile/myProfile/image

Remove the current user’s profile image.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

DELETE /d2l/api/lp/(version)/profile/(profileId)/image

Remove the profile image from a particular personal profile, by Profile ID.

Parameters:

  • version (D2LVERSION) – API version.

  • profileId (string) – Profile ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

DELETE /d2l/api/lp/(version)/profile/user/(userId)/image

Remove the profile image from a particular personal profile, by User ID.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

GET /d2l/api/lp/(version)/profile/myProfile

Retrieve personal profile information for the current user context.

Parameters:
Oauth2 Scopes:

users:profile:read users:own_profile:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a UserProfile JSON data block.

Note

The calling user context requires at least one of the users:profile:read or users:own_profile:read scopes.

GET /d2l/api/lp/(version)/profile/myProfile/image

Retrieve the current user’s profile image.

Parameters:
Query Parameters:

  • size (integer) – Optional. Desired thumbnail size (height and width in pixels) for profile image.

Oauth2 Scopes:

users:profile:read users:own_profile:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a file stream containing the current user’s profile image. Note that the back-end service may return a profile image larger than your provided size.

Note

The calling user context requires at least one of the users:profile:read or users:own_profile:read scopes.

GET /d2l/api/lp/(version)/profile/(profileId)

Retrieve a particular personal profile, by Profile ID.

Parameters:

  • version (D2LVERSION) – API version.

  • profileId (string) – Profile ID.

Oauth2 Scopes:

users:profile:read users:own_profile:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns the UserProfile JSON data block corresponding to your provided Profile ID.

Note

If the calling user context is not the same as the user that owns the profile, then it requires the users:profile:read scope. Otherwise, it requires at least one of the users:profile:read or users:own-profile:read scopes.

GET /d2l/api/lp/(version)/profile/(profileId)/image

Retrieve a particular profile image, by Profile ID.

Parameters:

  • version (D2LVERSION) – API version.

  • profileId (string) – Profile ID.

Query Parameters:

  • size (integer) – Optional. Desired thumbnail size (height and width in pixels) for profile image.

Oauth2 Scopes:

users:profile:read users:own_profile:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a file stream containing the profile image for the identified profile. Note that the back-end service may return a profile image larger than your provided size.

Note

If the calling user context is not the same as the user that owns the profile, then it requires the users:profile:read scope. Otherwise, it requires at least one of the users:profile:read or users:own-profile:read scopes.

GET /d2l/api/lp/(version)/profile/user/(userId)

Retrieve a particular personal profile, by User ID.

Parameters:
Oauth2 Scopes:

users:profile:read users:own_profile:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns the UserProfile JSON data block containing the personal profile for your provided user.

Note

If the calling user context is not the same as the user that owns the profile, then it requires the users:profile:read scope. Otherwise, it requires at least one of the users:profile:read or users:own-profile:read scopes.

GET /d2l/api/lp/(version)/profile/user/(userId)/image

Retrieve a particular profile image, by User ID.

Parameters:
Query Parameters:

  • size (integer) – Optional. Desired thumbnail size (height and width in pixels) for profile image.

Oauth2 Scopes:

users:profile:read users:own_profile:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a file stream containing the profile image for the identified profile. Note that the back-end service may return a profile image larger than your provided size.

Note

If the calling user context is not the same as the user that owns the profile, then it requires the users:profile:read scope. Otherwise, it requires at least one of the users:profile:read or users:own-profile:read scopes.

POST /d2l/api/lp/(version)/profile/myProfile/image

Update the personal profile image for the current user context.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Provide an uploaded image file using the simple file upload process; the content-disposition part header for the file part should have the name profileImage.

POST /d2l/api/lp/(version)/profile/(profileId)/image

Update the profile image for the identified personal profile, by Profile ID.

Parameters:

  • version (D2LVERSION) – API version.

  • profileId (string) – Profile ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Provide an uploaded image file using the simple file upload process; the content-disposition part header for the file part should have the name profileImage.

POST /d2l/api/lp/(version)/profile/user/(userId)/image

Update the profile image for the identified personal profile, by User ID.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Provide an uploaded image file using the simple file upload process; the content-disposition part header for the file part should have the name profileImage.

PUT /d2l/api/lp/(version)/profile/myProfile

Update the personal profile data for the current user context.

Parameters:
JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Note that your provided block’s data replaces all the associated user’s profile data on the service.

Return. This action returns a UserProfile JSON data block containing the updated personal profile data for the current user.

PUT /d2l/api/lp/(version)/profile/(profileId)

Update a particular personal profile, by Profile ID.

Parameters:

  • version (D2LVERSION) – API version.

  • profileId (string) – Profile ID.

JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Note that your provided block’s data replaces all the associated user’s profile data on the service.

Return. This action returns a UserProfile JSON data block for the updated personal profile.

Roles

GET /d2l/api/lp/(version)/roles/

Retrieve a list of all known user roles.

Parameters:
Oauth2 Scopes:

role:detail:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a JSON array of Role data blocks containing the properties of all user roles that the calling user context has permission to manage.

GET /d2l/api/lp/(version)/roles/(roleId)

Retrieve a particular user role.

Parameters:
Oauth2 Scopes:

role:detail:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a Role JSON data block for the identified user role.

GET /d2l/api/lp/(version)/(orgUnitId)/roles/

Retrieve a list of all the enrolled user roles the calling user can view in an org unit.

Parameters:
Oauth2 Scopes:

role:detail:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a JSON array of Role data blocks containing the properties of all user roles that the calling user context has permission to view and that are currently enrolled in the provided org unit.

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

Create a new role copied from an existing role.

Parameters:
Query Parameters:

  • deepCopyRoleId (D2LID) – Source role to act as template for new role.

JSON Parameters:
Oauth2 Scopes:

role:detail:create

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.4.10.

Input. Provide a RoleCopyData JSON data block containing name to give to the new role. The back-end service creates a new role with this name, and copies over the permissions, properties, and capabiltiies of the role you identify with the deepCopyRoleId query parameter.

Note that this action conservatively copies inter-role capabilities:

  • The new role will not have any capabilities at all upon the old role from which it was created. You will need to manually create such capabilities after the copy (either via API or the standard user interface).

  • The new role will only have some capabilities upon the new role: for example, if the users with the old role had the ability to impersonate other users with the old role, then this impersonation capability will get copies: new role users will be able to impersonate other new role users.

Return. This action returns a Role JSON data block representing the newly-created copy of the role.

Sessions

DELETE /d2l/api/lp/(version)/sessions/(userId)

Terminate all active web sessions for a user.

Parameters:
Oauth2 Scopes:

sessions:session:delete

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Note

This action terminates all active web sessions for a user; however, it does not terminate the access of any active API tokens that third-party applications may have for that user.

PUT /d2l/api/lp/(version)/forceLogout/(userId)

Terminate all active web sessions and revoke API access for a user.

Parameters:
Oauth2 Scopes:

sessions:session:delete

Status Codes:
API Versions:

  • 1.45+ – Route first appears in LMS v20.23.12.

Note

This action terminates all active web sessions for the identified user (as with the previous action); however, as well, this action revokes API access with the identified user as the calling user context for those API actions (by flushing any existing ID/Key access credentials and invalidating any currently active OAuth2 tokens).

1EdTech LIS role configuration

GET /d2l/api/lp/(version)/imsconfig/roles/

Retrieve a list of known LIS Roles.

Parameters:
Query Parameters:

  • lisUrn (string) – Optional. The URN of an LIS role.

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.5.1.

Input. Provide the URN of an LIS role with the lisUrn query parameter to retrieve a known LIS role with a matching URN. If you do not provide a query parameter, you will retrieve all known LIS roles.

Return. This action returns a JSON array of LIS Role data blocks.

GET /d2l/api/lp/(version)/imsconfig/map/roles/

Retrieve mappings between user roles and LIS roles.

Parameters:
Query Parameters:

  • lisUrn (string) – Optional. The URN of an LIS role.

  • d2lId (D2LID) – Optional. The ID of a user role.

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.5.1.

Input. Provide the URN of an LIS role with the lisUrn query parameter to retrieve only the mappings for a known LIS role with a matching URN. Provide the ID of a user role with the d2lId query parameter to retrieve only the mappings for the user role with a matching ID. Combine the lisUrn and d2lId query parameters to retrieve only the mapping between the matching user role and LIS role, if the mapping exists. If you do not provide a query parameter, you will retrieve all role mappings.

Return. This action returns a JSON array of LIS Role Mapping data blocks.

GET /d2l/api/lp/(version)/imsconfig/map/roles/(roleId)

Retrieve mapping between a user roles and LIS roles.

Parameters:
Query Parameters:

  • d2lId (D2LID) – Optional. The ID of a user role.

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.5.1.

Return. This action returns a JSON array of LIS Role Mapping data blocks. An LIS Role Mapping is only included in this list if it maps to the identified user role.

PUT /d2l/api/lp/(version)/imsconfig/map/roles/(roleId)

Map a user role to a set of LIS Roles.

Parameters:
JSON Parameters:

  • mappings (string array) – URNs of LIS roles.

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.5.1.

Input. Provide a JSON array of LIS role URNs to map to the identified user role. This action will map the user role identified by the roleId parameter to any known LIS role with a URN that matches a URN in the list. Any LIS role with a URN that does not match a URN in the list will have any existing mapping to the identified user role removed. All role mappings in the system that do not map the identified user role will remain unchanged.

Return. This action returns a JSON array of LIS Role Mapping data blocks. An LIS Role Mapping is only included in this list if it maps to the identified user role.

Global User Mapping

DELETE /d2l/api/lp/(version)/globalusermapping/users/(userid)

Unassign the global map identifier for a particular user.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to delete mappings.

GET /d2l/api/lp/(version)/globalusermapping/users/(userid)

Retrieves the global map identifier for a particular user.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a MapIdentifier GlobalUserMapping.MapIdentifier.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all mappings.

GET /d2l/api/lp/(version)/globalusermapping/identifiers/(identifier)

Retrieve the D2L user map identifier for a particular user.

Parameters:

  • version (D2LVERSION) – API version.

  • identifier (D2LID) – Global map identifier.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This route returns a simple JSON block containing the D2L user identifier for the identified user:

{
    "UserId": <number:D2LID>
}

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all mappings.

PUT /d2l/api/lp/(version)/globalusermapping/users/(userid)

Assign the global map identifier for a particular user.

Parameters:
JSON Parameters:
Oauth2 Scopes:

globalusermapping:mapping:write

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to create mappings.

User Relationships

DELETE /d2l/api/bfp/(version)/relationships/

Delete parental relationships for given users.

Parameters:
Status Codes:
API Versions:

  • 1.0+ – Route first appears in LMS v20.20.2.

Input. Requires a JSON object in the body of the request. This will indicate which relationships need to be deleted. This route is capable of receiving a batch of up to 1000 user relationships in a JSON Object.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to modify relationships in a user’s entry.

GET /d2l/api/bfp/(version)/relationships/(userId)

Retrieve parental relationships for a particular user.

Parameters:
Status Codes:
API Versions:

  • 1.0+ – Route first appears in LMS v20.20.2.

Return. This route will return a ParentalRelationshipMapping JSON object listing the relationships attached to the userId.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see relationships in a user’s entry.

PUT /d2l/api/bfp/(version)/relationships/

Create relationships for given users.

Parameters:
JSON Parameters:
Status Codes:
API Versions:

  • 1.0+ – Route first appears in LMS v20.20.2.

Input. Requires a JSON object in the body of the request. This will indicate the relationships to be created. This route is capable of receiving a batch of up to 1000 user relationships in a JSON Object.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to modify relationships in a user’s entry.

User Attributes

Note that all the user attribute actions require the back-end service to have enabled the Manager Dashboard or Learning Groups Organization functionality. Also, the calling user must belong to a role that can see user attributes (to retrieve user attribute values) and can see the user management tool (to retrieve attribute schemas and manage attribute values).

DELETE /d2l/api/lp/(version)/attributes/users/(userId)

Unset all attribute values for a user.

Parameters:
Oauth2 Scopes:

attributes:users:delete

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.36-1.42 – Deprecated as of LMS v20.24.1.

GET /d2l/api/lp/(version)/attributes/schemas/

Retrieve user attributes schema definitions.

Parameters:
Oauth2 Scopes:

attributes:schemas:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.36-1.42 – Deprecated as of LMS v20.24.1.

Return. This action returns a UserAttributeDefinitions JSON block describing each of the user attributes.

GET /d2l/api/lp/(version)/attributes/users/(userId)

Retrieve the attributes for a single user.

Parameters:
Oauth2 Scopes:

attributes:users:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.36-1.42 – Deprecated as of LMS v20.24.1.

Return. This action returns a UserAttributes JSON block listing all attributes that have values for the user.

PUT /d2l/api/lp/(version)/attributes/users/(userId)

Update one or more attributes for a single user.

Parameters:
JSON Parameters:
Oauth2 Scopes:

attributes:users:update

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.36-1.42 – Deprecated as of LMS v20.24.1.

Input. This action requires a UserAttributes JSON block in the body of the request containing the attributes that are changing. To unset an attribute set the value to be an empty array.

Return. This action returns a UserAttributes JSON block listing all attributes that have values for the user.

«  IPSIS   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Settings for user accounts  »