This method allows you to fetch responses to a specific form.

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

This method will return up to 100 responses at a time and you can use 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.kpaehs.com/v1/responses.list.

Parameter TypeScript Example Required Description
token string "YOUR_TOKEN" Required Your API Token
pretty boolean true Optional true means the response json will include white space for readability. Default is false.
form_id number 3987 Required The id of the form.
limit number 100 Optional The maximum number of responses to return. Max 500. Defaults to 10. Use page to fetch additional responses.
page number 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 string "5804f0f30ef50473af5870c6" Optional Filters responses by the user id of the observer.
followups string "pending" Optional Filter responses by whether follow-ups are pending. Defaults to including all responses. all or undefined includes all responses. pending only includes responses with pending follow-ups.
before number 1476981004760 Optional Only include responses submitted before the given date. Should be formatted as the number of milliseconds since 1970.
after number 1473688379489 Optional Only include responses submitted after the given date. Should be formatted as the number of milliseconds since 1970.
updated_before number 1476981004760 Optional Only include responses updated before the given date. Should be formatted as the number of milliseconds since 1970.
updated_after number 1473688379489 Optional Only include responses updated after the given date. Should be formatted as the number of milliseconds since 1970.
latest boolean true Optional The actual responses for each question, location, weather, etc are not returned by default. Include these elements with true. Default is false. This data will be returned in the latest property which represents the latest revision of the response.
deleted boolean true Optional false (default): only returns non-deleted responses. true: only returns deleted responses.

Example Request


Example Response

