Enables the retrieval of survey information for a given survey. This is survey definition data and NOT survey response data; to get survey response data you must use the Report end-points.

Dates will be provided in ISO 8601 format. For example, 2012-02-13T01:34:52Z will be used instead of February 2, 2012 1:34:52a UTC. This can be parsed in Java using the SimpleDateFormat and this pattern "yyyy-MM-dd'T'HH:mm:ss'Z".
new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z").format(new Date());

Resource URL

https://api.ideasystem.org/v1/survey/1234

Parameters

survey_id

required

Example: /v1/survey/1234

A unique survey identifier in the IDEA system.

Response

The response will be an HTTP 200 along with a JSON body that contains the surveys that match the given query parameters. If an error occurs with the parameters that are passed in, an HTTP 400 will be returned along with an error message in a JSON body. All other errors will return an HTTP 500 (Internal Server Error).

Response Parameters (JSON Body)

Example: "id": 1

A unique survey identifier in the IDEA system.

group_id

Example: "group_id": 1

A unique survey group identifier in the IDEA system.

src_name

Example: "src_name": "IOL3"

The source name this survey is associated with, i.e., where it came from.

src_id

Example: "src_id": "1"

This is the survey ID provided when this survey first entered the IDEA system. It is expected to be a unique survey identifier in the system where this survey originated. If this survey is ever re-transferred into the IDEA system, it should use the same ID.

src_group_id

Example: "src_group_id": "1"

This is the survey group ID provided when this survey first entered the IDEA system. It is expected to be a unique group identifier in the system where this survey originated. If this survey is ever re-transferred into the IDEA system, it should use the same ID.

institution_id

Example: "institution_id": 1

A unique institution identifier in the IDEA system. This matches up with the IDs that can be retrieved from the /institutions end-point. It allows the user of this data to look-up the meta-data about the institution this survey is associated with (name, FICE, etc.).

institution_name

Example: "institution_name": "IDEA Center"

Institution name in the IDEA system This matches up with the names that can be retrieved from the /institutions end-point.

year

Example: "year": 2012

Year this survey was administered.

term

Example: "term": "Fall"

Term in which this survey was administered. For example, it might be Spring, January, or Q1.

includes_gap_analysis

Example: "includes_gap_analysis": true

True if this survey includes gap analysis and false otherwise.

demographic_group_ids

Example: "demographic_group_ids": []

An array of demographic group IDs that were selected for use in this survey. The details on the demographic group can be retrieved using the /demographic_groups end-point. Optional.

end_date

Example: "end_date": "2012-09-06T00:00:00Z"

The latest of the information and rater form end dates.

start_date

Example: "start_date": "2012-09-06T00:00:00Z"

The earliest of the information and rater form start dates.

creation_date

Example: "creation_date": "2012-09-06T00:00:00Z"

The date this survey was created.

course

Example: "course": { ... }

Defines the course information. This will include details like the time and days that the class meets, the course name and number, and a local code used for grouping in reports.

course.title

Example: "title": "Intro to Biology"

Defines the course title.

course.number

Example: "number": "101"

Defines the course number.

course.local_code

Example: "local_code": "01 02 345

The local code provides a way to group related surveys. This will be useful in grouping data later in group summary reports. This is free-form so any type of text can be used.

course.days

Example: "days": "MWF"

Defines the days that the course meets. This is free-form so any type of days can be used. For example, it might meet on Monday, Wednesday, and Friday and specified as "MWF" or "Mon, Wed, Fri".

course.time

Example: "time": "14:30"

Defines the time that the course meets. This is free-form so any type of time can be used.

course.src_id

Example: "src_id": "01-23-456-789"

Provides a mapping from to the source system's course. This is optional.

course.subject

Example: "subject": "BIO"

The course's subject. For example, BIO in BIO 101. This is optional.

course.type

Example: "type": "undergraduate"

The type of course. This is optional but if provided will be one of the following: Undergraduate (Undergrad, U), Graduate (Grad, G), Professional (Prof, P), Developmental (Dev, D), Undergraduate Transferable (Undergraduate-Transferable, UT), or Undergraduate Non Transferable (Undergraduate-Non-Transferable, UNT).

