Fetch responses as a csv or in json format. This endpoint is extremely similar to the spreadsheet download on the Form's "Responses" page.

Responses are sorted newest to oldest. You can filter by observer (observer_id), and by date (before and after).

This method will return up to 1000 responses at a time and you can using paging to fetch additional items.

The paging field in the response includes total which contains the total number of responses available and last_page which is the highest page number which would contain results.


Parameters

Your request data may contain the following parameters. GET or POST the object (as JSON) to https://api.iscout.com/v1/responses.flat.

Parameter Example Required Description
token "YOUR_TOKEN" Required Your API Token
pretty true Optional true means the response json will include white space for readability. Default is false.
form_id 3987 Required The id of the form.
limit 100 Optional The maximum number of responses to return. Max 1000. Defaults to 100. Use page to fetch additional responses.
page 1 Optional The page of responses to return. Defaults to 1. The response field paging.last_page tells you what the last valid page number is.
observer_id "5804f0f30ef50473af5870c6" Optional Filters responses by the user id of the observer.
before 1476981004760 Optional Only include responses submitted before the given date. Should be formatted as the number of milliseconds since 1970.
after 1473688379489 Optional Only include responses submitted after the given date. Should be formatted as the number of milliseconds since 1970.
format "csv" Optional Choose whether the response should be in `json` or `csv` format. `json` is the default.
columns ["report number","observer","temperature"] Optional The column names that should be fetched. If no columns are provided then all columns will be returned.

Example Request


Example Response

