REST API Technical Specification

Poimapper API Technical Specification

Technical specification for the Poimapper Portal REST API.

Overview

This document describes the technical specification of the Poimapper Portal REST API.
The API is used to fetch data from the database and write data to the database.

Login

Authenticate the user with the system and obtain the auth_token JSON object.

POST
https://portal.poimapper.com/json/auth/login

Request parameters

Type	Parameter	Value
POST	`userName`	string
POST	`password`	string
POST	`instance`	string

Response

Status	Response
200	`{ "auth_token": <auth_token> }` — auth_token (Object)
400	`{"error":"Please provide username."}`
400	`{"error":"Please provide password."}`
400	`{"error":"Please provide account name."}`
401	`{"error":"Invalidaccount name."}`
401	`{"error":"Incorrect username or password."}`
500	`{"error":"Something went wrong. Please try again later."}`

Authentication token: The auth_token is an object that contains the username, user ID,
and the session key. The cookies returned in the response need to be present
in all further requests. The key must also be sent with all
client requests after logging in. The key helps the server validate the request source.

Sample server response

{
  "userName": "simon",
  "key": "7CDE412E756D7967EA2BC0D02BF44416",
  "id": "29",
  "groupId": 0,
  "parentGroup": 0,
  "editOwn": false,
  "readOwn": false,
  "canDelete": true,
  "assignedLocationOnly": false,
  "canDeleteall": true,
  "markerPreference": "form",
  "locations": "159,180,181",
  "forms": "362273 ,470001",
  "users": "undefined",
  "dates": "null;null",
  "loadSession": "false",
  "loadDataAutomatically": "true",
  "clusterMap": "true",
  "lang": "en"
}

Fetch List of Questionnaires and their Questions

Fetch forms and the questions.

POST
https://portal.poimapper.com/json/formlists/user/<user_id>

Header parameters

Type	Parameter	Description
HEAD	`key`	The key given in the response to `/JSON/auth/login`.
HEAD	`userId`	The username used to log in to Poimapper.

Note: user_id is the integer value given in the login response,
for example "id": "29".

Response

Status	Response
200	Questionnaire list object.
500	`{"error":"Something went wrong. Please try again later."}`

Sample response

{
  "questionnaireList": {
    "questionnaire": [],
    "id": "Survey6804861558685259111",
    "name": "Form list name",
    "language": "en",
    "surveyID": "27344",
    "version": "1785"
  }
}

The response gives details of the forms (identifier), number of POIs by count,
details of the questions, location labels of the location hierarchy, if any,
and related information.

Question attributes

Attribute	Description
ID	Unique alphanumeric string for a given question.
Type	Type of question, such as `IntQuestion`, `StringQuestion`, `FloatQuestion`, or `SingleSelect`.
Text	Text displayed to the user as the question text.
Invisible	Boolean indicating whether the question is shown to the user. Questions hidden in Form Builder have `Invisible` set to true.
Optional	Determines whether a question must be answered. If false, the question is mandatory before data can be saved.
Regexp	Regular expression containing custom validation rules for the question.
Maxlen	Maximum length of the answer. Empty means no limit.
Minlen	Minimum expected length of the answer.
Default	Default value pre-filled for the question in the form.
UseLastSavedValue	If true, the last saved value is pre-filled for the next data point.
AttachImage	If true, the question supports attached images.
accept	Used with File questions to specify accepted MIME types.
validatefield	Boolean indicating whether the field has a validation list.
validationlist	Validation list values, usually separated with a semicolon.
hideInDevice	If true, the question is not displayed on the mobile device.
hideInPortal	If true, the question is not displayed in the Data Viewer.
hideInPopup	If true, the question is not displayed in the map pop-up.
SPSSVariable	User-defined identifier used in logical conditions and as an SPSS export variable.
Script	Script executed for calculated value or skip logic questions.
Evaluate	Question ID evaluated for skip logic or calculated value questions.
Operation	Operations for numeric table columns. Supported values include `SUM` and `AVERAGE`.
readOnlyInDevice	Boolean determining whether the question is read-only on the device.
includeFile	Boolean indicating whether file attachments are supported.
edit	Specifies user roles that can edit the question.
view	Specifies user roles that can view the question.
RunOnCreate	If true, a calculated value question is executed only once.
AlertText	Custom warning text shown when there is a problem with entered values, particularly for numeric questions.
SalesForceId	Boolean indicating whether the question is a Salesforce ID field.
EnableBarCodeScan	Boolean enabling barcode scanning, usually for text questions.
PreserveValue	Used in scheduling. If true, a scheduled POI’s question value is preserved; otherwise it is reset on the device.

