Developer Platform (July 2017)

Demographics (data types, fields, users and org units)

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

Contents

The Demographics actions let an organization associate specific kinds of demographic data with users, and provides access to that data to third-parties. The Demographics functionality is built on three layers of entities:

Callers can use these routes to fetch, create, update, and delete demographics fields and entries. However, the back-end service will support a constrained set of data types, not modifiable by callers: therefore, callers should retrieve the list of all types a service does support to know what kinds of data typing constraints they’re operating with.

Note

Note that the demographics data for a user gets associated with the user’s record, and not with the user’s enrollment within a particular org unit. The calls to retrieve data with an org unit specified within the route are merely convenience routes to narrow down the list of possible users to the particular org unit: demographics fields available for user Id 12345 enrolled within one course will also be available for that same user enrolled (and retrieved) through another course.

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:
Query Parameters:
 
  • entryIds (CSV) – Optional. Specific entry IDs for demographic entries to delete.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

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:
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.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

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:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

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:
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.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

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:
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:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

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:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

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.

Fields

DELETE /d2l/api/lp/(version)/demographics/fields/(fieldId)

Delete a single demographic field, provided it has no associated entries.

Parameters:
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Note

This action will only delete a demographic field that has no associated entries. If you want to delete a field that does have existing entries associated with users, then you must first delete each of those entries, and then delete the field itself.

GET /d2l/api/lp/(version)/demographics/fields/

Retrieve the list of all demographics fields.

Parameters:
Query Parameters:
 
  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to see demographics entries.
  • 404 Not Found – No more data sets to view after provided bookmark, or no demographics fields found.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. You can 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 demographic field blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing). Note that this action uses a FieldId property as the paging control value. You can fetch the segment of results following any demographics field’s entry in the data set by passing that field’s FieldId as the bookmark value.

GET /d2l/api/lp/(version)/demographics/fields/(fieldId)

Retrieve a single demographic field.

Parameters:
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns the fetch form of a DemographicsField JSON block.

POST /d2l/api/lp/(version)/demographics/fields/

Create a new demographic field.

Parameters:
Status Codes:
JSON Parameters:
 
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns the fetch form of a DemographicsField JSON block containing the data for the newly created field.

PUT /d2l/api/lp/(version)/demographics/fields/(fieldId)

Update a single demographic field.

Parameters:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns the fetch form of a DemographicsField JSON block containing the data for the newly updated field.

Data types

GET /d2l/api/lp/(version)/demographics/dataTypes/

Retrieve the list of all demographics data types.

Parameters:
Query Parameters:
 
  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to see demographics entries.
  • 404 Not Found – No more data sets to view after provided bookmark, or no data types yet defined.
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. You can 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 demographic data type blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing). Note that this action uses a DataTypeId property as the paging control value. You can fetch the segment of results following any demographics data type’s entry in the data set by passing that data type’s DataTypeId as the bookmark value.

GET /d2l/api/lp/(version)/demographics/dataTypes/(dataTypeId)

Retrieve a single demographic data type.

Parameters:
  • version (D2LVERSION) – API version.
  • dataTypeId (GUID) – Data Type ID.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a DemographicsDataType JSON block.

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