Contents
Attributes¶
Survey Data¶
- ATTEMPTSALLOWEDTYPE_T
Number of attempts allowed for a survey can be accommodated in several ways. We use the term ATTEMPTSALLOWEDTYPE_T to stand in for an appropriate integer type.
Attempts Allowed Type
Value
Unlimited
0
Editable
1
Limited
2
-
Surveys.
SurveyReadData
¶ When the service sends you information about a survey, it will send back a JSON structure like this:
{ "SurveyId": <number:D2LID>, "Name": <string>, "SortOrder": <number>, "HasInstantFeedback": <boolean>, "IsAnonymous": <boolean>, "Description": { "Text": { <composite:RichText> }, "IsDisplayed": <boolean> }, "Submission": { <composite:RichText> }, "Footer": { "Text": { <composite:RichText> }, "IsDisplayed": <boolean> }, "IsActive": <boolean>, "StartDate": <string:UTCDateTime>|null, "EndDate": <string:UTCDateTime>|null, "DisplayInCalendar": <boolean>, "UserResponses": { "AttemptsAllowedTypeId": <number:ATTEMPTSALLOWEDTYPE_T>, "NumberOfAttempts": <number>|null }, "CategoryId": <number>|null, "PreventMovingBackwards": <boolean>, // Added with LE API v1.43 "Shuffle": <boolean>, // Added with LE API v1.43 "ActivityId": <string>|null, // Added with LE API v1.43 "AllowOnlyUsersWithSpecialAccess": <boolean> // Added with LE API v1.47 }
- UserResponses
If the AttemptsAllowedTypeId property is 0, then the NumberOfAttemptsAllowed property will be null; if AttemptsAllowedTypeId is 1, then NumberOfAttemptsAllowed will be 1; if AttemptsAllowedTypeId is 2, then NumberOfAttemptsAllowed will contain the number of attempts allowed (default value is 1).
- Description, SubmissionMessage, and Footer
These rich text properties can be displayed, or hidden, upon presentation of the survey to those taking it (based on the value of the IsDisplayed property).
- PreventMovingBackwards
When true, prevents the survey taker from paging backwards in this survey.
- Shuffle
When true, the order of the questions is randomized.
- AllowOnlyUsersWithSpecialAccess
When true, allow only users with special access to see this survey.
-
Surveys.
SurveyWriteData
¶ When creating or updating a survey, use a structure like this:
{ "Name": <string>, "HasInstantFeedback": <boolean>, "IsAnonymous": <boolean>, "Description": { "Text": { <composite:RichTextInput> }, "IsDisplayed": <boolean> }, "Submission": <composite:RichTextInput>, "Footer": { "Text": { <composite:RichTextInput> }, "IsDisplayed": <boolean> }, "IsActive": <boolean>, "StartDate": <string:UTCDateTime>|null, "EndDate": <string:UTCDateTime>|null, "DisplayInCalendar": <boolean>, "UserResponses": { "AttemptsAllowedTypeId": <number:ATTEMPTSALLOWEDTYPE_T>, "NumberOfAttempts": <number>|null }, "CategoryId": <number>|null, "PreventMovingBackwards": <boolean>, // Added with LE API v1.43 "Shuffle": <boolean>, // Added with LE API v1.43 "AllowOnlyUsersWithSpecialAccess": <boolean> // Added with LE API v1.47 }
- UserResponses
If the AttemptsAllowedTypeId property is 0, then the NumberOfAttemptsAllowed property will be null; if AttemptsAllowedTypeId is 1, then NumberOfAttemptsAllowed will be 1; if AttemptsAllowedTypeId is 2, then NumberOfAttemptsAllowed will contain the number of attempts allowed (default value is 1).
- PreventMovingBackwards
When true, prevents the survey taker from paging backwards in this survey.
- Shuffle
When true, the order of the questions is randomized.
- AllowOnlyUsersWithSpecialAccess
When true, allow only users with special access to see this survey.
Note
The AllowOnlyUsersWithSpecialAccess property is ignored (but still required with some value) if the calling user does not have permission to add special access to surveys.
Survey Attempts¶
-
Surveys.
SurveyAttemptData
¶ When the service sends you information about a survey attempt, it will send back a JSON structure like this:
{ "AttemptId": <number:D2LID>, "SurveyId": <number:D2LID>, "UserId": <number:D2LID>|null, "AttemptNumber": <number>, "Started": <string:UTCDateTime>, "Completed": <string:UTCDateTime>|null, }
- UserId
The ID of the user that this survey attempt is for or null if the survey is anonymous.
- Started
The date and time that this survey attempt was started.
- Completed
The date and time that this survey attempt was completed or null if it is in progress.
Survey Categories¶
-
Surveys.
SurveyCategoryData
¶ When creating or updating a survey category, use this structure.
{ "Name": <string>, "SortOrder": <number> }
-
Surveys.
SurveyCategoryReadData
¶ When the service sends you information about a survey category, it will send back a JSON structure like this:
{ "CategoryId": <number:D2LID>, "Name": <string>, "SortOrder": <number> }
Questions¶
-
SurveyQuestion.
QuestionData
¶ Survey questions information is identical to the
quiz questions
.
Special Access¶
-
Surveys.
SpecialAccessData
¶ When retrieving or updating a user’s special access for a survey, use a structure like this:
{ "StartDate": <string:UTCDateTime>|null, "EndDate": <string:UTCDateTime>|null }
Note
StartDate must be less than EndDate if both properties are non-null.
StartDate and EndDate both set to null means that no date restrictions are applied to the user.
-
Surveys.
SpecialAccessUserData
¶ When retrieving special access for a survey, the service will return a structure like this:
{ "UserId":<number:D2LID>, "SpecialAccess": <composite:SpecialAccessData> }
Actions¶
Surveys¶
-
DELETE
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)¶ Delete a survey.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
- Oauth2 Scopes
surveys:surveys:delete
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to delete surveys.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.42+ – Route first appears in LMS v20.20.3.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
¶ Retrieve the surveys belonging to an org unit.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Oauth2 Scopes
surveys:surveys:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to see surveys.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.41+ – Route first appears in LMS v20.20.2.
Return. This action returns an
ObjectListPage
JSON block containing a list ofSurveyReadData
JSON blocks belonging to the org unit.Note
This action only returns the survey objects that the calling user context has permission to see. If the calling user has no permission to see any survey objects, this action returns an empty result page.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)¶ Retrieve a survey.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
- Oauth2 Scopes
surveys:surveys:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to see surveys.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.41+ – Route first appears in LMS v20.20.2.
Return. This action returns a
SurveyReadData
JSON block containing the properties of the survey.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)/access/
¶ Retrieve a list of users with access to a specified survey.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
- Query Parameters
- Oauth2 Scopes
surveys:access:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to see and manage surveys for this org unit, see classlist, view user enrollment.
404 Not Found – Survey ID not found in provided org unit, or org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.46+ – Route first appears in LMS v20.20.7.
Return. This action returns a
object list page
containing the resultingUserAccess
blocks.
-
POST
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
¶ Create a new survey belonging to an org unit.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- JSON Parameters
SurveyWriteData (
SurveyWriteData
) – Survey data for the new survey.
- Oauth2 Scopes
surveys:surveys:read surveys:surveys:create
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to see or manage surveys.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.42+ – Route first appears in LMS v20.20.3.
Return. This action returns a
SurveyReadData
JSON block containing the properties of your new survey.
-
PUT
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)¶ Update a survey belonging to an org unit.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
- JSON Parameters
SurveyWriteData (
SurveyWriteData
) – New survey data for survey.
- Oauth2 Scopes
surveys:surveys:read surveys:surveys:update
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Survey is shared and cannot be restricted for special access.
403 Forbidden – No permission to see or update surveys.
404 Not Found – Org unit or survey not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.42+ – Route first appears in LMS v20.20.3.
Return. This action returns a
SurveyReadData
JSON block containing the properties of your updated survey.
Survey Attempts¶
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)/attempts/
¶ Retrieve a list of attempts for a survey.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
- Query Parameters
userId (D2LID) – Optional. Retrieve attempts for a single user.
- Oauth2 Scopes
surveys:attempts:read
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Survey is anonymous and cannot filter attempts by user ID
403 Forbidden – No permission to view survey results.
404 Not Found – Org unit or survey not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.45+ – Route first appears in LMS v20.20.6.
Return. This action returns an
ObjectListPage
JSON block containing a list ofSurveyAttemptData
belonging to the survey.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)/attempts/
(attemptId)¶ Retrieve a survey attempt.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
attemptId (D2LID) – Attempt ID.
- Oauth2 Scopes
surveys:attempts:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view survey results.
404 Not Found – Org unit, survey, or attempt not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.45+ – Route first appears in LMS v20.20.6.
- Return. This action returns a
SurveyAttemptData
JSON block containing the properties of your identified survey attempt.
Survey Categories¶
-
DELETE
/d2l/api/le/
(version)/
(orgUnitId)/surveys/categories/
(categoryId)¶ Delete the survey category belonging to an org unit.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
categoryId (D2LID) – Category ID.
- Oauth2 Scopes
surveys:surveys:delete
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to delete surveys.
404 Not Found – Category not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.42+ – Route first appears in LMS v20.20.3.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/categories/
¶ Retrieve the survey categories belonging to an org unit.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Oauth2 Scopes
surveys:surveys:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view surveys.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.42+ – Route first appears in LMS v20.20.3.
Return. This action returns an
ObjectListPage
JSON block containing a list ofSurveyCategoryReadData
belonging to the org unit.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/categories/
(categoryId)¶ Retrieve the survey category belonging to an org unit.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
categoryId (D2LID) – Category ID.
- Oauth2 Scopes
surveys:surveys:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view surveys.
404 Not Found – Category not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.42+ – Route first appears in LMS v20.20.3.
Return. This action returns a
SurveyCategoryReadData
JSON block containing the properties of your survey category.
-
POST
/d2l/api/le/
(version)/
(orgUnitId)/surveys/categories/
¶ Create a new survey category.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- JSON Parameters
categoryData (
SurveyCategory Data
) – New survey category data.
- Oauth2 Scopes
surveys:surveys:read surveys:surveys:create
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to view and manage surveys.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.42+ – Route first appears in LMS v20.20.3.
Return. This action returns a
SurveyCategoryReadData
JSON block containing the properties of your survey category.
-
PUT
/d2l/api/le/
(version)/
(orgUnitId)/surveys/categories/
(categoryId)¶ Update a survey category.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
categoryId (D2LID) – Survey Category ID.
- JSON Parameters
categoryData (
SurveyCategoryData
) – Updated data for the survey category.
- Oauth2 Scopes
surveys:surveys:update surveys:surveys:write
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to update survey category.
404 Not Found – Org unit not found, or survey category not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.42+ – Route first appears in LMS v20.20.3.
Return. This action returns a
SurveyCategoryReadData
JSON block containing the updated data for your survey category.
Questions¶
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)/questions/
¶ Retrieve all the questions in a survey.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
- Oauth2 Scopes
surveys:surveys:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to see survey or add/remove survey questions.
404 Not Found – Org unit not found, or survey not found.
- API Versions
1.43+ – Route first appears in LMS v20.20.4
Return. This action returns an
ObjectListPage
JSON block containing a list ofQuestionData
belonging to the survey you specified, blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).
Special Access¶
-
DELETE
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)/specialaccess/
(userId)¶ Remove survey special access for a user.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
userId (D2LID) – User ID.
- Oauth2 Scopes
surveys:surveys:delete
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to see surveys, manage surveys, edit survey properties, or add special access.
404 Not Found – Org unit, survey, or user with special access not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.48+ – Route first appears in LMS v20.20.9.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)/specialaccess/
¶ Retrieve special access rules in a survey.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
- Oauth2 Scopes
surveys:surveys:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to see surveys, manage surveys.
404 Not Found – Org unit or survey not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.48+ – Route first appears in LMS v20.20.9.
Return. This action returns a
object list page
containing the resultingSpecialAccessUserData
blocks.
-
GET
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)/specialaccess/
(userId)¶ Retrieve a user’s special access rule for a survey.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
userId (D2LID) – User ID.
- Oauth2 Scopes
surveys:surveys:read
- Status Codes
200 OK – Action succeeded.
403 Forbidden – No permission to see surveys, manage surveys.
404 Not Found – Org unit, survey, or user with special access not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.48+ – Route first appears in LMS v20.20.9.
Return. This action returns a
SpecialAccessData
JSON block.
-
PUT
/d2l/api/le/
(version)/
(orgUnitId)/surveys/
(surveyId)/specialaccess/
(userId)¶ Create or update a special access rule for a user and survey.
- Parameters
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
surveyId (D2LID) – Survey ID.
userId (D2LID) – User ID.
- JSON Parameters
SpecialAccessData (
SpecialAccessData
) – Special access data.
- Oauth2 Scopes
surveys:surveys:update
- Status Codes
200 OK – Action succeeded.
400 Bad Request – Invalid special access data provided.
403 Forbidden – No permission to see surveys, manage surveys, edit survey properties, or add special access.
404 Not Found – Org unit, survey, or user not found, or, user not allowed to receive special access.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions
1.48+ – Route first appears in LMS v20.20.9.