course.delivery_mode

Example: "delivery_mode": "online"

The delivery mode of the course. This is optional but if provided will be one of the following: Online (OL, on line, on_line, on-line), Face to Face (face-to-face, facetoface, F2F), or Hybrid.

course.term_type

Example: "term_type": "semester"

The term type this course is part of. This is optional but if provided will be one of the following: Semester, Trimester, Quarter, Intersession, Module, or Annual.

course.start_date

Example: "start_date": "2016-01-01"

The date the course starts on in the form of yyyy-MM-dd where yyyy is the 4 digit year (e.g., 2017), MM is the 2 digit month (e.g, 01), and dd is the 2 digit day of month (e.g., 24).

course.end_date

Example: "end_date": "2017-01-01"

The date the course ends on in the form of yyyy-MM-dd where yyyy is the 4 digit year (e.g., 2017), MM is the 2 digit month (e.g, 05), and dd is the 2 digit day of month (e.g., 10).

course.section

Example: "section": { ... }

When a survey is associated with only 1 section of a course, this portion might be populated to provide details on that course section.

course.section.title

Example: "title": "Intro to Biology"

Defines the course section title.

course.section.number

Example: "number": "101"

Defines the course section number.

course.section.src_id

Example: "src_id": "01-23-456-789"

Provides a mapping from to the source system's course section. This is optional.

course.section.subject

Example: "subject": "BIO"

The course section's subject. For example, BIO in BIO 101. This is optional.

course.section.start_date

Example: "start_date": "2016-01-01"

The date the course section starts on in the form of yyyy-MM-dd where yyyy is the 4 digit year (e.g., 2017), MM is the 2 digit month (e.g, 01), and dd is the 2 digit day of month (e.g., 24).

course.section.end_date

Example: "end_date": "2017-01-01"

The date the course section ends on in the form of yyyy-MM-dd where yyyy is the 4 digit year (e.g., 2017), MM is the 2 digit month (e.g, 05), and dd is the 2 digit day of month (e.g., 10).

course.section.delivery_mode

Example: "delivery_mode": "online"

The delivery mode of the course section. This is optional but if provided will be one of the following: Online (OL, on line, on_line, on-line), Face to Face (face-to-face, facetoface, F2F), or Hybrid.

course.section.days

Example: "days": "MWF"

Defines the days that the course section meets. This is free-form so any type of days can be used. For example, it might meet on Monday, Wednesday, and Friday and specified as "MWF" or "Mon, Wed, Fri".

course.section.time

Example: "time": "14:30"

Defines the time that the course section meets. This is free-form so any type of time can be used.

course.section.local_code

Example: "local_code": "01 02 345

The local code provides a way to group related surveys. This will be useful in grouping data later in group summary reports. This is free-form so any type of text can be used.

info_form

Example: "info_form": { ... }

Contains details about the survey form the survey subject fills out. For the Administrator and Chair system, this will include any gap analysis questions. For the Student Ratings system, this will include objectives and other information about the course.

info_form.id

Example: "id": 123

A unique survey form identifier in the IDEA system. This matches up with the IDs that can be retrieved from the /forms end-point. It allows the user of this data to look-up the meta-data about the form including the questions.

info_form.startDate

Example: "startDate": "2012-09-06T00:00:00Z"

The date this survey first becomes available to respondents.

info_form.endDate

Example: "endDate": "2012-09-06T23:59:59Z"

The date this survey becomes unavailable to respondents.

info_form.discipline_code

Example: "discipline_code": 1611

The discipline code for the information form. This value is optional.

info_form.respondents

Example: "respondents": [ ... ]

An array of survey subject information. More than likely, this will be a single survey subject.

info_form.respondents.first_name

Example: "first_name": "Bob"

The first name of info form respondent; this is the survey subject (e.g., faculty member, administrator, chair).

info_form.respondents.middle_name

Example: "middle_name": "Lee"

