This method returns the details of a given form such as version number and fields.
Parameters
Your request data may contain the following parameters. GET or POST the object (as JSON) tohttps://api.kpaehs.com/v1/forms.info.
| 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 |
1234 |
Required | The id of the form. |
include_versions |
boolean |
false |
Optional | Whether to include past vesions of the form. Default is false |
Example Request
Example Response
{
"ok": true,
"form": {
"id": 1024,
"created": 1476718836445,
"updated": 1476721596310,
"sequence": 1,
"name": "Near Miss Report",
"hidden": false,
"description": "Report events that qualify as a near miss.",
"score": false,
"latest": {
"version": 2,
"fields": [
{
"id": "nearmissfld-fieldoffice",
"title": "Field Office",
"shortTitle": "Office",
"required": true,
"type": "select",
"description": "The field office where the event occurred.",
"settings": {
"style": "select",
"sourceId": "field-offices",
"multiple": false
}
},
{
"id": "nearmissfld-lob",
"title": "Line of Business",
"shortTitle": "Line of Business",
"required": true,
"type": "select",
"description": "The relevant line of business for the event.",
"settings": {
"style": "select",
"sourceId": "lines-of-business",
"multiple": false
}
},
{
"id": "nearmissfld-client",
"title": "Company",
"shortTitle": "Company",
"required": true,
"type": "select",
"description": "The associted company for the event.",
"settings": {
"style": "select",
"sourceId": "clients",
"multiple": false
}
},
{
"id": "nearmissfld-misscategory",
"title": "Category",
"shortTitle": "Category",
"required": true,
"type": "select",
"description": "Choose one of the categories that the event falls under.",
"pdfColumnName": "Category",
"settings": {
"style": "list",
"multiple": false,
"items": [
{
"label": "Working",
"value": "working"
},
{
"label": "Driving",
"value": "driving"
},
{
"label": "Environmental",
"value": "environmental"
}
]
}
},
{
"id": "nearmissfld-workingcategory-type",
"title": "Working Category",
"shortTitle": "Working Category",
"required": true,
"type": "select",
"pdfColumnName": "Sub Category",
"description": "Choose one of the sub-categories that the event falls under.",
"settings": {
"style": "select",
"multiple": false,
"items": [
{
"label": "Awareness",
"value": "awareness"
},
{
"label": "Unsafe Action",
"value": "unsafe-action"
},
{
"label": "Unsafe/Defective Equipment",
"value": "unsafe-defective-equipment"
},
{
"label": "Failure to Secure",
"value": "failure-to-secure"
},
{
"label": "Working on Live Equipment",
"value": "live-equipment"
},
{
"label": "Unsafe Position",
"value": "unsafe-position"
},
{
"label": "Walking/Working Surface",
"value": "walk-work-surface"
},
{
"label": "Trenching/Shoring",
"value": "trenching-shoring"
},
{
"label": "Bites/Stings",
"value": "bites-stings"
},
{
"label": "Housekeeping",
"value": "housekeeping"
},
{
"label": "Failure to Use PPE",
"value": "fail-to-use-ppe"
},
{
"label": "Improper Tool",
"value": "improper-tool"
}
]
},
"showif": {
"data": {
"fieldId": "nearmissfld-misscategory",
"settings": {
"values": [
"working"
]
}
}
}
},
{
"id": "nearmissfld-drivingcategory-type",
"title": "Driving Category",
"shortTitle": "Driving Category",
"required": true,
"type": "select",
"description": "Choose one of the sub-categories that the event falls under.",
"pdfColumnName": "Sub Category",
"settings": {
"style": "select",
"multiple": false,
"items": [
{
"label": "Failure to Yield",
"value": "failure-to-yield"
},
{
"label": "Animal",
"value": "animal"
},
{
"label": "Pedestrian",
"value": "pedestrian"
},
{
"label": "Lane Change",
"value": "lane-change"
},
{
"label": "Improper Passing",
"value": "improper-passing"
},
{
"label": "Improper Following",
"value": "improper-following"
},
{
"label": "Unsafe/Defective Vehicle",
"value": "unsafe-defective-vehicle"
},
{
"label": "Unsafe Speed",
"value": "unsafe-speed"
},
{
"label": "Harsh Acceleration/Deceleration",
"value": "harsh-accel-decel"
},
{
"label": "Parking",
"value": "parking"
},
{
"label": "Load not Secure",
"value": "load-not-secure"
},
{
"label": "Awareness/Attitude",
"value": "awareness-attitude"
},
{
"label": "Backing",
"value": "backing"
},
{
"label": "Improper Turning",
"value": "improper-turning"
},
{
"label": "Unsafe Road Conditions",
"value": "unsafe-road-conditions"
}
]
},
"showif": {
"data": {
"fieldId": "nearmissfld-misscategory",
"settings": {
"values": [
"driving"
]
}
}
}
},
{
"id": "nearmissfld-environmentalcategory-type",
"title": "Environmental Category",
"shortTitle": "Environmental Category",
"required": true,
"type": "select",
"description": "Choose one of the sub-categories that the event falls under.",
"pdfColumnName": "Sub Category",
"settings": {
"style": "select",
"multiple": false,
"items": [
{
"label": "Spill Release",
"value": "spill-release"
},
{
"label": "Unsafe/Defective Equipment/Machinery",
"value": "unsafe-def-equip-machine"
},
{
"label": "Improper Containment",
"value": "improper-containment"
},
{
"label": "Improper Layout",
"value": "improper-layout"
},
{
"label": "Airborne",
"value": "airborne"
},
{
"label": "Failure to Secure",
"value": "failure-to-secure"
},
{
"label": "Unsafe Action",
"value": "unsafe-action"
},
{
"label": "Inadequate Supplies",
"value": "inadequate-supplies"
}
]
},
"showif": {
"data": {
"fieldId": "nearmissfld-misscategory",
"settings": {
"values": [
"environmental"
]
}
}
}
},
{
"id": "nearmissfld-bodypart",
"title": "Body Part Potentially Affected",
"shortTitle": "Body Part",
"required": false,
"type": "select",
"description": "Choose which body part(s) would have been affected.",
"settings": {
"style": "select",
"multiple": true,
"items": [
{
"label": "Head/Face",
"value": "head-face"
},
{
"label": "Eye",
"value": "eye"
},
{
"label": "Neck/Throat",
"value": "neck-throat"
},
{
"label": "Shoulder/Arm",
"value": "shoulder-arm"
},
{
"label": "Hand/Finger",
"value": "hand-finger"
},
{
"label": "Back",
"value": "back"
},
{
"label": "Knee/Leg",
"value": "knee-leg"
},
{
"label": "Foot/Toe",
"value": "foot-toe"
},
{
"label": "Body Systems",
"value": "body-systems"
}
]
}
},
{
"id": "nearmissfld-severity",
"title": "Severity",
"shortTitle": "Severity",
"required": true,
"type": "select",
"description": "Choose the severity of the near miss.",
"settings": {
"style": "list",
"multiple": false,
"items": [
{
"label": "Low",
"value": "low"
},
{
"label": "Medium",
"value": "medium"
},
{
"label": "High",
"value": "high"
},
{
"label": "Critical",
"value": "critical"
}
]
}
},
{
"id": "nearmissfld-recurrence",
"title": "Probability of Recurrence",
"shortTitle": "Recurrence",
"required": true,
"type": "select",
"description": "Choose the probability that the situation will happen again.",
"settings": {
"style": "list",
"multiple": false,
"items": [
{
"label": "Rare",
"value": "rare"
},
{
"label": "Random",
"value": "random"
},
{
"label": "Frequent",
"value": "frequent"
},
{
"label": "Accepted Risk",
"value": "accepted"
}
]
}
},
{
"id": "nearmissfld-actiontaken",
"title": "Action Taken for Hazard",
"shortTitle": "Action",
"required": false,
"type": "select",
"description": "Choose the type of action that was taken.",
"settings": {
"style": "list",
"multiple": false,
"items": [
{
"label": "Stop Work",
"value": "stop-work"
},
{
"label": "Communication",
"value": "communication"
},
{
"label": "Immediate Change",
"value": "immediate-change"
},
{
"label": "Gradual Change",
"value": "gradual-change"
}
]
}
},
{
"id": "nearmissfld-managementofhazard",
"title": "Management of Hazard",
"shortTitle": "Managment",
"required": false,
"type": "select",
"description": "Choose the type of management for the hazard.",
"settings": {
"style": "list",
"multiple": false,
"items": [
{
"label": "Eliminate",
"value": "eliminate",
"score": null
},
{
"label": "Control",
"value": "control",
"score": null
},
{
"label": "Protect",
"value": "protect",
"score": null
},
{
"label": "Accept",
"value": "accept",
"score": null
}
],
"scan": false,
"sourceId": "",
"previewId": "",
"defaultIds": [],
"tags": [],
"showAllOnOutput": false
},
"hideMoreButton": false,
"hideOutputs": false,
"hideFilters": false,
"hideVoid": true,
"hidden": false,
"rememberValue": false,
"pdfColumnName": "Management"
},
{
"id": "nearmissfld-description",
"title": "Description of Incident",
"shortTitle": "Description",
"required": true,
"type": "text",
"description": "Please describe the incident in full detail.",
"pdfColumnName": "Note",
"settings": {
"texttype": "multiline"
}
},
{
"id": "nearmissfld-attachments",
"title": "Attach Photos",
"shortTitle": "Photos",
"required": false,
"type": "attachments",
"description": "Please upload any related attachments.",
"pdfColumnName": "Attachments",
"settings": {}
}
],
"created": 1476721596311
}
}
}
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. |