Admin

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)/(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 /surveyKPI/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

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.jpg" -F "itemName=my_phone" https://sg.smap.com.au/surveyKPI/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 /surveyKPI/userList/simple
Synposis:Get a list of users in the current organisation of the user making the API call.

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:

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:

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:
 
Status Codes:

Get Accessible

GET /surveyKPI/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+)

Example response:

https://sg.smap.com.au/surveyKPI/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:
 
Status Codes:

Upload

POST /surveyKPI/upload/surveytemplate
Synposis:Upload a survey template in the spreadsheet format

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/surveyKPI/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:
 
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 (string) -- 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:

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:
 
Status Codes: