Admin API

This API provides access to administration functions. To use these functions you will need admin privilege.

Usage

GET /surveyKPI/adminreport/usage/(int: year)/(int: month)
Synposis:The usage API allows you to view the number of submissions made by each user in a month. These can be further broken down by project, survey and device.

Example request:

GET /surveyKPI/adminreport/usage/2018/1 HTTP/1.1
Host: sg.smap.com.au
Accept: xlsx
Query Parameters:
 
  • project (boolean) – Show usage by project
  • survey (boolean) – Show usage by survey
  • device (boolean) – Show usage by device

Example response:

Usage by User

Usage by User

Resources

GET /surveyKPI/upload/media
Synposis:Get a list of the media Shared Resources available in the users current organisation. Includes images, video, audio and csv files.

Example response:

https://sg.smap.com.au/surveyKPI/upload/media

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
"files": [
{
"name": "a.jpg",
"url": "/surveyKPI/file/a.jpg/organisation",
"thumbnailUrl": "/surveyKPI/file/a.jpg/organisation?thumbs=true",
"deleteUrl": "https://sg.smap.com.au/surveyKPI/upload/media/organisation/1/a.jpg",
"type": "image",
"size": 7946,
"modified": "2019-04-21T22:32:42.000+0000"
},
{
"name": "b.jpg",
"url": "/surveyKPI/file/b.jpg/organisation",
"thumbnailUrl": "/surveyKPI/file/b.jpg/organisation?thumbs=true",
"deleteUrl": "https://sg.smap.com.au/surveyKPI/upload/media/organisation/1/b.jpg",
"type": "image",
"size": 7236,
"modified": "2019-04-21T22:32:42.000+0000"
},
{
"name": "c.jpg",
"url": "/surveyKPI/file/c.jpg/organisation",
"thumbnailUrl": "/surveyKPI/file/c.jpg/organisation?thumbs=true",
"deleteUrl": "https://sg.smap.com.au/surveyKPI/upload/media/organisation/1/c.jpg",
"type": "image",
"size": 1075,
"modified": "2019-04-21T22:32:42.000+0000"
},
{
"name": "camps.csv",
"url": "/surveyKPI/file/camps.csv/organisation",
"thumbnailUrl": "/images/csv.png",
"deleteUrl": "https://sg.smap.com.au/surveyKPI/upload/media/organisation/1/camps.csv",
"type": "csv",
"size": 103116,
"modified": "2019-09-12T06:36:19.000+0000"
}
]
}
Query Parameters:
 
  • survey_id – The id of a survey to return the media. If specified the media associated with the survey will be returned rather than the shared media for the organisaiton.
Request Headers:
 
Status Codes:
POST /surveyKPI/upload/media
synposis:Upload a media file.

Example request:

curl -u xxxx -i -X POST -H “Content-Type: multipart/form-data” -F “data=@phone.jpghttps://sg.smap.com.au/surveyKPI/upload/media

Query Parameters:
 
  • survey_id – The id of a survey if you want the media file to only be available to that survey.

Projects

GET /api/v1/admin/projects
Synposis:Get a list of projects.

Example response:

https://sg.smap.com.au/api/v1/admin/projects

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
{
"id": 1554,
"name": "tasks",
"desc": "",
"tasks_only": false,
"changed_by": "neil",
"changed_ts": "2019-11-09 04:19:22.83124+00"
}
]
Query Parameters:
 
  • all (boolean) – If set to true all projects will be returned. Otherwise only the project to which the user is currently assigned will be returned.
  • links (boolean) – Return links to other project related data.
Request Headers:
 
Status Codes:

Submissions

GET /api/v1/admin/submissions
Synposis:A list of submissions in the calling user’s organisation. The data is always returned as latest first

Example response:

https://sg.smap.com.au/api/v1/admin/aubmissions

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
{
"prikey": "856836",
"Survey Name": "pp",
"s_id": "14454",
"survey_ident": "s1_14454",
"instanceid": "uuid:7444b43e-dc6c-4037-9d84-06aaa4d181e2",
"Device": "355306069766014",
"Upload Time": "2019-11-09 01:35:59",
"Project": "A project",
"Instance Name": "",
"Instance ID": "uuid:7444b43e-dc6c-4037-9d84-06aaa4d181e2",
"Start Time": "2019-11-09 01:35:26",
"End Time": "2019-11-09 01:35:55",
"User": "neil"
},
{
"prikey": "856835",
"Survey Name": "v181203",
"s_id": "14439",
"survey_ident": "s1_14439",
"instanceid": "uuid:fcbaf0a5-8ceb-413b-b180-58fc995447c4",
"Device": "webform",
"Upload Time": "2019-11-08 23:25:48",
"Project": "A project",
"Instance Name": "",
"Instance ID": "uuid:fcbaf0a5-8ceb-413b-b180-58fc995447c4",
"Start Time": "2019-11-08 23:25:26",
"End Time": "2019-11-08 23:25:46",
"User": "neil",
"lon": 153.012455,
"lat": -27.448157
}
]
Query Parameters:
 
  • limit – Set to the number of records that you want to see. Since data is returned latest first then if you specify the limit as 10 you will see the last 10 submissions.
  • start – The id to start from (upload id). If you specify a start of 1,000 and a limit of 2 then uploads 999 and 998 will be returned. Note the id you specify in start will not be returned. You can use this parameter to page through the data setting the value of start to the oldest submission returned in the previous query.
  • stopat – When set do not go past the specified upload id. The data for the specified upload id is not returned. You can use this when reading the data as a feed. For example if you call the service and the latest submission has an id of 1001, then if you call the service again with stopat=1001 you will only get the new submissions.
  • user – Return the submissions for the specified user.
  • tz – Set to a valid time zone. (Refer to timezones api call to get a list of valid time zones). The upload time will be returned in this time zone.
  • links (boolean) – Return links to other submission related data.
Request Headers:
 
Status Codes:

Timezone

GET /surveyKPI/utility/timezones
Synposis:Many API calls include a timezone parameter so that dates can be returned in the specified time zone. This api returns the timezones that can be used.

Example response:

https://sg.smap.com.au/surveyKPI/utility/timezones

A list of timezones. Each timezone consists of an “id” and a name. The “id” is what you should use to identifity the time zone in a web service call. The name is just the “id” with the addition of the current hour offset from UTC. The timezones are returned in order of increasing offset.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
{
"id": "Pacific/Niue",
"name": "Pacific/Niue (-11:00)"
},
{
"id": "US/Samoa",
"name": "US/Samoa (-11:00)"
},
{
"id": "Pacific/Midway",
"name": "Pacific/Midway (-11:00)"
},
{
"id": "Pacific/Samoa",
"name": "Pacific/Samoa (-11:00)"
}
]
Request Headers:
 
Status Codes:

Get a PDF of a submitted Record

GET /surveyKPI/pdf/(survey ident)
Synposis:

Returns a PDF of the data in the submission. You can use the data API passing a parameter of links=true to see the URLs that will return a PDF of data.

Query Parameters:
 
  • instance – (Required) The instance id of the record you want to retrieve.
  • tz – Set to a valid time zone.
Request Headers:
 
Status Codes:

Edit a submission in a Webform

GET /webForm/(survey ident)
Synposis:

Opens the submission in a webform for editing. You can use the data API passing a parameter of links=true to see the URLs.

Query Parameters:
 
  • datakey – (Required) The column that holds the key of the record. Usually you would use “instanceid”
  • datakeyvalue – The value of the key that identified the record.
Request Headers:
 
Status Codes: