Attributes¶

Demographics.DemographicsDataType¶

{
    "DataTypeId": <string:GUID>,
    "DataTypeName": <string>,
    "DisplayName": <string>
}

Demographics.DemographicsEntry¶

{
    "Name":<string>,
    "Values": [
        <string>,
        <string>, ...
    ]
}

Demographics.DemographicsEntryData¶

{
    "EntryValues": [  // Array of DemographicsEntry blocks
        {
            "Name": <string>,
            "Values": [
                <string>,
                <string>, ...
            ]
        },
        { <composite:DemographicsEntry> }, ...
    ]
}

Demographics.DemographicsUserEntryData¶

{
    "UserId": <number:D2LID>,
    "EntryValues": [  // Array of DemographicsEntry blocks
        {
            "Name": <string>,
            "Values": [
                <string>,
                <string>, ...
            ]
        },
        { <composite:DemographicsEntry> }, ...
    ]
}

Demographics.DemographicsField¶

Create. When you use actions that define a new Demographics Field for the service, you should provide a block that looks like this:

{
    "Name": <string>,
    "Description": <string>,
    "DataTypeId": <string:GUID>
}

Fetch. When you use actions that retrieve Demographics Field information, the service provides a block like this:

{
    "FieldId": <number:D2LID>,
    "Name": <string>,
    "Description": <string>,
    "DataTypeId": <string:GUID>
}

Update. When you use actions that update existing Demographics Field information, you should provide a block that looks like this:

{
    "Name": <string>,
    "Description": <string>
}

Actions¶

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

Delete one or more of a particular user’s associated demographics entries.

Parameters:

• version (D2LVERSION) – API version.

• userId (D2LID) – User ID.

Query Parameters:

• entryIds (CSV) – Optional. Specific entry IDs for demographic entries to delete.

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to manage demographics entries.

• 404 Not Found – No such user.

• 429 Too Many Requests – API call-rate limit exceeded.

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 two ways:

• If you provide a list of entry IDs as a query parameter, the service seeks to delete only the entries it can match with IDs from your provided list.

• If you do not provide the entryIds query parameter, the service deletes all the entries associated with the user you specify.

GET /d2l/api/lp/(version)/demographics/orgUnits/(orgUnitId)/users/¶

Retrieve all the demographics entries for all users enrolled in a particular org unit.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

Query Parameters:

• fieldIds (CSV of D2LIDs) – Optional. Demographic field IDs.

• roleIds (CSV of D2LIDs) – Optional. User role IDs.

• userIds (CSV of D2LIDs) – Optional. User IDs.

• search (string) – Optional. Search string to look for in the demographic field values.

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

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to view demographics entries.

• 404 Not Found – No more data sets to view after provided bookmark, or no matching entries found.

• 429 Too Many Requests – API call-rate limit exceeded.

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. This actions retrieves all the demographics entries for all the users enrolled in a particular org unit; this could be a large data-set, and therefore you should use one or more of the query parameters to filter the results–you can restrict the results to:

• Only those entries that match a list of specific demographics fields (identified by field ID)

• Only those entries that match users with belonging to one or more user roles (identified by role ID)

• Only those entries associated with one or more users (identified by user ID)

• Only those entries that match a given search string

The service applies these filters cumulatively, meaning that it will return only those users who match all of the filters. However, when using a list of IDs in any filter, users who match any of the supplied IDs will match that filter. This means that if you construct a query with a list of roleIds the service will return users who have any of the specified roles; if you construct a query with a search string, a single role ID, and a list of user IDs, the query will return the users (a) with one of the given user IDs, (b) the given role, and (c) a field matching the search string.

You can also use the 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 demographics entry blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).

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

Retrieve all the demographics entries for a specific user within a particular org unit.

Parameters:

• version (D2LVERSION) – API version.

• orgUnitId (D2LID) – Org unit ID.

• userId (D2LID) – User ID.

Query Parameters:

• fieldIds (CSV of D2LIDs) – Optional. Demographic field IDs.

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to view demographics entries.

• 404 Not Found – No such user, or no matching entries found.

• 429 Too Many Requests – API call-rate limit exceeded.

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. This action retrieves all the demographics entries for a user within a particular org unit. You can use the fieldIds query parameter to further filter the results and restrict them to only those entries that match your list of specific demographics fields (identified by field ID).

Return. This action returns a DemographicsUserEntryData JSON block containing all the matching demographics entries for your query.

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

Retrieve all the demographics entries for all users, and optionally filter the results.

Parameters:

• version (D2LVERSION) – API version.

Query Parameters:

• fieldIds (CSV of D2LIDs) – Optional. Demographic field IDs.

• roleIds (CSV of D2LIDs) – Optional. User role IDs.

• userIds (CSV of D2LIDs) – Optional. User IDs.

• search (string) – Optional. Search string to look for in the demographic field values.

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

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to view demographics entries.

• 404 Not Found – No more data sets to view after provided bookmark, or no matching entries found.

• 429 Too Many Requests – API call-rate limit exceeded.

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. This actions retrieves all the demographics entries for all users; this could be a very large data-set, and therefore you should use one or more of the query parameters to filter the results–you can restrict the results to:

• Only those entries that match a list of specific demographics fields (identified by field ID)

• Only those entries that match users with belonging to one or more user roles (identified by role ID)

• Only those entries associated with one or more users (identified by user ID)

• Only those entries that match a given search string

The service applies these filters cumulatively, meaning that it will return only those users who match all of the filters. However, when using a list of IDs in any filter, users who match any of the supplied IDs will match that filter. This means that if you construct a query with a list of roleIds the service will return users who have any of the specified roles; if you construct a query with a search string, a single role ID, and a list of user IDs, the query will return the users (a) with one of the given user IDs, (b) the given role, and (c) a field matching the search string.

You can also use the 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 demographics entry blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).

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

Retrieve all the demographics entries for a single user.

Parameters:

• version (D2LVERSION) – API version.

• userId (D2LID) – User ID.

Query Parameters:

• fieldIds (CSV of D2LIDs) – Optional. Comma-separated list of demographic field IDs.

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

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to view demographics entries.

• 404 Not Found – No such user, or no matching entries found.

• 429 Too Many Requests – API call-rate limit exceeded.

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. This action retrieves all the demographics entries for a user across all the user’s org unit enrollments. You can use the fieldIds query parameter to further filter the results and restrict them to only those entries that match your list of specific demographics fields (identified by field ID).

Return. This action returns a DemographicsUserEntryData JSON block containing all the matching demographics entries for your query.

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

Update the demographics entries for a single user.

Parameters:

• version (D2LVERSION) – API version.

• userId (D2LID) – User ID.

JSON Parameters:

• DemographicsEntryData (Demographics.DemographicsEntryData) – Updated demographics entry data for user.

Status Codes:

• 200 OK – Action succeeded.

• 403 Forbidden – No permission to manage demographics entries.

• 404 Not Found – No such user.

• 429 Too Many Requests – API call-rate limit exceeded.

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. This action uses your provided block’s data to replace all the user’s demographics entries; therefore, we recommend that you first fetch all the entries for the user so you can be sure to update the complete set of entries.

Return. This action returns a DemographicsUserEntryData JSON block containing the user’s updated entries.

Note

You can use this action and provide an empty set of entries. This effectively removes all the demographics entries currently associated with the user. Future calls to retrieve the user’s entries will return 404 results until you once again use this call to provide some demographics entries for the user.