Developer Platform (April 2020)

Surveys

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

Contents

Attributes

Surveys

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
}
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.

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
}
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.

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

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

surveys:surveys:read

Status Codes
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
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.

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

Create a new surveys belonging to an org unit.

Parameters
JSON Parameters
Oauth2 Scopes

surveys:surveys:read surveys:surveys:create

Status Codes
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 new surveys 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.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 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.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
Oauth2 Scopes

surveys:surveys:read

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

surveys:surveys:read surveys:surveys:create

Status Codes
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
Oauth2 Scopes

surveys:surveys:update surveys:surveys:write

Status Codes
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).

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