Usage


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 and survey.

To use these functions you will need "admin" privilege

Methods

URL Request Type / Format Description Version Example
/surveyKPI/adminreport/usage/ {year}/ {month} GET / Excel File The number of submissions in the specified month by user 18.10+ https://sg.smap.com.au/surveyKPI/adminreport/usage/2018/1

Parameters

Parameter Description Version Example
year Specify the year of the data to be retrieved (required) 18.10+ https://sg.smap.com.au/surveyKPI/adminreport/usage/2018/1
month Specify the month of the data to be retrieved (required). Must be between 1 and 12 inclusive. 18.10+ https://sg.smap.com.au/surveyKPI/adminreport/usage/2018/1
project=true Show usage by project as well as user 18.10+ https://sg.smap.com.au/surveyKPI/adminreport/usage/2018/1?project=true
survey=true Show usage by survey as well as project and user 18.10+ https://sg.smap.com.au/surveyKPI/adminreport/usage/2018/1?survey=true

Resources


Resources are files used by forms. The following types of resources can be managed through the API:

  1. Media: For example a CSV file that contains choices or a photograph that is used to illustrate a choice in a select one question.

Media

Service Request Type / Format Description Version Example
/surveyKPI/upload/media GET JSON Get a list of the media available in the users current organisation. The response includes URLs to:
  • download the file
  • download a thumb nail
  • delete the file
 17.10+ https://sg.smap.com.au/surveyKPI/upload/media
/surveyKPI/upload/media POST Upload a new file to the organisation. 17.10+ curl -u xxxx -i -X POST -H "Content-Type: multipart/form-data" -F "data=@phone.jpg" https://sg.smap.com.au/surveyKPI/upload/media

Parameters

Parameter Description Version Example
survey_id Retrieve a list of files or upload media only for the survey with specified id. You can also use the form field survey_id when posting media. 17.10+ https://sg.smap.com.au/surveyKPI/upload/media?survey_id=1778

Projects


The projects API allows manipulation of projects

Methods

URL Request Type / Format Description Version Example
/api/v1/admin/projects GET / Json A list of projects 19.05+ https://sg.smap.com.au/api/v1/admin/projects

Parameters

Parameter Description Version Example
all Set to "true" in order to return all projects in the organisation. Otherwise the list of projects will only contain those projects that they calling user is a member of 19.05+ https://sg.smap.com.au/api/v1/admin/projects?all=true
links Set to "true" in order to show links to other data where the project id is a key. For example task groups that are in a project. 19.05+ https://sg.smap.com.au/api/v1/admin/projects?all=true&links=true

Submissions


Methods

URL Request Type / Format Description Version Example
/api/v1/submissions GET / Json A list of submissions in the calling user's organisation. The data is always returned as latest first. 19.05+ https://sg.smap.com.au/api/v1/submissions

Parameters

Parameter Description Version Example
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. 19.05+ https://sg.smap.com.au/api/v1/submissions?limit=10
start The id to start from (prikey). 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. 19.05+ https://sg.smap.com.au/api/v1/submissions?limit=10&start=1000
links Set to "true" in order to show links to other views of the submitted data 19.05+ https://sg.smap.com.au/api/v1/submissions?limit=10&links=true
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. 19.05+ https://sg.smap.com.au/api/v1/submissions?stopat=1001
user Return the submissions for the specified user. 19.05+ https://sg.smap.com.au/api/v1/submissions?user=karen
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. 19.05+ https://sg.smap.com.au/api/v1/submissions?stopat=1001&tz=Australia/Brisbane

Time zones


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.

Methods

URL Request Type / Format Description Version Example
/surveyKPI/utility/timezones GET / Json 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. 19.05+ https://sg.smap.com.au/surveyKPI/utility/timezones

PDF of Submission


Methods

URL Request Type / Format Description Version Example
/surveyKPI/pdf/{survey instance}?instance={instance id} GET / Json 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. 19.05+

Parameters

Parameter Description Version Example
tz Set to "a valid time zone. (Refer to timezones api call to get a list of valid time zones). 19.05+

Edit a submission in a webform


Methods

URL Request Type / Format Description Version Example
/webForm/{survey instance}?datakey=instanceid&datakeyvalue={instance id} GET / Json Opens the submission in a webform for editing. There are two mandatory parameters; datakey - just specify instanceid, and the datakey value where you put the instanceid that you want to edit. You can use the data API passing a parameter of links=true to see the URLs. 19.05+