Ninth Brain API Documentation
Form Responses
| Field | Type | Description |
|---|---|---|
| HasMoreResults | bool | indicates if there are more results |
| Offset | int | Number of results skipped. Will match the parameter passed into the endpoint. |
| ResultCount | int | Number of results returned. |
| Data | List of FormResponse objects | One item for each form response |
| Field | Type | Description |
|---|---|---|
| ResponseId | int | Unique id generated by NBS |
| SubmittedBy | FormResponseEmployee Object | The employee that originally submitted the form |
| StartDate | DateTimeOffset | When the form was started |
| AssignedTo | FormResponseEmployee Object | Who the form is currently assigned to |
| Status | String | Statuses can be custimized by each company |
| AttachedToType | String | Describes what type of record the form is attached to. “IndividualRecord”, “QualityImprovement”, “EducationRecord”, “EmployeeHealth”, “FormsOnly” |
| RelatedIndividual | RelatedIndividual Object | Only included if the AttachedToType is “Individual Record” or “Education Record” |
| RelatedEmployeeHealthEvent | RelatedEmployeeHealthEvent Object | Only included if the AttachedToType is “Employee Health Incident” |
| RelatedQualityImprovementIncident | RelatedQualityImprovementIncident Object | Only included if the AttachedToType is “Quality Improvement Incident” |
| Answers | List of FormResponseAnswers Objects | List of the answers to form questions |
| Field | Type | Description |
|---|---|---|
| NBSId | int | Unique identifier created by NBS |
| EmployeeNumber | string | Unique within company |
| FirstName | int | |
| LastName | int |
| Field | Type | Description |
|---|---|---|
| HealthEventId | int | Unique identifier per company created by NBS |
| HealthEventType | string | |
| EventDateTime | DateTimeOffset | |
| RelatedIndividual | int |
| Field | Type | Description |
|---|---|---|
| IncidentId | int | Unique identifier per company created by NBS |
| IncidentType | string | |
| IncidentDateTime | DateTimeOffset |
| Field | Type | Description |
|---|---|---|
| QuestionId | int | Unique id for each question generated by NBS |
| QuestionType | string | “Dropdown List”, “Radio Buttons”, “Checkboxes”, “Textbox”, “Comments Box”, “Date/Time”, “Number”, “Yes/No”, “True/False”, “Ranking Sum”, “Ranking”, “Radio Button Matrix”, “Checkbox Matrix”, “Textbox Matrix”, “One or More Lines”, “Rating Scale”, “NBS Dropdown List”, “Attach Document”, “Address”, “Name”, “Custom Dropdown”, “Signature” |
| QuestionText | string | Label shown to users when completing form |
| QuestionAlias | string | Optional identifer for questions |
| PageNumber | int | |
| SectionName | string | |
| AnswerValue | Object | Because each question type’s answer is different the AnswerValue property is a different structure that makes sense for each question type. |
Note that you can include the offset with the times but you need to html encode the
+as%2Bif you are sending one. For example you would send2022-01-01T00:00+00:00as2022-01-01T00:00%2B00:00.
Get a list of form submissions during a specified time range.
Authorization needed
GET https://api.ninthbrain.com/FormResponse/GetList?api-version=2.0&FormId=21959&StartDate=2023-10-01T00:00%2B00:00&EndDate=2023-11-01T00:00%2B00:00
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| FormId | int | required | The form to query. A list of the company’s forms can be found using the Forms endpoint. |
| StartDate | DateTimeOffset | required | Specifes date range of form responses to return. Filters based on form start date. Note on sending offset with datetime |
| EndDate | DateTimeOffset | required | Specifes date range of form responses to return. Filters based on form start date. Note on sending offset with datetime |
| Offset | int | optional | Used for paging results. Number of records to skip. Defaults to 0. |
| Limit | int | optional | Used for paging results. Max number of results to return, must be between 1-200. Defaults to 200. |
This is an example response that includes all 23 fields types.
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
"HasMoreResults": false,
"Offset": 0,
"Results": 1,
"FormId": 123,
"FormTitle": "Every Field Type",
"Data": [{
"ResponseId": 4532853,
"SubmittedBy": {
"NBSId": 123,
"EmployeeNumber": "A123",
"FirstName": "John",
"LastName": "Doe"
},
"StartDate": "2023-10-17T15:31:05.223-04:00",
"AssignedTo": : {
"NBSId": 123,
"EmployeeNumber": "A123",
"FirstName": "John",
"LastName": "Doe"
},
"Status": "Open",
"AttachedToType": "IndividualRecord",
"RelatedIndividual": {
"NBSId": 123,
"EmployeeNumber": "A123",
"FirstName": "John",
"LastName": "Doe"
}
"Answers": [{
"AnswerValue": "testing 123",
"QuestionId": 715564,
"QuestionType": "Textbox",
"QuestionText": "Textbox",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": "multiple lines \r\nof text are \r\nhere",
"QuestionId": 715565,
"QuestionType": "Comments Box",
"QuestionText": "Comments Box",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": "2023-08-14T00:00:00-04:00",
"QuestionId": 715566,
"QuestionType": "Date/Time",
"QuestionText": "Date Time",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": [
"b"
],
"QuestionId": 715567,
"QuestionType": "Checkboxes",
"QuestionText": "Checkboxes",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": {
"SelectedValue": "b",
"OtherAnswerValue": ""
},
"QuestionId": 715568,
"QuestionType": "Radio Buttons",
"QuestionText": "Radio Buttons",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": true,
"QuestionId": 715569,
"QuestionType": "True/False",
"QuestionText": "t/f",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": false,
"QuestionId": 715570,
"QuestionType": "Yes/No",
"QuestionText": "y/n",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": {
"SelectedValue": "b",
"OtherAnswerValue": ""
},
"QuestionId": 715572,
"QuestionType": "Dropdown List",
"QuestionText": "Dropdown list",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": "Bernard, Andy",
"QuestionId": 715573,
"QuestionType": "NBS Dropdown List",
"QuestionText": "Employee Dropdown",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": "Alaska: Truck 5",
"QuestionId": 715574,
"QuestionType": "NBS Dropdown List",
"QuestionText": "Vehicle Dropdown",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": "Doe, John",
"QuestionId": 715575,
"QuestionType": "Name",
"QuestionText": "Name",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": "Selected Custom Dropdown Value",
"QuestionId": 715576,
"QuestionType": "Custom Dropdown",
"QuestionText": "Custom Dropdown",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": {
"StreetAddress1": "123 main",
"StreetAddress2": "line 2",
"City": "Demo Town",
"State": "MI",
"ZipCode": "23422"
},
"QuestionId": 715577,
"QuestionType": "Address",
"QuestionText": "Address",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": 10.0,
"QuestionId": 715578,
"QuestionType": "Number",
"QuestionText": "A Number",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Basic Fields"
}, {
"AnswerValue": [{
"Row": "Row 1",
"Column": "Col A",
"AnswerText": "Text Typed into 1A"
}, {
"Row": "Row 1",
"Column": "Col B",
"AnswerText": "Text Typed into 1B"
}, {
"Row": "Row 2",
"Column": "Col A",
"AnswerText": "Text Typed into 2A"
}, {
"Row": "Row 2",
"Column": "Col B",
"AnswerText": "Text Typed into 2B"
}
],
"QuestionId": 715579,
"QuestionType": "Textbox Matrix",
"QuestionText": "Matrix",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Advanced Fields"
}, {
"AnswerValue": [{
"Row": "Row 1",
"SelectedValues": [
"Significant",
"Neutral"
]
}, {
"Row": "Row 2",
"SelectedValues": [
"Very Significant"
]
}
],
"QuestionId": 715581,
"QuestionType": "Checkbox Matrix",
"QuestionText": "Checkbox Matrix",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Advanced Fields"
}, {
"AnswerValue": [{
"Row": "Row 1",
"SelectedValue": "Very Good"
}, {
"Row": "Row 2",
"SelectedValue": "Bad"
}
],
"QuestionId": 715582,
"QuestionType": "Radio Button Matrix",
"QuestionText": "Radio Button Matrix",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Advanced Fields"
}, {
"AnswerValue": [{
"Row": "First Row",
"SelectedValue": "1"
}
],
"QuestionId": 715583,
"QuestionType": "Rating Scale",
"QuestionText": "Rating",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Advanced Fields"
}, {
"AnswerValue": [{
"Row": "Row 1",
"SelectedValue": "1"
}, {
"Row": "Row 2",
"SelectedValue": "2"
}, {
"Row": "Row 3",
"SelectedValue": "3"
}
],
"QuestionId": 715584,
"QuestionType": "Ranking",
"QuestionText": "Ranking",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Advanced Fields"
}, {
"AnswerValue": [{
"Row": "Row A",
"SelectedValue": "1"
}, {
"Row": "Row 2",
"SelectedValue": "4"
}, {
"Row": "Row 4",
"SelectedValue": "5"
}
],
"QuestionId": 715585,
"QuestionType": "Ranking Sum",
"QuestionText": "Ranking Sum",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Advanced Fields"
}, {
"AnswerValue": [{
"Row": "First Row",
"SelectedValue": "Text typed into first row"
}, {
"Row": "Second Row",
"SelectedValue": "Text typed into second"
}
],
"QuestionId": 715586,
"QuestionType": "One or More Lines",
"QuestionText": "One or More Lines",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Advanced Fields"
}, {
"AnswerValue": {
"FileUri": "https://api.ninthbrain.com/FormResponseDocument/GetFile?id=133623819&api-version=2.0"
},
"QuestionId": 715587,
"QuestionType": "Attach Document",
"QuestionText": "Attachment",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Advanced Fields"
}, {
"AnswerValue": {
"HasSignature": true
},
"QuestionId": 715588,
"QuestionType": "Signature",
"QuestionText": "Sign Here",
"QuestionAlias": "",
"PageNumber": 0,
"SectionName": "Advanced Fields"
}
]
}
]
}
bad_request(HTTP 400)unauthorized(HTTP 401) - This APIKey is not valid for this service.internal_error(HTTP 500)