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.Text, Footer.Text: These RichText properties can be displayed, or hidden, upon presentation of the survey to those taking it (based on the value of their associated 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
}

Description.Text, Submission, Footer.Text: Note that these properties all use the RichTextInput structure type.
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 structure.

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 of SurveyReadData 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

userId (D2LID) – Optional. Retrieve access for a single user.
roleId (D2LID) – Optional. Retrieve access for users with the given role.

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 resulting UserAccess 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 of SurveyAttemptData 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 of SurveyCategoryReadData 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 of QuestionData 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 resulting SpecialAccessUserData 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.