Data¶
This endpoint provides access to submitted data in JSON format. Where:
pk- the form unique identifierdataid- submission data unique identifierowner- username of the owner(user/organization) of the data point
GET JSON List of data end points¶
Lists the data endpoints accessible to requesting user, for anonymous access a list of public data endpoints is returned.
Reading this data needs public_data or a role on the form. See access to submissions.
GET /api/v1/data
Example¶
curl -X GET https://api.ona.io/api/v1/data
Response¶
[
{
"id": 4240,
"id_string": "dhis2form",
"title": "dhis2form",
"description": "dhis2form",
"url": "https://api.ona.io/api/v1/data/4240"
},
...
]
GET JSON List of data end points using limit operators¶
Lists the data endpoints accesible to the requesting user based on ‘start’ and/or ‘limit’ query parameters. Use the start parameter to skip a number of records and the limit parameter to limit the number of records returned.
GET /api/v1/data/{pk}?start=start_value
curl -X GET 'https://api.ona.io/api/v1/data/2?start=5'
GET /api/v1/data/{pk}?start=start_value&limit=limit_value
curl -X GET 'https://api.ona.io/api/v1/data/2?limit=2'
GET /api/v1/data/{pk}?start=start_value&limit=limit_value
curl -X GET 'https://api.ona.io/api/v1/data/2?start=3&limit=4'
Fetch XForm ODK data for all forms per account in csv format¶
Pull all form data for forms located within your account
Example¶
curl -X GET https://api.ona.io/api/v1/data.csv
Response¶
- ::
- description,id,id_string,title,url
,549,form1,First Form,https://stage-odk.ona.io/api/v1/data/549.csv ,569,form2,Second Form,https://stage-odk.ona.io/api/v1/data/569.csv ,570,Smallform,Smallform,https://stage-odk.ona.io/api/v1/data/570.csv
Stream XForm submission data in csv format¶
Example¶
curl -X GET https://api.ona.io/api/v1/data/1343.csv
Response¶
- ::
hello,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,2,n/a,uuid:6a477d27-343c-44c2-9204-bd42ec3e0796,77466,6a477d27-343c-44c2-9204-bd42ec3e0796,2021-02-23T14:14:47,2021-02-23T14:14:47,,,202001170844,,winny,0,0,True,1343 Test que,14,14,40.446947 27.283625 0 0,40.446947,27.283625,0,0,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,n/a,2,n/a,uuid:a09a9b71-b98a-4904-ab04-1ed162ab2b02,186964,a09a9b71-b98a-4904-ab04-1ed162ab2b02,2021-05-27T12:38:14,2021-05-27T12:38:14,,,202001170844,,winny,0,0,True,1343
GET JSON List of data end points filter by owner¶
Lists the data endpoints accessible to requesting user, for the specified
owner as a query parameter.
GET /api/v1/data?owner=owner_username
Example¶
curl -X GET https://api.ona.io/api/v1/data?owner=ona
GET JSON list of submitted data for a specific form¶
Provides a JSON list of submitted data for a specific form.
Note: Responses are automatically paginated when requesting a list of data that surpasses 10,000 records.
GET /api/v1/data/{pk}Example¶
curl -X GET https://api.ona.io/api/v1/data/22845
Response¶
[
{
"_id": 4503,
"_bamboo_dataset_id": "",
"_deleted_at": null,
"_edited": false,
"expense_type": "service",
"_xform_id": 22845,
"_xform_id_string": "exp",
"_geolocation": [
null,
null
],
"end": "2013-01-03T10:26:25.674+03",
"start": "2013-01-03T10:25:17.409+03",
"_duration": "",
"expense_date": "2011-12-23",
"_status": "submitted_via_web",
"today": "2013-01-03",
"_uuid": "2e599f6fe0de42d3a1417fb7d821c859",
"imei": "351746052013466",
"formhub/uuid": "46ea15e2b8134624a47e2c4b77eef0d4",
"kind": "monthly",
"_submission_time": "2013-01-03T02:27:19",
"_date_modified": "2013-01-03T02:29:20",
"_submitted_by": "onaio",
"required": "yes",
"_attachments": [],
"_tags": [],
"_notes": [],
"item": "Rent",
"amount": "35000.0",
"deviceid": "351746052013466",
"subscriberid": "639027...60317",
"_version": "1",
"_media_count": 0,
"_total_media": 0,
"_media_all_received": true
},
....
]
Request signed attachment URLs¶
Add signed_urls=true to JSON submission list or detail requests to receive
storage download URLs directly:
GET /api/v1/data/{pk}?signed_urls=true
GET /api/v1/data/{pk}/{dataid}?signed_urls=true
This replaces only _attachments[].download_url. Thumbnail links and the
response structure stay the same. Omitting the parameter or setting it to
false returns the usual /files links. Signing applies to paginated,
sorted, field-selected, and streaming JSON responses. Field selection must
include _attachments to receive attachment links.
Signed attachment access follows submission access, including when the attachment
was submitted by a different user. The data endpoint authorizes submissions
before their attachment URLs are generated or reused from cache. Missing,
deleted, or mismatched attachments, local or unsupported storage, and unavailable
signing retain their original /files links. Signed URLs are never saved in
submission JSON or history.
Deployments control link lifetime through ATTACHMENT_SIGNED_URL_EXPIRATION,
in seconds, with a default of 3600. Original attachment downloads through
/files use the same setting. Requests cannot override this lifetime.
The server caches signed URLs for at most the normal response cache lifetime and their remaining validity, with a 30-second safety margin. Known shorter credential lifetimes also limit reuse. Cache hits do not extend these deadlines. Buffered signed responses use private caching and ETags that change when the response or signed URLs change. Their freshness decreases on cache hits and conditional responses.
Signed JSON streams reuse cached URLs while processing submissions in bounded
batches. They send Cache-Control: private, max-age=0, must-revalidate without
ETag or Last-Modified validators, so revalidation returns the response body with
status 200. This avoids a preliminary attachment scan or buffering the dataset.
GET XML list of submitted data for a specific form¶
Provides an XML list of submitted data for a specific form.
GET /api/v1/data/{pk}.xml
Example¶
curl -X GET https://api.ona.io/api/v1/data/574.xml
Response¶
<submission-batch serverTime="2021-07-02T08:16:24.304534+00:00">
<submission-item bambooDatasetId="" dateCreated="2021-07-02T08:16:24.091445+00:00" duration="" edited="False" formVersion="2014111" lastModified="2021-07-02T08:16:24.206278+00:00" mediaAllReceived="True" mediaCount="1" objectID="1957" reviewComment="" reviewStatus="" status="submitted_via_web" submissionTime="2021-07-02T08:16:24" submittedBy="bob" totalMedia="1">
<data id="transportation_2011_07_25" version="2014111">
<transport>
<available_transportation_types_to_referral_facility>none</available_transportation_types_to_referral_facility>
<loop_over_transport_types_frequency>
<ambulance></ambulance>
<bicycle></bicycle>
<boat_canoe></boat_canoe>
<bus></bus>
<donkey_mule_cart></donkey_mule_cart>
<keke_pepe></keke_pepe>
<lorry></lorry>
<motorbike></motorbike>
<taxi></taxi>
<other></other>
</loop_over_transport_types_frequency>
</transport>
<image1 type="file">1335783522563.jpg</image1>
<meta>
<instanceID>uuid:5b2cc313-fc09-437e-8149-fcd32f695d41</instanceID>
</meta>
</data>
<linked-resources>
<attachments>
<id>50</id>
<name>1335783522563.jpg</name>
<xform>574</xform>
<filename>bob/attachments/574_transportation_2011_07_25/1335783522563.jpg</filename>
<instance>1957</instance>
<mimetype>image/jpeg</mimetype>
<download_url>/api/v1/files/50?filename=bob/attachments/574_transportation_2011_07_25/1335783522563.jpg</download_url>
<small_download_url>/api/v1/files/50?filename=bob/attachments/574_transportation_2011_07_25/1335783522563.jpg&suffix=small</small_download_url>
<medium_download_url>/api/v1/files/50?filename=bob/attachments/574_transportation_2011_07_25/1335783522563.jpg&suffix=medium</medium_download_url>
</attachments>
</linked-resources>
</submission-item>
<submission-item>
...
</submission-item>
</submission-batch>
Get FLOIP flow results for a specific form¶
Provides a list of rows of submitted data for a specific form. Each row contains 6 values as specified here. The data is accessed from the data endpoint by specifying the header Accept: "application/vnd.org.flowinterop.results+json".
- The values in each row are:
Timestamp- form submission timestampRow ID- Submission idContact ID- Name of the person who made the submission or null if unavailableQuestion ID- The question field nameResponse- The question responseResponse metadata- The question options or null if none
GET /api/v1/data/{pk} -H "Accept:application/vnd.org.flowinterop.results+json"Example¶
curl -X GET http://localhost:8000/api/v1/data/3 -H "Accept: application/vnd.org.flowinterop.results+json" -u username:password
Response¶
[
[ "2017-05-23T13:35:37.119-04:00", 20394823948, 923842093, "ae54d3", "female", {"option_order": ["male","female"]} ],
[ "2017-05-23T13:35:47.822-04:00", 20394823950, 923842093, "ae54d7", "chocolate", null ]
]
Get FLOIP flow results for a specific submission¶
Provides a list of rows of submitted data for a specific submission in a form in FLOIP resource data format as specified here.
GET /api/v1/data/{pk}/{dataid}-H "Accept: application/vnd.org.flowinterop.results+json"
Example¶
curl -X GET http://localhost:8000/api/v1/data/210902/19158892 -H "Accept: application/vnd.org.flowinterop.results+json" -u username:password
Response¶
[
[ "2017-05-23T13:35:37.119-04:00", 20394823948, 923842093, "ae54d3", "female", {"option_order": ["male","female"]} ],
[ "2017-05-23T13:35:47.822-04:00", 20394823950, 923842093, "ae54d7", "chocolate", null ]
]
Paginate data of a specific form¶
Returns a list of JSON or XML submitted data for a specific form using page number and the number of items per page. Use the page parameter to specify page number and page_size parameter is used to set the custom page size.
page- Integer representing the page.page_size- Integer representing the number of records that should be returned in a single page.
There are a few important facts to note about retrieving paginated data:
The maximum number of items that can be requested in a page via the
page_sizequery param is 10,000Information regrading transversal of the paginated responses can be found in the Link header returned in the response. Note: Some relational links may not be present depending on the page accessed i.e the ``first`` relational page link won’t be present on the first page response
Page links omit start and limit so subsequent requests can traverse the
complete filtered result set. They preserve filters, sorting, selected fields,
and signed_urls.
JSON Example¶
curl -X GET https://api.ona.io/api/v1/data/328.json?page=1&page_size=4
Sample response with link header¶
curl -i "localhost:8000/api/v1/data/2?page=1&page_size=1"
Response Header:
...
Link: <http://localhost:8000/api/v1/data/2?page=2&page_size=1>; rel="next", <http://localhost:8000/api/v1/data/2?page=3&page_size=1>; rel="last"
JSON Response:
[
{
"_id":1,"_tags":[],"_uuid":"78afb566-8293-4f42-a83f-99d5ba0061e2",
"_notes":[]"_edited":false,"_status":"submitted_via_web",
"_version":"202010260841","_duration":"","_xform_id":2,
"plot_count":"1","_attachments":[],"_geolocation":[null,null],
"_media_count":0,"_total_media":0,"formhub/uuid":"281845ab2d214ff6ac08526c0484fe34",
"_submitted_by":null,"meta/instanceID":"uuid:78afb566-8293-4f42-a83f-99d5ba0061e2",
"_submission_time":"2020-10-26T08:49:06","_xform_id_string":"nested_repea",
"_bamboo_dataset_id":"","_media_all_received":true
}
]
Sort submitted data of a specific form using existing fields¶
Provides a sorted list of json submitted data for a specific form by specifing the order in which the query returns matching data. Use the sort parameter to filter the list of submissions.The sort parameter has field and value pairs.
{"field":value}
Query sorted by the age field ascending.
{"age":1}
Descending sort query using the age field:
{"age":-1}
Example of Ascending Sort¶
curl -X GET https://api.ona.io/api/v1/data/328.json?sort={"age":1}
Example of Descending sort¶
curl -X GET https://api.ona.io/api/v1/data/328.json?sort={"age":-1}
Get a single data submission for a given form¶
Get a single specific submission json data providing pk
and dataid as url path parameters, where:
pk- is the identifying number for a specific formdataid- is the unique id of the data, the value of_idor_uuid
GET /api/v1/data/{pk}/{dataid}
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845/4503
Response¶
{
"_id": 4503,
"_bamboo_dataset_id": "",
"_deleted_at": null,
"expense_type": "service",
"_xform_id_string": "exp",
"_geolocation": [
null,
null
],
"end": "2013-01-03T10:26:25.674+03",
"start": "2013-01-03T10:25:17.409+03",
"expense_date": "2011-12-23",
"_status": "submitted_via_web",
"today": "2013-01-03",
"_uuid": "2e599f6fe0de42d3a1417fb7d821c859",
"imei": "351746052013466",
"formhub/uuid": "46ea15e2b8134624a47e2c4b77eef0d4",
"kind": "monthly",
"_submission_time": "2013-01-03T02:27:19",
"required": "yes",
"_attachments": [],
"item": "Rent",
"amount": "35000.0",
"deviceid": "351746052013466",
"subscriberid": "639027...60317"
}
Fetch data on select columns for a given form¶
Returns a list of the selected columns from the submitted data. Use the fields parameter to specify the column data that should be returned.
fields- a comma separated list of columns on the given form.
GET /api/v1/data/{form_pk}.json?fields=["field1", "field2"]
Example¶
curl -X GET https://api.ona.io/api/v1/data/513322.json?fields=["_id", "_last_edited", "_last_edited_by"]
Response¶
[
{
"_id": 64999942,
"_last_edited": null,
"_last_edited_by": null
},
{
"_id": 64999819,
"_last_edited": null,
"_last_edited_by": null
},
{
"_id": 64999278,
"_last_edited": null,
"_last_edited_by": null
},
{
"_id": 64999082,
"_last_edited": null,
"_last_edited_by": null
},
{
"_id": 60549177,
"_last_edited": null,
"_last_edited_by": null
},
{
"_id": 60549136,
"_last_edited": null,
"_last_edited_by": null
}
]
Get the history of edits made to a submission¶
Get a single specific submission json data providing pk
and dataid as url path parameters, where:
pk- is the identifying number for a specific formdataid- is the unique id of the data, the value of_idor_uuid
GET /api/v1/data/{pk}/{dataid}/history
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845/4503/history
Response¶
[
{
"_id": 3,
"_bamboo_dataset_id": "",
"_deleted_at": null,
"expense_type": "service",
"_xform_id_string": "exp",
"_geolocation": [
null,
null
],
"end": "2013-01-03T10:26:25.674+03",
"start": "2013-01-03T10:25:17.409+03",
"expense_date": "2011-12-23",
"_status": "submitted_via_web",
"today": "2013-01-03",
"_uuid": "2e599f6fe0de42d3a1417fb7d821c859",
"imei": "351746052013466",
"formhub/uuid": "46ea15e2b8134624a47e2c4b77eef0d4",
"kind": "monthly",
"_submission_time": "2013-01-03T02:27:19",
"_attachments": [],
"_notes": [],
"item": "Rent",
"amount": "35000.0",
"deviceid": "351746052013466",
"subscriberid": "639027...60317"
},
....
]
Query submitted data of a specific form¶
Use the query or data parameter to pass in a JSON key/value query.
ISO 8601 date formats are supported. Below are examples of common formats:
YYYY-MM-DD(e.g., 2024-09-18)YYYY-MM-DDThh:mm:ss(e.g., 2024-09-18T14:30:00)YYYY-MM-DDThh:mm:ssZ(e.g., 2024-09-18T14:30:00Z)YYYY-MM-DDThh:mm:ss.ssssssZ(e.g., 2024-09-18T14:30:00.169615Z)YYYY-MM-DDThh:mm:ss±hh:mm(e.g., 2024-09-17T13:39:40+00:00)YYYY-MM-DDThh:mm:ss.ssssss±hh:mm(e.g., 2024-09-17T13:39:40.169615+00:00)
When quering a date time field whose value is in ISO format such as 2020-12-18T09:36:19.767455+00:00, it is important to ensure the + (plus) is encoded to %2b.
+ without encoding is parsed as whitespace. So 2020-12-18T09:36:19.767455+00:00 should be converted to 2020-12-18T09:36:19.767455%2b00:00.
Example I¶
Query submissions where name is tom
curl -X GET https://api.ona.io/api/v1/data/22845?query={"name":"tom"}
Example II¶
Query submissions where age is greater than 21
curl -X GET https://api.ona.io/api/v1/data/22845?query={"age":{"$gt":"21"}}
Example III¶
Query submissions where age is less than or equal to 21
curl -X GET https://api.ona.io/api/v1/data/22845?query={"age":{"$lte":"21"}}
Example IV¶
Query submissions with case insensitive and partial search
curl -X GET https://api.ona.io/api/v1/data/22845?query={"name":{"$i":"hosee"}}
Example V¶
Query submissions collected before specific date
curl -X GET https://api.ona.io/api/v1/data/22845.json?query={"_submission_time":{"$lte": "2020-08-31"}}
Example VI¶
Query submissions collected within specific dates
curl -X GET https://api.ona.io/api/v1/data/22845.json?query={"_submission_time":{"$gte": "2020-01-01", "$lte": "2020-08-31"}}
Example VII¶
Query submissions where age is 21 or name is hosee
curl -X GET https://api.ona.io/api/v1/data/22845?query={"$or": [{"age": "21", "name": "hosee"}]}
Example VIII¶
Query submissions with APPROVED submission review status
curl -X GET https://api.ona.io/api/v1/data/22845?query={"_review_status" : "1"}
Example IX¶
Query submissions with REJECTED submission review status
curl -X GET https://api.ona.io/api/v1/data/22845?query={"_review_status" : "2"}
Example X¶
Query submissions with PENDING submission review status
curl -X GET https://api.ona.io/api/v1/data/22845?query={"_review_status" : "3"}
Example XI¶
Query submissions with pending submission review status or NULL
curl -X GET https://api.ona.io/api/v1/data/22845?query={"$or": [{"_review_status": "3"}, {"_review_status": null}]}
Example XII¶
Query submissions with NULL submission review status
curl -X GET https://api.ona.io/api/v1/data/22845?query={"_review_status": null}
Example XIII¶
Query submissions collected within specific dates or edited within specific dates.
curl -X GET https://api.ona.io/api/v1/data/22845?query={"$or": [{"_submission_time":{"$gte": "2020-01-01", "$lte": "2020-08-31"}}, {"_last_edited":{"$gte": "2020-01-01", "$lte": "2020-08-31"}}]}
All Filters Options
Filter Description¶
$gt Greater than $gte Greater than or Equal to $lt Less than $lte Less or Equal to $i Case insensitive or partial search $or Or ==================================================
Query submitted data of a specific form using date_created¶
Filter submissions using the date_created field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?date_created__year=2017
All Filters Options
Filter |
Description |
|---|---|
date_created__year |
Exact year e.g. 2017 |
date_created__year__lt |
Year Less than |
date_created__year__lte |
Year Less than or Equal to |
date_created__year__gt |
Year Greater than |
date_created__year__gte |
Year Greater than or Equal to |
date_created__month |
Exact month e.g. 11 |
date_created__month__lt |
Month Less than |
date_created__month__lte |
Month Less than or Equal to |
date_created__month__gt |
Month Greater than |
date_created__month__gte |
Month Greater than or Equal to |
date_created__day |
Exact day e.g. 13 |
date_created__day__lt |
Day Less than |
date_created__day__lte |
Day Less than or Equal to |
date_created__day__gt |
Day Greater than |
date_created__day__gte |
Day Greater than or Equal to |
Filter options can be chained to narrow results even further.
Query submitted data of a specific form using date_modified¶
Filter submissions using the date_modified field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?date_modified__month=11
All Filters Options
Filter |
Description |
|---|---|
date_modified__year |
Exact year e.g. 2017 |
date_modified__year__lt |
Year Less than |
date_modified__year__lte |
Year Less than or Equal to |
date_modified__year__gt |
Year Greater than |
date_modified__year__gte |
Year Greater than or Equal to |
date_modified__month |
Exact month e.g. 11 |
date_modified__month__lt |
Month Less than |
date_modified__month__lte |
Month Less than or Equal to |
date_modified__month__gt |
Month Greater than |
date_modified__month__gte |
Month Greater than or Equal to |
date_modified__day |
Exact day e.g. 13 |
date_modified__day__lt |
Day Less than |
date_modified__day__lte |
Day Less than or Equal to |
date_modified__day__gt |
Day Greater than |
date_modified__day__gte |
Day Greater than or Equal to |
Filter options can be chained to narrow results even further.
Query submitted data of a specific form using last_edited¶
Filter submissions using the last_edited field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?last_edited__year=2017&last_edited__month=2
All Filters Options
Filter |
Description |
|---|---|
last_edited__year |
Exact year e.g. 2017 |
last_edited__year__lt |
Year Less than |
last_edited__year__lte |
Year Less than or Equal to |
last_edited__year__gt |
Year Greater than |
last_edited__year__gte |
Year Greater than or Equal to |
last_edited__month |
Exact month e.g. 11 |
last_edited__month__lt |
Month Less than |
last_edited__month__lte |
Month Less than or Equal to |
last_edited__month__gt |
Month Greater than |
last_edited__month__gte |
Month Greater than or Equal to |
last_edited__day |
Exact day e.g. 13 |
last_edited__day__lt |
Day Less than |
last_edited__day__lte |
Day Less than or Equal to |
last_edited__day__gt |
Day Greater than |
last_edited__day__gte |
Day Greater than or Equal to |
Filter options can be chained to narrow results even further.
Query submitted data of a specific form using version¶
Filter submissions using the version field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?version=2324243
Query submitted data of a specific form using status¶
Filter submissions using the status field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?status=submitted_via_web
Query submitted data of a specific form using uuid¶
Filter submissions using the uuid field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?uuid=9c6f3468-cfda-46e8-84c1-75458e72805d
Query submitted data of a specific form using user¶
Filter submissions using the user field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?user__id=260
All Filters Options
Filter |
Description |
|---|---|
user__id |
user’s id |
user__username |
user’s username |
Query submitted data of a specific form using submitted_by¶
Filter submissions using the submitted_by field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?submitted_by__username=hunter2
All Filters Options
Filter |
Description |
|---|---|
submitted_by__id |
submitted_by user’s id |
submitted_by__username |
submitted_by user’s username |
Query submitted data of a specific form using survey_type¶
Filter submissions using the survey_type field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?survey_type__slug=fortytwo
Query submitted data of a specific form using media_all_received¶
Filter submissions using the media_all_received field
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?media_all_received=true
Query submitted data of a specific form based on encryption status¶
Filter submissions using the is_encrypted field.
Use true or 1 to get encrypted submissions only, false or 0 to get unencrypted submissions only.
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?is_encrypted=true
Filter submissions using the decryption_status field.
Use pending to get submissions that are waiting to be decrypted, in_progress to get submissions that are being decrypted, success to get submissions that were successfully decrypted, failed to get submissions that failed decryption.
Example¶
curl -X GET https://api.ona.io/api/v1/data/22845?decryption_status=failed
For submissions that have a status of failed, there exists a _decryption_error field that contains an error name and message. The following are the possible errors:
KMS_KEY_DISABLED: Encryption key is disabled.KMS_KEY_NOT_FOUND: Encryption key used for encryption not found.INVALID_SUBMISSION: Data is corrupted.
A submission with a status of pending can be decrypted again. Another attempt is made when the submission is saved with all its media files received, such as when its last media file arrives. If an earlier attempt to decrypt it did not succeed, its _decryption_error field contains the reason. The following are the possible errors:
MAX_RETRIES_EXCEEDED: System was unable to decrypt the submission after multiple attempts.NOT_ALL_MEDIA_RECEIVED: Not all media files have been received.
Tag a submission data point¶
A POST payload of parameter tags with a comma separated list of tags.
Examples¶
animal fruit denim- space delimited, no commasanimal, fruit denim- comma delimited
POST /api/v1/data/{pk}/{dataid}/labels
Payload
{"tags": "tag1, tag2"}
Delete a specific tag from a submission¶
DELETE /api/v1/data/{pk}/{dataid}/labels/tag_name
Request¶
curl -X DELETE https://api.ona.io/api/v1/data/28058/20/labels/tag1
or to delete the tag “hello world”
curl -X DELETE https://api.ona.io/api/v1/data/28058/20/labels/hello%20world
Response¶
HTTP 200 OK
Get list of public data endpoints¶
GET /api/v1/data/public
Example¶
curl -X GET https://api.ona.io/api/v1/data/public
Response¶
[
{
"id": 4240,
"id_string": "dhis2form",
"title": "dhis2form",
"description": "dhis2form",
"url": "https://api.ona.io/api/v1/data/4240"
},
...
]
Get enketo edit link for a submission instance¶
GET /api/v1/data/{pk}/{dataid}/enketo
Example¶
curl -X GET https://api.ona.io/api/v1/data/28058/20/enketo?return_url=url
Response¶
{"url": "https://hmh2a.enketo.formhub.org"}
Delete a specific submission instance¶
Delete a specific submission in a form
DELETE /api/v1/data/{pk}/{dataid}
Example¶
curl -X DELETE https://api.ona.io/api/v1/data/28058/20
Response¶
HTTP 204 No Content
Delete a subset of submissions¶
Delete multiple submissions in a form
DELETE /api/v1/data/{pk}
A POST payload of parameter instance_ids with a comma separated list of submission ids.
Payload
instance_ids = '101425,108428,1974624'
Example¶
'curl -X DELETE https://api.ona.io/api/v1/data/28058' -d 'instance_ids=101425,108428,1974624'
Response¶
{"status_code": 200, "message": "3 records were deleted"}
Delete all submissions in a form¶
Delete all submissions in a form
DELETE /api/v1/data/{pk}
A POST payload of parameter delete_all with the value ‘True’. The value is ‘False’ by default.
Payload
delete_all = 'True'
Example¶
'curl -X DELETE https://api.ona.io/api/v1/data/28058' -d 'delete_all="True"'
Response¶
{"status_code": 200, "message": "3 records were deleted"}
Permanent Deletion of Submissions¶
Permanently Delete a specific submission instance
DELETE /api/v1/data/{pk}/{dataid}
A POST payload of parameter permanent_delete with the value ‘True’. The value is ‘False’ by default.
Note: This functionality is only enabled when the ENABLE_SUBMISSION_PERMANENT_DELETE setting is set to True within the application
Payload
permanent_delete = 'True'
Example¶
`curl -X DELETE https://api.ona.io/api/v1/data/28058' -d 'permanent_delete=True'`
Response¶
- ::
HTTP 204 No Content
Permanently Delete a subset of submissions
DELETE /api/v1/data/{pk}
Example¶
`curl -X DELETE https://api.ona.io/api/v1/data/28058' -d 'permanent_delete=True' -d 'instance_ids=101425,108428,1974624'`
Response¶
{
"status_code": "200",
"message": "3 records were deleted"
}
GEOJSON¶
Get a valid geojson value from the submissions
Options
geo_field- valid field that can be converted to a geojson (Point, LineString, Polygon).fields- additional comma separated values that are to be added to the properties sectionsimple_style- boolean to enable or disable Mapbox Geojson simplestyle spectitle- adds a title field and value to geojson properties section
List all the geojson values for a submission
GET /api/v1/data/{form_pk}/{dataid}.geojson
Example¶
curl -X GET https://api.ona.io/api/v1/data/28058/20.geojson
Response¶
HTTP 200 OK
Response¶
{
"type": "Feature",
"geometry": {
"type": "GeometryCollection",
"geometries": [{
"type": "Point",
"coordinates": [36.787219, -1.294197]
}]
},
"properties": {
"id": 6448,
"xform": 65
}
}
List all the geojson values for a given form
GET /api/v1/data/{form_pk}.geojson
Example¶
curl -X GET https://api.ona.io/api/v1/data/28058.geojson
Response¶
HTTP 200 OK
Response¶
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "GeometryCollection",
"geometries": [{
"type": "Point",
"coordinates": [36.787219, -1.294197]
}]
},
"properties": {
"id": 6448,
"xform": 65
}
},
{
"type": "Feature",
"geometry": {
"type": "GeometryCollection",
"geometries": [{
"type": "Point",
"coordinates": [36.7872606, -1.2942131]
}]
},
"properties": {
"id": 6447,
"xform": 65
}
}]
}
List the geojson data, for a polygon field, for a given submission
GET /api/v1/data/{pk}/{dataid}.geojson?geo_field={name_of_field_on_form}
Example¶
curl -X GET https://api.ona.io/api/v1/data/513322/60549136.geojson?geo_field=my_geoshape
Response¶
HTTP 200 OK
Response¶
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
36.747679,
-1.300717
],
[
36.752386,
-1.305222
],
[
36.751879,
-1.300642
],
[
36.747679,
-1.300717
]
]
]
},
"properties": {
"id": 60549136,
"xform": 513322
}
}
List the geojson data, for a geotrace field, for a given submission. Add fields to the properties attribute
GET /api/v1/data/{pk}/{dataid}.geojson?geo_field={name_of_field_on_form}
Example¶
curl -X GET https://api.ona.io/api/v1/data/513322/60549136.geojson?geo_field=my_geotrace
Response¶
HTTP 200 OK
Response¶
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[
36.745623,
-1.302819
],
[
36.750326,
-1.299129
]
]
},
"properties": {
"id": 60549136,
"xform": 513322
}
}
Fetch geojson values for a submission with populated properties attribute
GET /api/v1/data/{pk}/{dataid}.geojson?fields={_id,_last_edited,_last_edited_by}
Example¶
curl -X GET https://api.ona.io/api/v1/data/513322/60549136.geojson?fields=_id,_last_edited,_last_edited_by
Response¶
HTTP 200 OK
Response¶
{
"type": "Feature",
"geometry": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"coordinates": [
36.744421,
-1.29943
]
}
]
},
"properties": {
"id": 60549136,
"xform": 513322,
"_id": 60549136,
"_last_edited": null,
"_last_edited_by": null
}
}
List all the geojson values for a given form with simplestyle-spec enabled and title prop set
GET /api/v1/data/{form_pk}.geojson?geo_field={name_of_field_on_form}&simple_style=true&title={name_of_title_field_on_form}
Example¶
curl -X GET https://api.ona.io/api/v1/data/28058.geojson?geo_field=my_geoshape&style_spec=true
Response¶
HTTP 200 OK
Response¶
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [36.787219, -1.294197]
},
"properties": {
"id": 6448,
"xform": 65,
"title": "my_field"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [36.7872606, -1.2942131]
},
"properties": {
"id": 6447,
"xform": 65,
"title": "my_field"
}
}]
}
Paginate geojson data for a given form
Returns a list of geojson features for a specific form using page number and the number of items per page.
Use the page parameter to specify page number and page_size parameter to set the custom page size.
page- Integer representing the page.page_size- Integer representing the number of features that should be returned in a single page.
GET /api/v1/data/{form_pk}.geojson?page={page_number}&page_size={page_size_number}
Example¶
curl -X GET https://api.ona.io/api/v1/data/28058.geojson?page=1&page_size=2
Response¶
HTTP 200 OK
Response¶
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "GeometryCollection",
"geometries": [{
"type": "Point",
"coordinates": [36.787219, -1.294197]
}]
},
"properties": {
"id": 6448,
"xform": 65
}
},
{
"type": "Feature",
"geometry": {
"type": "GeometryCollection",
"geometries": [{
"type": "Point",
"coordinates": [36.7872606, -1.2942131]
}]
},
"properties": {
"id": 6447,
"xform": 65
}
}]
}
OSM¶
The .osm file format concatenates all the files for a form or individual submission. When the .json endpoint is accessed, the individual osm files are listed on the _attachments key.
OSM endpoint for all osm files uploaded to a form concatenated.¶
GET /api/v1/data/{pk}.osm
Example¶
curl -X GET https://api.ona.io/api/v1/data/28058.osm
OSM endpoint with all osm files for a specific submission concatenated.¶
GET /api/v1/data/{pk}/{data_id}.osm
Example¶
curl -X GET https://api.ona.io/api/v1/data/28058/20.osm