Fetch List of Locations

Fetch a list of locations for a location hierarchy associated with a group.

POST
https://portal.poimapper.com/json/app/locations/list/<user_id>

Header parameters

Type	Parameter	Description
HEAD	`key`	The key given in the response to `/json/auth/login`.
HEAD	`userId`	The username used to log in to Poimapper.

Note: user_id is the integer value returned in the login response.

Response

Status	Response
200	`[]`
500	`{"error":"Something went wrong. Please try again later."}`

Sample location response

[
  {
    "key": "21120",
    "title": "Province A",
    "zoom": "0",
    "parent": "-1",
    "level": "0",
    "isFolder": false,
    "isLazy": true,
    "loaded": false,
    "lowerPostalCode": [1234],
    "upperPostalCode": [5678]
  },
  {
    "key": "21121",
    "title": "County 1",
    "zoom": "0",
    "parent": "21120",
    "level": "1",
    "isFolder": false,
    "isLazy": true,
    "loaded": false,
    "lowerPostalCode": [1111],
    "upperPostalCode": [2222]
  },
  {
    "key": "21122",
    "title": "Sub-County 1",
    "zoom": "0",
    "parent": "21121",
    "level": "2",
    "isFolder": false,
    "isLazy": true,
    "loaded": false,
    "lowerPostalCode": [333],
    "upperPostalCode": [444]
  },
  {
    "key": "21126",
    "title": "Sub-County 2",
    "zoom": "0",
    "parent": "21121",
    "level": "2",
    "isFolder": false,
    "isLazy": true,
    "loaded": false,
    "lowerPostalCode": [567],
    "upperPostalCode": [789]
  },
  {
    "key": "21123",
    "title": "Village 1",
    "zoom": "0",
    "parent": "21122",
    "level": "3",
    "isFolder": false,
    "isLazy": true,
    "loaded": false,
    "lowerPostalCode": [555],
    "upperPostalCode": [666]
  },
  {
    "key": "21124",
    "title": "Village 2",
    "zoom": "0",
    "parent": "21122",
    "level": "3",
    "isFolder": false,
    "isLazy": true,
    "loaded": false,
    "lowerPostalCode": [777],
    "upperPostalCode": [888]
  },
  {
    "key": "21125",
    "title": "Village 3",
    "zoom": "0",
    "parent": "21122",
    "level": "3",
    "isFolder": false,
    "isLazy": true,
    "loaded": false,
    "lowerPostalCode": [678],
    "upperPostalCode": [876]
  },
  {
    "key": "21127",
    "title": "Village 4",
    "zoom": "0",
    "parent": "21126",
    "level": "3",
    "isFolder": false,
    "isLazy": true,
    "loaded": false,
    "lowerPostalCode": [123],
    "upperPostalCode": [345]
  },
  {
    "key": "21128",
    "title": "Village 5",
    "zoom": "0",
    "parent": "21126",
    "level": "3",
    "isFolder": false,
    "isLazy": true,
    "loaded": false,
    "lowerPostalCode": [444, 456],
    "upperPostalCode": [556, 789]
  }
]

Location object attributes

Attribute	Description
key	Numeric value uniquely identifying the node. Used when location filters are needed when fetching data.
title	Name of the location.
parent	Key of the parent node. A value of `-1` means the node has no parent.
level	Numeric hierarchy level. Levels run from 0 through 3.
lowerPostalCode	Lower limit of the postal code for the location node.
upperPostalCode	Upper limit of the postal code for the location node.

Fetch List of Users

Fetch data of a given form.

POST
https://portal.poimapper.com/json/app/user/<user_id>

Header parameters

Type	Parameter	Description
HEAD	`key`	The key returned in the `/json/auth/login` response.
HEAD	`userId`	The username used to log in to Poimapper.

Note: user_id is the integer value returned in the login response.

Response

Status	Response
200	`[]`
500	`{"error":"Something went wrong. Please try again later."}`

Sample user response

