Submit Survey Data

POST /services/survey

This end-point is used to submit IDEA survey data (including specific IDEA form types used, responses, and extra questions).

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());

When re-submitting data, be sure to use the same source survey ID (src_id). This, along with the application, is used to determine if this is a new survey or an existing one. When it is an existing one, we invalidate the existing survey and reports and then store the new data (survey raw data and calculated report data).

Resource URL

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

Data Parameters (JSON Body)

src_id
required
Example: "src_id": "1234"
Defines the source's ID for this survey. This MUST be a unique identifier within the source system. This is used to ensure duplicate surveys are not inserted into the IDEA system. If the same survey is sent multiple times, it should use the same src_id. This will be stored in our system separate from our IDEA survey ID. The IDEA and source IDs can be mapped using the response; the JSON response contains the IDEA IDs and source IDs. This is required and can take any String up to a length of 45 characters.
src_group_id
required
Example: "src_group_id": "1234"
Defines the source's group ID for this survey. This is used to maintain client specified survey grouping structure. If the same survey is sent multiple times, it should use the same src_group_id. This will be stored in our system separate from our IDEA group ID. The IDEA and source IDs can be mapped using the response; the JSON response contains the IDEA IDs and source IDs. This is required and can take any String up to a length of 45 characters.
year
optional
Example: "year": 2013
The year provided must be a valid year and it is suggested that it map to the year in which the survey was administered. An error will occur if an invalid year is provided. For example, 2012 is a valid year while -1 is not. It is suggested that this matches the year portion of the creationDate. If not defined, we will get the current date and use the year portion of it.
term
optional
Example: "term": "Spring"
Defines a user-generated term that this survey is from. For example, Spring, January, or Q1. This is optional and can take any String up to a length of 45 characters.
includes_gap_analysis
optional
Example: "includes_gap_analysis": false
True if this survey will have gap analysis and false otherwise. This is only used in the Chair and Admin surveys.
creation_date
optional
Example: "creation_date": "2013-03-01T02:12:42Z"
Defines when the survey was initially setup. It is suggested that this be before the first form start date. If nothing is provided, the current date/time will be used. In IOL3, this would be when the client request is created. For partners, it might be the date when the survey was initially created in the CMS/LMS.
institution_id
required
Example: "institution_id": 77893
Uniquely identifies a institution in the IDEA system. This ID can be retrieved from the GET /institution REST end-point.
course
required for student ratings surveys
Example: "course": { ... }

Defines the course information when submitting survey data associated with course. This will include details like the time and days that the class meets, the course title, subject, and number, and a local code used for grouping in reports.

It is suggested that the course or course.section elements are filled out for the Student Ratings of Instruction (SRI) so that the survey's context can be determined. Both areas can have values but might be redundant.

course.src_id
optional
Example: "src_id": "012-3456-789"
Provides a mapping from to the source system's course. This is optional but can take any String, including an empty value, up to a length of 500 characters.
course.title
optional
Example: "title": "Intro to Sociology"
Defines the course title. This is a suggested value for the Student Ratings of Instruction (SRI) and be any String value up to 300 characters.
course.number
optional
Example: "number": "101"
Defines the course number. For example, 101 in BIO 101. This is a suggested value for the Student Ratings of Instruction (SRI) and be any String value up to 500 characters.
course.subject
optional
Example: "subject": "BIO"
The course's subject. For example, BIO in BIO 101. This is a suggested value for the Student Ratings of Instruction (SRI) and can take any String, including an empty value, up to a length of 45 characters.
course.time
optional
Example: "time": "12:30"
Defines the time that the course meets. This is free-form so any type of time can be used as long as it is less than 45 characters.
course.days
optional
Example: "days": "MWF"
Defines the days that the course meets. This is free-form so any type of days can be used as long as it is less than 45 characters. For example, it might meet on Monday, Wednesday, and Friday and specified as "MWF" or "Mon, Wed, Fri".
course.local_code
optional
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 but must be less than 8 characters.
course.type
optional
Example: "type": "undergraduate"
The type of course. This is optional but if provided must 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
optional
Example: "delivery_mode": "online"
The delivery mode of the course. This is optional but if provided must 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
optional
Example: "term_type": "semester"
The term type this course is part of. This is optional but if provided must be one of the following: Semester, Trimester, Quarter, Intersession, Module, or Annual.
course.start_date
optional
Example: "start_date": "2017-01-24"
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
optional
Example: "end_date": "2017-05-10"
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
optional
Example: "section": { ... }

When a survey is associated with only 1 section of a course, this portion can be populated to provide details on that course section. It is optional and can provide details on the source ID, number, subject, title, local code, delivery mode, start/end dates, and the meeting time/days.