{
  "ok": true,
  "description": "Near Miss Report: Showing All",
  "paging": {
    "total": 66,
    "last_page": 33
  },
  "responses": [
    {
      "id": 1024,
      "parent_response_id": null,
      "pending_followup_assignees_id": [],
      "created": 1476124461658,
      "updated": 1476718837845,
      "fups": [],
      "latest": {
        "m_completer_id": "5804f0f40ef50473af5870e6",
        "m_submitter_id": "5804f0f40ef50473af587134",
        "started_on": 1476124172467,
        "submitted_on": 1476124461356,
        "received_on": 1476357332698,
        "version": 3,
        "form_version": 1,
        "location": {
          "lon": -97.90176526248575,
          "lat": 30.302495522720506,
          "accuracy": 957
        },
        "weather": {
          "temperature": 65,
          "icon": "wind",
          "windSpeed": 17
        },
        "responses": {
          "nearmissfld-fieldoffice": {
            "value": {
              "values": [
                "5804f0f40ef50473af5870cd"
              ]
            },
            "attachments": []
          },
          "nearmissfld-lob": {
            "value": {
              "values": [
                "5804f0f40ef50473af5870d1"
              ]
            },
            "attachments": []
          },
          "nearmissfld-client": {
            "value": {
              "values": [
                "5804f0f40ef50473af5870d6"
              ]
            },
            "attachments": []
          },
          "nearmissfld-misscategory": {
            "value": {
              "values": [
                "working"
              ]
            },
            "attachments": []
          },
          "nearmissfld-workingcategory-type": {
            "value": {
              "values": [
                "walk-work-surface"
              ]
            },
            "attachments": []
          },
          "nearmissfld-drivingcategory-type": {
            "value": {
              "values": [
                "unsafe-road-conditions"
              ]
            },
            "attachments": []
          },
          "nearmissfld-environmentalcategory-type": {
            "value": {
              "values": [
                "inadequate-supplies"
              ]
            },
            "attachments": []
          },
          "nearmissfld-bodypart": {
            "value": {
              "values": [
                "eye"
              ]
            },
            "attachments": []
          },
          "nearmissfld-severity": {
            "value": {
              "values": [
                "low"
              ]
            },
            "attachments": []
          },
          "nearmissfld-recurrence": {
            "value": {
              "values": [
                "frequent"
              ]
            },
            "attachments": []
          },
          "nearmissfld-actiontaken": {
            "value": {
              "values": [
                "immediate-change"
              ]
            },
            "attachments": []
          },
          "nearmissfld-managementofhazard": {
            "value": {
              "values": []
            },
            "attachments": []
          },
          "nearmissfld-description": {
            "value": {
              "text": "This is a sample answer for the paragraph input 1"
            },
            "attachments": []
          },
          "nearmissfld-attachments": {
            "value": {
              "attachments": [
                {
                  "key": "modules/create-customer/fake-data/client/response-attachments/road-washout.jpg"
                },
                {
                  "key": "modules/create-customer/fake-data/client/response-attachments/cracked-metal.jpg"
                },
                {
                  "key": "modules/create-customer/fake-data/client/response-attachments/broken-pipe.jpg"
                }
              ]
            },
            "attachments": []
          }
        }
      }
    },
    {
      "id": 1027,
      "parent_response_id": null,
      "pending_followup_assignees_id": [],
      "created": 1474605298868,
      "updated": 1476718837882,
      "latest": {
        "m_completer_id": "5804f0f40ef50473af5870e9",
        "m_submitter_id": "5804f0f40ef50473af587185",
        "started_on": 1474605127011,
        "submitted_on": 1474605297236,
        "received_on": 1474838169908,
        "version": 3,
        "form_version": 1,
        "location": {
          "lon": -97.75466801961623,
          "lat": 30.296529179222823,
          "accuracy": 893
        },
        "weather": {
          "temperature": 81,
          "icon": "rain",
          "windSpeed": 7
        },
        "fups": [],
        "responses": {
          "nearmissfld-fieldoffice": {
            "value": {
              "values": [
                "5804f0f40ef50473af5870d0"
              ]
            },
            "attachments": []
          },
          "nearmissfld-lob": {
            "value": {
              "values": [
                "5804f0f40ef50473af5870d3"
              ]
            },
            "attachments": []
          },
          "nearmissfld-client": {
            "value": {
              "values": [
                "5804f0f40ef50473af5870d4"
              ]
            },
            "attachments": []
          },
          "nearmissfld-misscategory": {
            "value": {
              "values": [
                "working"
              ]
            },
            "attachments": []
          },
          "nearmissfld-workingcategory-type": {
            "value": {
              "values": [
                "trenching-shoring"
              ]
            },
            "attachments": []
          },
          "nearmissfld-drivingcategory-type": {
            "value": {
              "values": [
                "unsafe-road-conditions"
              ]
            },
            "attachments": []
          },
          "nearmissfld-environmentalcategory-type": {
            "value": {
              "values": [
                "failure-to-secure"
              ]
            },
            "attachments": []
          },
          "nearmissfld-bodypart": {
            "value": {
              "values": [
                "foot-toe",
                "body-systems"
              ]
            },
            "attachments": []
          },
          "nearmissfld-severity": {
            "value": {
              "values": [
                "high"
              ]
            },
            "attachments": []
          },
          "nearmissfld-recurrence": {
            "value": {
              "values": [
                "frequent"
              ]
            },
            "attachments": []
          },
          "nearmissfld-actiontaken": {
            "value": {
              "values": [
                "immediate-change"
              ]
            },
            "attachments": []
          },
          "nearmissfld-managementofhazard": {
            "value": {
              "values": []
            },
            "attachments": []
          },
          "nearmissfld-description": {
            "value": {
              "text": "This is a sample answer for the paragraph input 71"
            },
            "attachments": []
          },
          "nearmissfld-attachments": {
            "value": {
              "attachments": [
                {
                  "key": "modules/create-customer/fake-data/client/response-attachments/road-washout.jpg"
                },
                {
                  "key": "modules/create-customer/fake-data/client/response-attachments/broken-pipe.jpg"
                }
              ]
            },
            "attachments": []
          }
        }
      }
    }
  ]
}

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 KPA Flex 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.