[
  {
    "id": 894,
    "name": "user-admin",
    "groupId": 0,
    "active": true,
    "roles": null,
    "email": null,
    "otp": null,
    "accessSharedDataOnly": false,
    "samlUser": false,
    "firstLogin": false
  }
]

User object attributes

Attribute	Description
id	Numeric value that uniquely identifies a user.
name	Username of the user.

Fetch Data for a given Form

Fetch data of a given questionnaire/form.

GET
https://portal.poimapper.com/json/app/answer/<questionnaire_id>?version=<version_number>

Header parameters

Type	Parameter	Description
HEAD	`key`	The key given in the response to `/json/auth/login`.
HEAD	`userId`	The username used to log in to Poimapper.

version is the integer value for the version number of the answer format.
The most recent version recommended by the document is 5.

Response

Status	Response
200	`[{}]`
500	`{"error":"Something went wrong. Please try again later."}`

Example requests

Filter by user and editing status

/answer/Form79693315?version=2&query={"user_id": 2, "needs_editing": true}

Return selected fields

/answer/Form79693315?version=2&fields=user_id,questionnaire_id

Filter by locations

/answer/Form79693315?version=2&query={"location1": [1,2], "location2": 6}

Paginate using row_id

/answer/Form79693315?version=2&offset=1224&limit=1000

Parameters

Parameter	Description
version	Mandatory. The recommended and most recent version is 5.
limit	Optional. Number of results to return. If fewer than the limit are returned, there is no need to request more currently.
offset	Optional. Returns answers with `row_id` greater than the offset value. Use the greatest `row_id` returned by the previous request.
fields	Optional. Fields to return. `row_id` is always returned even if not included. If omitted, all fields are returned.
query	Optional object of fields to match for returned answers.
filter	Array of filter objects. Each item represents conditions applied to the data.
externalId	Optional. When set to 1, uses the external integration ID or reference name as the key for JSON object values, in that order of preference.
property	Filter property value.
condition	String conditions: `CONTAINS`, `DOES_NOT_CONTAIN`, `STARTS_WITH`, `ENDS_WITH`. Other field types support `EQUAL` and `NOT_EQUAL`; numeric fields also support `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL`, and `LESS_THAN_OR_EQUAL`.
field	Name of the field.
value	Value of the filter.
operator	`0` = AND, `1` = OR.
condition2	JSON object containing a second condition to apply with the operator.
sort	JSON object representing sorting to be applied to the result.
sortdatafield	Field name to sort by.
sortorder	`asc` for ascending or `desc` for descending.
off	Offset value when paginating results. Returns results from this index.
from	Source of the request. For Data Viewer requests, use `portal`. This adds `formName`, `formId`, `portaledittime`, and converts `phoneedittime` to seconds.
closest	Coordinates in `latitude:longitude` format. Returns POIs closest to the coordinates when the relevant form option is enabled.

Important:field corresponds to the ID of a question. It can be used to retrieve
answers for a specific question or set of questions.

Example response

[
  {
    "id": "91bba030-3eff-4722-91d2-94de7ec0bc93",
    "name": "new query this one",
    "questionnaire_id": "F423B0628A3A120A",
    "user_id": 11,
    "needs_editing": false,
    "modified": 1405588263205,
    "f1E1FF6292D1C316": null,
    "entryTime": null,
    "phoneEditTime": 0,
    "portalEditTime": 15595,
    "portalEditEntry": 1405588263000,
    "countQuestion": 1,
    "row_id": 3002,
    "comments": [
      {
        "username": "dda",
        "date": "2015-02-02 10:53:49.62295",
        "comment": "foo"
      }
    ],
    "files": [
      {
        "id": 27,
        "rowId": 3002,
        "questionId": "",
        "mimeType": "image/png",
        "fileSize": 69102,
        "fileName": "Screenshot 2014-07-16 17.13.54.png",
        "url": "https://poimapper-uploads.s3.amazonaws.com/..."
      }
    ]
  }
]

Additional response attributes