The middle name of info form respondent; this is the survey subject (e.g., faculty member, administrator, chair).

info_form.respondents.last_name

Example: "last_name": "Smith"

The last name of info form respondent; this is the survey subject (e.g., faculty member, administrator, chair).

info_form.respondents.title

Example: "title": "Dean of Medicine"

The title of info form respondent; this is the survey subect's title (e.g., Chair, Professor, Provost).

info_form.respondents.position_code

Example: "position_code": 1234

The position code of this survey subject. This is used in the Feedback System for Administrators to denote the type of Administrator this person is. For example, a Dean of Agriculture would select position code 1201 where 1201 is the ID of the position code.

info_form.respondents.src_id

Example: "src_id": "9876-5432-10"

The survey subject's source ID; this is optional but if provided gives a way to map the survey data to a 3rd party system.

info_form.respondents.email

Example: "email": "someName@someInstitution.edu"

The email address for the survey subject; this is optional.

info_form.respondents.role

Example: "role": "Primary"

The survey subject's role in the class; this is optional but if provided will be Primary, Secondary, Lab, Teaching Assistant, or Preceptor.

info_form.respondents.sex

Example: "sex": "Male"

The survey subject's sex; this is optional but if provided will be Male or Female.

info_form.respondents.employment_status

Example: "employment_status": "Full-time"

The survey subject's employment status; this is optional but if provided will be Full-time or Part-time.

info_form.respondents.appointment

Example: "appointment": "Tenured"

The survey subject's appointment type; this is optional but if provided will be Adjunct, Tenured, or Tenure-track.

info_form.respondents.races

Example: "races": []

A list of the survey subject's races. This is optional but if provided is an unordered list of String values that are unique (aka, a Set).

rater_form

Example: "rater_form": { ... }

The rater form contains details about the survey form those rating the survey subject will fill out.

rater_form.id

Example: "id": 123

rater_form.startDate

Example: "startDate": "2012-09-06T00:00:00Z"

The date that this survey first becomes available to respondents.

rater_form.endDate

Example: "endDate": "2012-09-06T23:59:59Z"

The date that this survey becomes unavailable to respondents.

rater_form.custom_question_groups

Example: "custom_question_groups": [ ... ]

Defines the custom (or extra) questions that were added to this survey.

rater_form.custom_question_groups.number

Example: "number": 1

custom question group number

rater_form.custom_question_groups.type

Example: "type": "open"

custom question group type, one of: scaled (legacy), likert, open, semanticDifference, multipleChoice, fillInTheBlank, mixed

rater_form.custom_question_groups.title

Example: "title": "Question Group 1"

custom question group title

rater_form.custom_question_groups.message

Example: "message": "question group 1"

custom question group message

rater_form.custom_question_groups.questions

Example: "questions": [ ... ]

array of questions in this group

rater_form.custom_question_groups.questions.id

Example: "id": 1

unique question identifier in the IDEA system

rater_form.custom_question_groups.questions.number

Example: "number": 12

custom question number

rater_form.custom_question_groups.questions.text

Example: "text": "Likert question 8"

custom question text

rater_form.custom_question_groups.questions.type

Example: "type": "scaled"

One of: scaled (legacy), likert, open, semanticDifference, multipleChoiceSingleAnswer, multipleChoiceMultipleAnswer, fillInTheBlank

rater_form.custom_question_groups.questions.response_options

Example: "response_options": [ ... ]

array of valid response options for a scaled question

rater_form.custom_question_groups.questions.response_options.value

Example: "value": 1

response value

rater_form.custom_question_groups.questions.response_options.description

Example: "description": "Very Low"

response option description

rater_form.custom_question_groups.questions.response_options.abbreviation

Example: "abbreviation": "Very Low"

short response option name/description

rater_form.custom_question_groups.questions.response_options.is_excluded

Example: "is_excluded": false

true if this response option should be excluded from calculated values

rater_form.custom_question_groups.response_options

Example: "response_options": [ ... ]

array of valid response options for a scaled question group. If each question has it's own response options, this should be omitted

rater_form.custom_question_groups.response_options.value