It is suggested that the course or course.section elements are filled out for the Student Ratings of Instruction (SRI) so that the survey's context can be determined. Both areas can have values but might be redundant.

course.section.src_id
optional
Example: "src_id": "012-3456-789"
Provides a mapping from to the source system's course section. This is optional but can take any String, including an empty value, up to a length of 45 characters.
course.section.title
optional
Example: "title": "Intro to Sociology"
Defines the course section title. This is optional and can be any String value less than 300 characters.
course.section.number
optional
Example: "number": "101"
Defines the course section number. For example, 101 in BIO 101. This is optioanl and can be any String value less than 500 characters.
course.section.subject
optional
Example: "subject": "BIO"
The course section's subject. For example, BIO in BIO 101. This is optional but can take any String, including an empty value, up to a length of 45 characters.
course.section.time
optional
Example: "time": "12:30"
Defines the time that the course section meets. This is free-form so any type of time can be used as long as it is less than 45 characters.
course.section.days
optional
Example: "days": "MWF"
Defines the days that the course section meets. This is free-form so any type of days can be used as long as it is less than 45 characters. For example, it might meet on Monday, Wednesday, and Friday and specified as "MWF" or "Mon, Wed, Fri".
course.section.local_code
optional
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 as long as it is less than 8 characters.
course.section.delivery_mode
optional
Example: "delivery_mode": "online"
The delivery mode of the course section. This is optional but if provided must 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.start_date
optional
Example: "start_date": "2017-01-24"
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
optional
Example: "end_date": "2017-05-10"
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).
info_form
required
Example: "info_form": { ... }
Defines the form that the survey subject would fill out. This includes a form ID, start/end dates, number of respondents asked to respond, the respondent information (this is the survey subjects), and the answers for each question.
info_form.id
required
Example: "id": 12
Defines which IDEA form this is. The ID can be retrieved from the GET /forms REST end-point.
info_form.start_date
required
Example: "start_date": "2013-03-01T00:00:01Z"
Defines the date when the information form was first available to be filled out.
info_form.end_date
required
Example: "end_date": "2013-03-10T23:59:59Z"
Defines the date when the information form was last available to be filled out.
info_form.discipline_code
optional
Example: "discipline_code": "0203"

Discipline codes are used on student ratings surveys. If not provided, the discipline values will not appear on the report. Discipline/Department Codes are listed at DisciplineCodes.

A list of supported Disciplines is available through the Data Portal GET /disciplines REST end-point.

info_form.program_code
optional
Example: "program_code": "01.0603"

Classification of Instructional Programs (CIP) code (available from the Department of Education).

A list of supported CIPs is available through the Data Portal GET /cip REST end-point. We currently support the 2010 version.

info_form.number_asked
required
Example: "number_asked": 1
Defines how many respondents were asked to respond. For the information form, this will likely be 1.
info_form.respondents
required
Example: "respondents": [ ... ]
Defines the respondents (as an array). For the information form, this will likely be a single respondent.
info_form.respondents.first_name
required
Example: "first_name": "Jane"
The first name of info form respondent; this is the survey subject (e.g., faculty member, administrator, chair). This is required and can take any String up to a length of 200 characters.
info_form.respondents.last_name
required
Example: "last_name": "Doe"
The last name of info form respondent; this is the survey subject (e.g., faculty member, administrator, chair). This is required and can take any String up to a length of 200 characters.
info_form.respondents.title
required
Example: "title": "Professor"
The title of info form respondent; this is the survey subject's title (e.g., Chair, Professor, Provost). This is required and can take any String up to a length of 200 characters.
info_form.respondents.position_code
optional
Example: "position_code": 1
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
optional
Example: "src_id": "01-234-5678-999"
The ID of this respondent on the source system. This provides a way to map IDEA data to a source system. This is optional and can be any String value up to 100 characters in length (including an empty String).
info_form.respondents.email
optional
Example: "email": "test@some.institution.edu"
The email address of the survey subject. This is optional and can be any String value up to 254 characters in length. We DO NOT perform any validation on the email address since we never use this value to deliver email.
info_form.respondents.sex
optional
Example: "sex": "female"
The sex of the survey subject; this is optional and can be male or female (or an empty String).
info_form.respondents.role
optional
Example: "role": "primary"
The survey subject's role in the course. This is only useful in the Student Ratings of Instruction (SRI) system. This is optional and can be one of the following values: Primary, Secondary, Lab, Teaching Assistance (Teaching-Assistant, TA), or Preceptor.
info_form.respondents.appointment
optional
Example: "appointment": "adjunct"
The survey subject's appointment type. This is optional and be one of the following values: Tenured, Tenure Track (Tenure-Track), or Adjunct.
info_form.respondents.employment_status
optional
Example: "employment_status": "full-time"
The survey subject's employment status. This is optional and can be one of the following: Full Time (Full-Time) or Part Time (Part-Time).
info_form.respondents.races
optional
Example: "races": [ ... ]
The survey subject's race as a list of String values. This is optional and can take any String up to a length of 100 characters each.
info_form.respondents.responses
required
Example: "responses": [ ... ]
Array of responses to info form questions. Responses are matched to IDEA questions using IDEA form ID and question ID.
info_form.respondents.responses.question_id
required
Unique identifier for a question in the IDEA system
info_form.respondents.responses.answer
required
Response value.
rater_form
required
Example: "rater_form": { ... }
Defines the form that the raters would fill out. This includes a form ID, start/end dates, number of respondents asked to respond and responses for each respondent. In addition, this will include any custom questions that were added to the survey.
rater_form.id
required
Example: "id": 12
Defines which IDEA form this is. The ID can be retrieved from the GET /forms REST end-point.
rater_form.start_date
required
Example: "start_date": "2013-03-01T00:00:01Z"
Defines the date when the rater form was first available to be filled out.
rater_form.end_date
required
Example: "end_date": "2013-03-10T23:59:59Z"
Defines the date when the rater form was last available to be filled out.
rater_form.number_asked
required
Example: "number_asked": 25
Defines how many respondents were asked to respond.
rater_form.respondents
required
Example: "respondents": [ ... ]
Defines the respondents (as an array). For the rater form, this should not include any personally identifiable information (e.g., name). If rater form respondent information is provided, it is ignored (not stored).