Attribute	Description
needs_editing	Boolean indicating whether the data point has been marked as needing editing.
rowId	Unique numerical value automatically assigned to each data point. It differs even for the same data point in a history trace.
id	Unique GUID for a data point. It remains the same across the history trace.
gps_accuracy	GPS accuracy, in meters, depending on the device used.
url	Unique URL for a file or image. The link expires after some time.
mimeType	Media type of the object, for example `image/png`.
fileSize	File/image size in bytes.
fileName	Name of the file/image, if any.
modified	Timestamp of the last modification.
comments	Comments associated with a data point, including comment text, timestamp, and username.
entryTime	Timestamp when the data point was added using the device. Null when added through the Data Viewer portal.
phoneEditTime	Milliseconds used to add or edit the data point in the mobile application.
portalEditTime	Milliseconds used to add or edit the data point in the Data Viewer.
portalEditEntry	Timestamp when the data point was added in the Data Viewer. Null when added through the mobile application.

Save Data for a given Form

Save form data by sending a JSON structure containing question identifiers and their response values.

POST
https://portal.poimapper.com/json/app/answer/<form_id>

The form_id parameter is the alphanumeric ID of the form.

Core fields

Field	Description
ID	Assigned UUID of the data.
ModifiedTime	Tracks the time the data was last updated. Send a UNIX timestamp value.
entryTime	Local time when data entry was performed on the mobile app.
phoneEditTime	Time the data point was open in the mobile app before saving.
portalEditTime	Time the data point was open in the Portal before saving.
portalEditEntry	Timestamp when data entry was performed in the Portal.
createdBy	User who initially created the data.
countQuestion	Default value of 1 for reports and charts functionality.

Selection options:Use the option ID as the answer value for a ListItem option.
For multiple select options, separate the option IDs with a comma.

Example request payload

{
  "Coordinates": "4.214943141390651 33.04687500000001",
  "Name": "Sample Write API Test Data",
  "f4F8BD60D0F969E4": 28,
  "f9EC852C3998B2F8": "Opt9CA27100DA7833A"
}

Successful response

{
  "status": "OK",
  "message": "Data Saved",
  "_id": "689a45018f61571a0ce5f9e1",
  "id": "cf801983-7d4c-4a06-ade9-01d535ccdd25",
  "dataPoint": <json>
}

The _id is the unique numeric identifier for the data in the database
and changes when the row is updated. The id is the alphanumeric unique
identifier that does not change across versions of a data point and is required to
update it in future. The dataPoint contains the saved datapoint JSON
together with the generated alphanumeric ID and row ID.

Location hierarchy

If a form has a location hierarchy, location values can be updated by specifying
location IDs in the JSON payload. The keys are location1,
location2, location3, and location4,
starting with the topmost parent.

{
  "Coordinates": "4.214943141390651 33.04687500000001",
  "Name": "Sample Write API Test Data",
  "f4F8BD60D0F969E4": 28,
  "f9EC852C3998B2F8": "Opt9CA27100DA7833A",
  "location1": 95,
  "location2": 96,
  "location3": 97,
  "location4": 98
}

Update Answer Values for a given Form

Existing data can be updated through the API using the unique UUID of the data point.

The UUID can be obtained by exporting form data to Excel or CSV in the Portal
and selecting Include unique data identifier. The UUID is also returned
when data is saved.

PUT
https://portal.poimapper.com/json/app/answer/<form_id>/<uuid>

Example request URL

https://portal.poimapper.com/json/app/answer/F28FC59F89A2C79F/cf801983-7d4c-4a06-ade9-01d535ccdd25

Request payload

{
  "Coordinates": "4.214943141390651 33.04687500000001",
  "Name": "Sample Write API Test Data Updated",
  "f4F8BD60D0F969E4": 32,
  "f9EC852C3998B2F8": "Opt9CA27100DA7833A"
}

Delete data for a given Form

Delete form data by specifying the UUIDs of the data points in the request payload.

POST
https://portal.poimapper.com/json/app/delete/multiple/<form_id>

The form_id is the alphanumeric Questionnaire ID.
It can be read from the Questionnaire ID tag of the form’s XML.

Request payload

{
  "arguments": [
    "0d25c826-328f-4fcf-a091-cc43566f04ab",
    "308a0d04-c4d8-4845-81c0-3d05582ecce4"
  ]
}

Successful response

{
  "status": "OK",
  "message": "POIs Deleted successfully",
  "row_id": 0
}

If status is “fail”:The request may have issues with the payload. Check that
arguments is a JSON array.

Reducing Child Abuse With A Country Wide Approach

The Challenge of Reducing Child Abuse

The VuruguMapper Initiative

Scaling Up

Recent Posts

Solutions

Language

Poimapper