Example: "value": 1

response value

rater_form.custom_question_groups.response_options.description

Example: "description": "Very High"

response option description

rater_form.custom_question_groups.response_options.abbreviation

Example: "abbreviation": "Very High"

short response option name/description

rater_form.custom_question_groups.response_options.is_excluded

Example: "is_excluded": false

true if this response option should be excluded from calculated values

Example

This request will retrieve the survey information for a survey with ID 123.

Request

GET /v1/survey/123

Response (as JSON)

HTTP 200
{
    "id": 123,
    "group_id": 234,
    "src_name": "IOL3",
    "src_id": "4321",
    "src_group_id": "5432",
    "institution_id": 54209,
    "year": 2012,
    "term": "09/03/2012",
    "includes_gap_analysis": true, // true if this includes a self-rating and false otherwise
    "demographic_group_ids": [ 654, 657, 658, 662 ], //Optional item that defines what demographic groups were selected.
    "end_date": "2012-09-25T00:00:00Z",
    "start_date": "2012-09-06T00:00:00Z",
    "creation_date": "2012-09-05T14:20:07Z",
    "course": {
        "title": "Introduction to REST APIs",
        "number": "101",
        "local_code": "012345", // Institution defined local code
        "days": "MWF",
        "time": "14:30",
        "src_id": "01-23456789-0011",
        "subject": "REST",
        "type": "undergraduate",
        "delivery_mode": "Face to Face",
        "term_type": "semester",
        "start_date": "2017-01-01",
        "end_date": "2017-05-01",
        "section": {
            "title": "RESTful APIs Lab",
            "number": "101a",
            "src_id": "01-23456789-0012",
            "subject": "REST",
            "start_date": "2017-01-01",
            "end_date": "2017-05-01",
            "delivery_mode": "hybrid",
            "days": "TU",
            "time": "08:30",
            "local_code": "54321" // Institution defined local code
        }
    },
    "info_form":
    {
        "id": 456,
        "start_date": "2012-09-06T00:00:00Z",
        "end_date": "2012-09-25T00:00:00Z",
        "discipline_code": 1600,
        "respondents":
        [
            {
                "first_name": "Test",
                "middle_name": "My",
                "last_name": "Subject",
                "title": "Dean",
                "position_code": 12,
                "src_id": "0123-4567890",
                "email": "some.person@institution.edu",
                "role": "primary",
                "sex": "female",
                "employment_status": "full-time",
                "appointment": "tenured",
                "races": [
                    "Hispanic",
                    "Pacific Islander"
                ]
            }
        ]
    },
    "rater_form":
    {
        "id": 457,
        "start_date": "2012-09-06T00:00:00Z",
        "end_date": "2012-09-25T00:00:00Z",
        "custom_question_groups":
        [
            {
                "number": 1,
                "type": "open",
                "title": "Open Question Group Title",
                "message": "This is an open question group message",
                "questions":
                [
                    {
                        "id": 123,
                        "number": 1,
                        "text": "This is an open question 1",
                        "type": "open",
                        "response_options": []
                    }
                ]
            },
            {
                "number": 2,
                "type": "scaled",
                "title": "Scaled Question Group Title",
                "message": "This is a scaled question group message",
                "questions":
                [
                    {
                        "id": 124,
                        "number": 1,
                        "text": "This is a scaled question 1",
                        "type": "scaled",
                        "response_options":
                        [
                            {
                                "value": 1,
                                "description": "This is option 1",
                                "abbreviation": "O1",
                                "is_excluded": false
                            },
                            {
                                "value": 2,
                                "description": "This is option 2",
                                "abbreviation": "O2",
                                "is_excluded": false
                            },
                            {
                                "value": 3,
                                "description": "This is option 3",
                                "abbreviation": "O3",
                                "is_excluded": false
                            },
                            {
                                "value": 4,
                                "description": "Cannot Judge",
                                "abbreviation": "CJ",
                                "is_excluded": true
                            }
                        ]
                    }, ...
                ]
            },...
        ]
    }
}

Get Survey Information