Note: If there are more respondents in this array than the value in rater_form.number_asked an error will be returned and no data will be stored.

rater_form.respondents.responses
required
Example: "responses": [ ... ]
Array of responses to rater form questions. Standard IDEA question responses are matched to questions using the question_id. Custom question responses are matched to question using group_number and question_number.
rater_form.respondents.responses.group_type
required for custom question responses
Example: "group_type": "custom"
Group number and question number must match a custom question defined in rater_form.custom_question_groups.
rater_form.respondents.responses.group_number
required for custom question responses
Question group number
rater_form.respondents.responses.question_number
required for custom question responses
Question number
rater_form.respondents.responses.question_id
required for standard IDEA form question responses
Unique identifier for a question in the IDEA system.
rater_form.respondents.responses.answer
required
Response value
rater_form.custom_question_groups
optional
Example: "custom_question_groups": [ ... ]
Defines the custom (or extra) questions that were added to this survey.
rater_form.custom_question_groups.number
required
Custom question group number. Extra question group numbers should start at 1+(max standard question group number)
rater_form.custom_question_groups.type
required
"open" or "scaled"
rater_form.custom_question_groups.title
required on all scaled question groups
Custom question group title. This is required and can take any String up to a length of 500 characters.
rater_form.custom_question_groups.message
optional
Custom question group message. This is optional and can take any String up to a length of 5000 characters.
rater_form.custom_question_groups.response_options
required for scaled group
Array of valid response options for a scaled question
rater_form.custom_question_groups.response_options.value
required
Response value. This should be a number greater than zero (0) for example 1, 2, 3, etc. The value zero (0) is reserved by IDEA to represent the number of respondents who left a particular question blank. Negative numbers and zero (0) will be rejected with an error.
rater_form.custom_question_groups.response_options.description
required
Response option description. This is required and can take any String up to a length of 300 characters.
rater_form.custom_question_groups.response_options.abbreviation
optional
Short response option name/description. This is required and can take any String up to a length of 50 characters.
rater_form.custom_question_groups.response_options.is_excluded
optional, defaults to false
True if this response option should be excluded from calculated values.
rater_form.custom_question_groups.questions
required
Array of questions in this group.
rater_form.custom_question_groups.questions.number
required
Custom question number.
rater_form.custom_question_groups.questions.text
required
Custom question text. This is required and can take any String up to a length of 1500 characters.
rater_form.custom_question_groups.questions.type
required
"open" or "scaled"

Response

If the survey was stored properly, the returned JSON will have a status of "SAVED" and a HTTP status code of 200. The data returned allows a client to map their IDs (passed in as id, group_id and returned as src_id and src_group_id) to the IDEA IDs (returned as id and group_id). The id and group_id will be useful later to query for reports (model and pdf) and report status.

If the survey was NOT stored properly, the returned JSON will have a status of "ERROR" and contain an error message. HTTP status code of 400 will be returned when unexpected JSON was posted. HTTP status code of 503 will be returned when a back-end error occurs.

