Data

This endpoint provides access to submitted data in JSON format. Where:

  • pk - the form unique identifier

  • dataid - submission data unique identifier

  • owner - 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&amp;suffix=small</small_download_url>
                <medium_download_url>/api/v1/files/50?filename=bob/attachments/574_transportation_2011_07_25/1335783522563.jpg&amp;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 timestamp

  • Row ID - Submission id

  • Contact ID - Name of the person who made the submission or null if unavailable

  • Question ID - The question field name

  • Response - The question response

  • Response 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:

  1. The maximum number of items that can be requested in a page via the page_size query param is 10,000

  2. Information 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

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 form

  • dataid - is the unique id of the data, the value of _id or _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 form

  • dataid - is the unique id of the data, the value of _id or _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 using Tags

Provides a list of json submitted data for a specific data/form matching specific tags. Use the tags query parameter to filter the list of forms, tags should be a comma separated list of tags.

You can use the not_tagged query parameter to exclude data/forms that is not tagged with the specific comma separated list of tags.

GET /api/v1/data?tags=tag1,tag2
GET /api/v1/data/{pk}?tags=tag1,tag2
GET /api/v1/data?not_tagged=tag1,tag2
GET /api/v1/data/{pk}?not_tagged=tag2

Example

curl -X GET https://api.ona.io/api/v1/data/22845?tags=monthly

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 commas

  • animal, 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"
    },
    ...
]

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 section

  • simple_style - boolean to enable or disable Mapbox Geojson simplestyle spec

  • title - 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