Developer Platform (October 2022)

Surveys

«  Quizzes   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Assessments and rubrics  »

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>,
    "Shuffle": <boolean>,
    "ActivityId": <string>|null,
    "AllowOnlyUsersWithSpecialAccess": <boolean>
}
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>,
    "Shuffle": <boolean>,
    "AllowOnlyUsersWithSpecialAccess": <boolean>
}
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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.42-1.50 – Deprecated as of LMS v20.22.1.

GET /d2l/api/le/(version)/(orgUnitId)/surveys/

Retrieve the surveys belonging to an org unit.

Parameters:
Oauth2 Scopes:

surveys:surveys:read

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.41-1.50 – Deprecated as of LMS v20.22.1.

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.46-1.50 – Deprecated as of LMS v20.22.1.

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:
JSON Parameters:
Oauth2 Scopes:

surveys:surveys:read surveys:surveys:create

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.42-1.50 – Deprecated as of LMS v20.22.1.

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:
Oauth2 Scopes:

surveys:surveys:read surveys:surveys:update

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.42-1.50 – Deprecated as of LMS v20.22.1.

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.45-1.50 – Deprecated as of LMS v20.22.1.

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.45-1.50 – Deprecated as of LMS v20.22.1.

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.42-1.50 – Deprecated as of LMS v20.22.1.

GET /d2l/api/le/(version)/(orgUnitId)/surveys/categories/

Retrieve the survey categories belonging to an org unit.

Parameters:
Oauth2 Scopes:

surveys:surveys:read

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.42-1.50 – Deprecated as of LMS v20.22.1.

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.42-1.50 – Deprecated as of LMS v20.22.1.

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:
JSON Parameters:
Oauth2 Scopes:

surveys:surveys:read surveys:surveys:create

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.42-1.50 – Deprecated as of LMS v20.22.1.

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:
Oauth2 Scopes:

surveys:surveys:update surveys:surveys:write

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.42-1.50 – Deprecated as of LMS v20.22.1.

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.51+ – Route first appears in LMS v20.21.1.

  • 1.43-1.50 – Deprecated as of LMS v20.22.1.

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.48-1.50 – Deprecated as of LMS v20.22.1.

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.48-1.50 – Deprecated as of LMS v20.22.1.

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:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.48-1.50 – Deprecated as of LMS v20.22.1.

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:
Oauth2 Scopes:

surveys:surveys:update

Status Codes:
API Versions:

  • 1.51+ – Route first appears in LMS v20.21.1.

  • 1.48-1.50 – Deprecated as of LMS v20.22.1.

«  Quizzes   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Assessments and rubrics  »