Admin¶

Usage
Resources
Users (Simple)
Projects
Surveys
Submissions
Timezone
Get a PDF of a submitted Record
Edit a submission in a Webform
Change current organisation

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

Usage ¶

GET /api/v1/misc/adminreport/usage/(int: year)/(int: month)/(string: userIdent)¶

For servier releases prior to 24.04 use "/surveyKPI/adminreport/usage/(int: year)/(int: month)/(string: userIdent)"

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. The API request stopped working in version 21.11 as this reporting usage for all users became too lengthy. The reports generated from the user interface now run in the background and can later be downloaded from the reports page. However this API call is back in version 21.12 with the addition of one more path parameter for the user ident. So it now downloads usage for only a single user.

Example request:

GET /api/v1/misc/adminreport/usage/2018/1/sal HTTP/1.1
Host: sg.smap.com.au
Download: xlsx

Query Parameters:
	project (boolean) -- Show usage by project survey (boolean) -- Show usage by survey device (boolean) -- Show usage by device inc_temp (boolean) -- Include temporary and anonymous users o_id (int) -- Organisation Id. Can be used if the calling user has organisational administration privilege to get details on a user in a different organisation

Example response:

Usage by User

Resources ¶

GET /api/v1/misc/media¶

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

For server releases prior to 24.04 use the URL: "/surveyKPI/upload/media".

Example response:

https://sg.smap.com.au/api/v1/misc/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:
	Authorization -- basic
Status Codes:	200 OK -- no error

POST /api/v1/misc/media¶

Synposis:	Upload a media file.

For server releases prior to 24.04 use the URL: "/surveyKPI/upload/media".

Example request:

curl -u xxxx -i -X POST -H "Content-Type: multipart/form-data" -F "data=@phone.jpg" -F "itemName=my_phone" https://sg.smap.com.au/api/v1/misc/media/upload/media

Query Parameters:

data -- The media file to upload.
surveyId -- (Optional) The id of a survey if you want the media file to only be available to that survey.
itemName -- (Optional, requires version 23.06) The name of the resource. The default is to use the filename without the extension.
action -- (Optional, requires version 23.06) Set to "replace" in order to force replacement of an existing resource with the same name.

Users (Simple)¶

GET /api/v1/misc/userList/simple¶

Synposis:	Get a list of users in the current organisation of the user making the API call.

For server releases prior to 24.04 use the URL: "surveyKPI/userList/simple".

Example response:

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

[
  {
    "id": 2,
    "ident": "neil",
    "name": "Neil Penman"
  },
  {
    "id": 3,
    "ident": "tom",
    "name": "Tom"
  }
]

Status Codes:	200 OK -- no error

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:
	Authorization -- basic
Status Codes:	200 OK -- no error

Surveys ¶

Get ¶

GET /api/v1/admin/surveys/(project id)¶

Synposis:	Get a list of surveys with details on each within the specified project. Projects can be found using Projects.

Example response:

https://sg.smap.com.au/api/v1/admin/surveys/17

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

[
  {
    "id": 116,
    "e_id": 0,
    "o_id": 0,
    "p_id": 17,
    "ident": "s17_115",
    "displayName": "csvtest",
    "task_file": false,
    "timing_data": false,
    "audit_location_data": false,
    "track_changes": false,
    "deleted": false,
    "blocked": false,
    "hasManifest": false,
    "forms": [],
    "optionLists": {},
    "styleLists": {},
    "serverCalculations": {},
    "sscList": [],
    "languages": [],
    "surveyManifest": [],
    "filters": {},
    "changes": [],
    "meta": [],
    "roles": {},
    "instance": {},
    "managed_id": 0,
    "version": 2,
    "loadedFromXLS": true,
    "exclude_empty": false,
    "projectName": "tx",
    "projectTasksOnly": false,
    "hideOnDevice": false,
    "dataSurvey": true,
    "oversightSurvey": true,
    "groupSurveyId": 0,
    "links": {
      "mailouts": "https://ubuntu1804.smap.com.au/api/v1/mailout/s17_115?links=true"
    }
  }
]

Query Parameters:
	links (boolean) -- Return links to other survey related data.
Request Headers:
	Authorization -- basic
Status Codes:	200 OK -- no error

Get Accessible ¶

GET /api/v1/misc/surveys/idents¶

Synposis:	Get a list of survey names and their identifier and project name that are accessible by the calling user. (version 21.05+)

For server releases prior to 24.04 use the URL: "/surveyKPI/surveys/idents".

Example response:

https://sg.smap.com.au/api/v1/misc/surveys/idents

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

    [
        {
            "id": 296,
            "project": "A project",
            "name": "Audit this",
            "ident": "s1_20363"
        },
        {
            "id": 298,
            "project": "A project",
            "name": "Beneficiary List",
            "ident": "s1_21255"
        },
        {
            "id": 299,
            "project": "A project",
            "name": "Geotrace Line Form_ Draft (4)",
            "ident": "s1_30057"
        },
        {
            "id": 321,
            "project": "A project",
            "name": "Literacy_Assessment_test",
            "ident": "s1_29888"
        }
    ]

Request Headers:
	Authorization -- basic
Status Codes:	200 OK -- no error

Upload ¶

POST /api/v1/misc/upload/surveytemplate¶

Synposis:	Upload a survey template in the spreadsheet format

For server releases prior to 24.04 use the URL: "/surveyKPI/surveys/idents".

Example request:

curl -u xxxx -i -X POST -H "Content-Type: multipart/form-data" -F "fileupload=@file.xlsx" -F templateName=name -F projectId=10 -F groupsurvey=0 https://sg.smap.com.au/api/v1/misc/upload/surveytemplate

Query Parameters:
	fileupload -- The name of the spreadsheet to upload templateName -- The name to call the uploaded survey
Query:	projectId: The id of the project to store the survey in
Query:	groupsurvey: The id of the survey that you want to group this new survey with. (optional). If you do include it set it to zero to specify no group

Submissions ¶

GET /api/v1/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/submissions

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 (integer) -- 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 (integer) -- 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 (integer) -- 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 (text) -- Return the submissions for the specified user. tz (text) -- 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. survey_ident (text) -- Only return data for the specified survey (version 21.01+)
Request Headers:
	Authorization -- basic
Status Codes:	200 OK -- no error

Timezone ¶

GET /api/v1/misc/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.

For server releases prior to 24.04 use the URL: "/surveyKPI/utility/timezones".

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:
	Authorization -- basic
Status Codes:	200 OK -- no error

Get a PDF of a submitted Record ¶

GET /api/v1/misc/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.

For server releases prior to 24.04 use the URL: "/surveyKPI/utility/timezones".

Query Parameters:
	instance -- (Required) The instance id of the record you want to retrieve. tz (string) -- Set to a valid time zone.
Request Headers:
	Authorization -- basic
Status Codes:	200 OK -- no error

Edit a submission in a Webform ¶

GET /webForm/(survey ident)¶

Query Parameters:
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.
	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:
	Authorization -- basic
Status Codes:	200 OK -- no error

Change current organisation ¶

GET /api/v1/users/organisation/(organisation name)¶

Synposis:	Set the users organisation to the value specified in "organisation name". Available in server version 21.03+.

Example response:

https://sg.smap.com.au/api/v1/users/organisation/head%20office

HTTP/1.1 200 OK
Vary: Accept

Request Headers:
	Authorization -- basic
Status Codes:	200 OK -- no error