Response Parameters (JSON Body)

id
Example: "id": 1234
This defines the ID that the IDEA System will use to identify this survey (combo: ID_SURVEY).
group_id
Example: "group_id": 1234
This defines the group ID that the IDEA System will use to identify the group of surveys this belongs to.
src_id
Example: "src_id": "1234"
This will simply mirror back the source survey ID provided in the initial request. This is done to confirm what was sent and make it easy to map the IDEA survey ID to the client's ID.
src_group_id
Example: "src_group_id": "1234"
This will simply mirror back the source group ID provided in the initial request. This is done to confirm what was sent and make it easy to map the IDEA System group ID to the client's group ID.
status
Example: "status": "SAVED"
This defines the status of the saving of the given survey. It will either be SAVED (meaning that the survey was successfully stored) or ERROR (meaning there was an issue in saving the survey). The status_message should provide guidance if ERROR is returned.
status_message
Example: "status_message": "The database was unreachable; try again later."
This provides guidance to the client if the status is set to ERROR. It will be human readable and have as much detail as can reasonably be provided.


Example


Request

POST /v1/services/survey

POST Data (as JSON)

{
    "src_id": "123", // Source's survey ID (must be globaly unique within source system).
    "src_group_id": "234", // Source's survey group ID.
    "year": 2012,
    "term": "09/03/2012", // This can be any text (e.g., Fall, Spring, January)
    "includes_gap_analysis": false //always false for student ratings data
    "creation_date": "2012-04-05T05:00:00Z",
    "institution_id": 4455, //Uniquely identifies a institution in the IDEA system (retrieved from the GET /institution REST end-point).
    "course": {
        "local_code": "012345", // Institution defined local code
        "title": "Introduction to REST APIs",
        "number": "101",
        "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": {
            "src_id": "01-23456789-0012",
            "subject": "REST",
            "title": "RESTful APIs Lab",
            "number": "101a",
            "delivery_mode": "hybrid",
            "local_code": "54321", // Institution defined local code
            "days": "TU",
            "time": "08:30",
            "start_date": "2017-01-01",
            "end_date": "2017-05-01"
        }
    },
    "info_form":
    {
        "id": 1, //Identifies which IDEA form this is (retrieved from the GET /forms REST end-point).
        "start_date": "2012-04-05T00:00:00Z",
        "end_date": "2012-04-15T00:00:00Z",
        "discipline_code": "1603",
        "program_code": "01.0603", // defines the Classification of Instructional Program code for this survey
        "number_asked": 1,
        "respondents":
        [
            {
                "first_name": "Test",
                "last_name": "Subject",
                "title": "Dean",
                "position_code": 12,
                "src_id": "0123-4567890",
                "email": "some.person@institution.edu",
                "role": "primary",
                "employment_status": "full-time",
                "appointment": "tenured",
                "races": [
                    "Hispanic",
                    "Pacific Islander"
                ],
                "responses":
                [
                    {
                        "question_id": 123,
                        "answer": "3"
                    }, ...
                ]
            }
        ]
    },
    "rater_form":
    {
        "id": 9, //Identifies which IDEA form this is (retrieved from the GET /forms REST end-point).
        "start_date": "2012-04-05T00:00:00Z",
        "end_date": "2012-04-15T00:00:00Z",
        "custom_question_groups":
        [
            {
                "number": 7,
                "type": "open",
                "title": "Open Question Group Title",
                "message": "This is an open question group message",
                "response_options":[],
                "questions":
                [
                    {
                        "number": 1,
                        "text": "This is an open question 1",
                        "type": "open"
                    }
                ]
            },
            {
                "number": 8,
                "type": "scaled",
                "title": "Scaled Question Group Title",
                "message": "This is a scaled question group message",
                "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
                    }
                ],
                "questions":
                [
                    {
                        "number": 1,
                        "text": "This is a scaled question 1",
                        "type": "scaled"
                    }, ...
                ]
            },...
        ],
        "number_asked": 23,
        "respondents":
        [
            {
                "responses":
                [
                    {
                        "question_id": 234,
                        "answer": "3"
                    }, ...
                    {
                        "group_type": "custom",
                        "group_number": 8,
                        "question_number": 1,
                        "answer": "1"
                    }, ...
                ]
            }, ...
        ]
    }
}

Response (as JSON)

HTTP 200
{
    "id": 6543, //IDEA survey ID
    "group_id": 7654, //IDEA survey group ID
    "src_id": "123",	// Source (where this survey originaly came from) survey ID
    "src_group_id": "234",  //Source (where this survey originaly came from) survey group ID
    "status": "SAVED",
    "status_message": ""
}