link,report,report number,date,updated,version,observer,observer-emp-num,duration,latitude,longitude,temperature,wind-speed,weather,lhbrcique8olxa02,nearmissfld-fieldoffice,nearmissfld-lob,nearmissfld-lob-followups,nearmissfld-client,nearmissfld-misscategory,nearmissfld-workingcategory-type,nearmissfld-drivingcategory-type,nearmissfld-drivingcategory-type-followups,nearmissfld-environmentalcategory-type,nearmissfld-environmentalcategory-type-followups,nearmissfld-bodypart,nearmissfld-bodypart-followups,nearmissfld-severity,nearmissfld-severity-followups,nearmissfld-recurrence,nearmissfld-actiontaken,nearmissfld-managementofhazard,nearmissfld-description,nearmissfld-attachments,nearmissfld-attachments-followups,select-working,select-driving,select-environmental,select-low,select-medium,select-high,select-critical,select-rare,select-random,select-frequent,select-accepted,select-stop work,select-communication,select-immediate change,select-gradual change,select-eliminate,select-control,select-protect,select-accept
Link,Report,Report Number,Date,Updated,Version,Observer,Observer Emp#,Duration (Seconds),Latitude,Longitude,Temperature,Wind Speed,Weather,Employee,Office,Line of Business,Line of Business Follow-ups,Company,Category,Working Category,Driving Category,Driving Category Follow-ups,Environmental Category,Environmental Category Follow-ups,Body Part,Body Part Follow-ups,Severity,Severity Follow-ups,Recurrence,Action,Managment,Description,Photos,Photos Follow-ups,Working,Driving,Environmental,Low,Medium,High,Critical,Rare,Random,Frequent,Accepted,Stop Work,Communication,Immediate Change,Gradual Change,Eliminate,Control,Protect,Accept
http://acme.iscout.localhost:3000/forms/responses/view/1154,Near Miss Report,1154,2019-02-12 16:55:13,2019-02-12 16:55:13,1,Derrick Brown,DBROWN,13,35.2057428,-97.4428221,42.98,5.15 mph,clear,Derrick Brown,Atlanta,Assembly,0,Emerson Finishing,Working,Awareness,,0,,0,,0,Low,0,Rare,,,Test,,0,1,0,0,1,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0
http://acme.iscout.localhost:3000/forms/responses/view/1152,Near Miss Report,1152,2019-02-02 08:17:46,2019-02-12 15:49:20,4,Rick Pruitt,47606,99,30.317034595300182,-97.70571814667117,80,18 mph,rain,,Atlanta,Electrical,0,Emerson Finishing,Working,Awareness,Awareness/Attitude,0,Spill Release,0,,0,High,0,Accepted,,,This is a sample answer for the paragraph input 4290,,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,0,0,0,0
http://acme.iscout.localhost:3000/forms/responses/view/1150,Near Miss Report,1150,2019-02-07 14:20:35,2019-02-12 15:49:20,3,Jason Clark,47552,138,29.717029279631387,-95.31940119835807,47,16 mph,rain,,Houston,Assembly,0,A&B Services,Driving,Housekeeping,Harsh Acceleration/Deceleration,0,Spill Release,0,"Eye, Body Systems, Knee/Leg",0,High,0,Rare,,,This is a sample answer for the paragraph input 4224,http://acme.iscout.localhost:3000/get-upload?key=modules%2Fcreate-customer%2Ffake-data%2Fclient%2Fresponse-attachments%2Fcracked-metal.jpg,0,0,1,0,0,0,1,0,1,0,0,0,0,0,0,0,0,0,0,0
http://acme.iscout.localhost:3000/forms/responses/view/1148,Near Miss Report,1148,2019-02-04 13:26:05,2019-02-12 15:49:20,3,Bridget Goodman,47543,206,29.44447549280965,-98.46784193851614,69,18 mph,fog,,Atlanta,Concrete,0,Emerson Finishing,Driving,Unsafe/Defective Equipment,Awareness/Attitude,0,Improper Containment,0,"Hand/Finger, Body Systems, Shoulder/Arm",0,Low,0,Random,Gradual Change,,This is a sample answer for the paragraph input 4156,,0,0,1,0,1,0,0,0,0,1,0,0,0,0,0,1,0,0,0,0
http://acme.iscout.localhost:3000/forms/responses/view/1146,Near Miss Report,1146,2019-02-07 00:39:14,2019-02-12 15:49:20,3,Dennis Wolfe,47542,54,30.31293386446263,-97.6838054151103,38,3 mph,wind,,Dallas,Concrete,0,A&B Services,Working,Bites/Stings,Lane Change,0,Improper Containment,0,"Knee/Leg, Eye",0,High,0,Accepted,Communication,,This is a sample answer for the paragraph input 4091,,0,1,0,0,0,0,1,0,0,0,0,1,0,1,0,0,0,0,0,0
http://acme.iscout.localhost:3000/forms/responses/view/1144,Near Miss Report,1144,2019-02-05 09:56:29,2019-02-12 15:49:20,3,Melinda Nichols,47541,147,29.72892561517524,-95.40468730224588,37,20 mph,fog,,Houston,Concrete,0,Yates Electric,Environmental,Walking/Working Surface,Unsafe Road Conditions,0,Improper Containment,0,Foot/Toe,0,Low,0,Frequent,Gradual Change,,This is a sample answer for the paragraph input 4023,http://acme.iscout.localhost:3000/get-upload?key=modules%2Fcreate-customer%2Ffake-data%2Fclient%2Fresponse-attachments%2Froad-washout.jpg,0,0,0,1,1,0,0,0,0,0,1,0,0,0,0,1,0,0,0,0
http://acme.iscout.localhost:3000/forms/responses/view/1142,Near Miss Report,1142,2019-02-07 16:57:18,2019-02-12 15:49:20,3,Margarita Chambers,47540,294,30.21261638978011,-97.75684269890837,64,13 mph,rain,,Houston,Concrete,0,Yates Electric,Environmental,Unsafe Action,Animal,0,Failure to Secure,0,"Body Systems, Shoulder/Arm",0,Medium,0,Rare,,Protect,This is a sample answer for the paragraph input 3954,http://acme.iscout.localhost:3000/get-upload?key=modules%2Fcreate-customer%2Ffake-data%2Fclient%2Fresponse-attachments%2Fcracked-metal.jpg,0,0,0,1,0,1,0,0,1,0,0,0,0,0,0,0,0,0,1,0
http://acme.iscout.localhost:3000/forms/responses/view/1140,Near Miss Report,1140,2019-02-12 14:06:35,2019-02-12 15:49:20,4,Jamie Cole,47539,198,29.516774731199828,-98.44745675192227,27,,snow,,Dallas,Assembly,0,A&B Services,Driving,Awareness,Unsafe Speed,0,Unsafe Action,0,"Neck/Throat, Back",0,Critical,0,Rare,,Protect,This is a sample answer for the paragraph input

Errors

If an error occurs, the response JSON will have ok set to false:

{
  "ok": false,
  "error": "token_invalid",
  "description": "The token `YOUR_TOKEN` was not found."
}

The error field will contain one of the following error identifiers and there may also be a description field with a more detailed explanation:

Identifier Description
api_method_not_found The requested url did not match any iScout api method.
request_method_invalid The requested method was not GET or POST.
request_data_invalid The request did not include a valid JSON request object.
rate_limit_exceeded This token is exceeding its request limit.
token_missing The request did not include a token.
token_invalid The request token was invalid.
token_inactive The request token was has been deactivated.
token_permission The request token does not have write permission.
account_inactive The request token was for an account that is not active.
parameter_unexpected The request data included a parameter that is not supported.
parameter_missing The request data failed to include a parameter which was required.
parameter_invalid The request data included a parameter which had a value that is not allowed.
server_error The server encountered an internal error.
content_not_found The requested content was not found.