Projects¶

List, Retrieve, Update, Create Project and Project Forms

Where:

pk - is the project id
formid - is the form id
owner - is the username for the user or organization of the project

Register a new Project¶

POST /api/v1/projects

Example¶

{
    "url": "https://api.ona.io/api/v1/projects/1",
    "owner": "https://api.ona.io/api/v1/users/ona",
    "name": "project 1",
    "date_created": "2013-07-24T13:37:39Z",
    "date_modified": "2013-07-24T13:37:39Z"
}

List of Projects¶

GET /api/v1/projects

Example¶

curl -X GET https://api.ona.io/api/v1/projects

Response¶

[
    {
        "url": "https://api.ona.io/api/v1/projects/1",
        "owner": "https://api.ona.io/api/v1/users/ona",
        "name": "project 1",
        "date_created": "2013-07-24T13:37:39Z",
        "date_modified": "2013-07-24T13:37:39Z"
    },
    {
        "url": "https://api.ona.io/api/v1/projects/4",
        "owner": "https://api.ona.io/api/v1/users/ona",
        "name": "project 2",
        "date_created": "2013-07-24T13:59:10Z",
        "date_modified": "2013-07-24T13:59:10Z"
    }, ...
]

List of Projects filter by owner/organization¶

GET /api/v1/projects?owner=owner_username

You can use this to get both members and collaborators of an organization. In the case of organizations, this gives you both members and collaborators under “users”. Under “teams” key we list only the members of the organization.

Example¶

curl -X GET https://api.ona.io/api/v1/projects?owner=ona

Retrieve Project Information¶

GET /api/v1/projects/{pk}

Example¶

curl -X GET https://api.ona.io/api/v1/projects/1

Response¶

{
    "url": "https://api.ona.io/api/v1/projects/1",
    "owner": "https://api.ona.io/api/v1/users/ona",
    "name": "project 1",
    "date_created": "2013-07-24T13:37:39Z",
    "date_modified": "2013-07-24T13:37:39Z"
}

Update Project Information¶

PUT /api/v1/projects/{pk} or PATCH /api/v1/projects/{pk}

Example¶

curl -X PATCH -d 'metadata={"description": "Lorem ipsum","location": "Nakuru, Kenya","category": "water"}' https://api.ona.io/api/v1/projects/1

Response¶

{
    "url": "https://api.ona.io/api/v1/projects/1",
    "owner": "https://api.ona.io/api/v1/users/ona",
    "name": "project 1",
    "metadata": {
        "description": "Lorem ipsum",
        "location": "Nakuru, Kenya",
        "category": "water"
    },
    "date_created": "2013-07-24T13:37:39Z",
    "date_modified": "2013-07-24T13:37:39Z"
}

Available Permission Roles¶

The following are the available roles in onadata:

member Default role for user with no permission
readonly-no-download Role for a user able to view data but not export it
readonly Role for a user able to view and download data
dataentry-only Role for a user able to submit data only
dataentry-minor Role for a user able to submit and view only data he/she submitted
dataentry Role for a user able to submit and view all data
editor-minor Role for a user able to view and edit data he/she submitted
editor Role for a user able to view and edit all data
manager Role for a user with administrative privileges
owner Role for an owner of a data-set, organization, or project.

Share a project with a specific user¶

You can share a project with a specific user by PUT a payload with

username of the user you want to share the form with and
role you want the user to have on the project.Available roles are readonly, dataentry, editor, manager.

PUT /api/v1/projects/{pk}/share

Example¶

curl -X PUT -d username=alice -d role=readonly https://api.ona.io/api/v1/projects/1/share

Response¶

HTTP 204 NO CONTENT

Send an email to users on project share¶

An email is only sent when the email_msg request variable is present.

POST /api/v1/projects/{pk}/share

Example¶

curl -X POST -d username=alice -d role=readonly -d email_msg="I have shared the project with you" https://api.ona.io/api/v1/projects/1/share

Response¶

::: HTTP 204 NO CONTENT

Remove a user from a project¶

You can remove a specific user from a project using POST with payload:

username of the user you want to remove
role the user has on the project
remove set remove to True

Example¶

curl -X POST -d "username=alice" -d "role=readonly" -d "remove=True" http://api.ona.io/api/v1/projects/1/share

Response¶

HTTP 204 NO CONTENT

Assign a form to a project¶

To [re]assign an existing form to a project you need to POST a payload of formid=FORMID to the endpoint below.

POST /api/v1/projects/{pk}/forms

Example¶

curl -X POST -d '{"formid": 28058}' https://api.ona.io/api/v1/projects/1/forms -H "Content-Type: application/json"

Response¶

{
    "url": "https://api.ona.io/api/v1/forms/28058",
    "formid": 28058,
    "uuid": "853196d7d0a74bca9ecfadbf7e2f5c1f",
    "id_string": "Birds",
    "sms_id_string": "Birds",
    "title": "Birds",
    "allows_sms": false,
    "bamboo_dataset": "",
    "description": "",
    "downloadable": true,
    "encrypted": false,
    "owner": "ona",
    "public": false,
    "public_data": false,
    "date_created": "2013-07-25T14:14:22.892Z",
    "date_modified": "2013-07-25T14:14:22.892Z"
}

Upload XLSForm to a project¶

POST /api/v1/projects/{pk}/forms

Example¶

curl -X POST -F xls_file=@/path/to/form.xls https://api.ona.io/api/v1/projects/1/forms

Response¶

{
    "url": "https://api.ona.io/api/v1/forms/28058",
    "formid": 28058,
    "uuid": "853196d7d0a74bca9ecfadbf7e2f5c1f",
    "id_string": "Birds",
    "sms_id_string": "Birds",
    "title": "Birds",
    "allows_sms": false,
    "bamboo_dataset": "",
    "description": "",
    "downloadable": true,
    "encrypted": false,
    "owner": "ona",
    "public": false,
    "public_data": false,
    "date_created": "2013-07-25T14:14:22.892Z",
    "date_modified": "2013-07-25T14:14:22.892Z"
}

Get forms for a project¶

GET /api/v1/projects/{pk}/forms

Example¶

curl -X GET https://api.ona.io/api/v1/projects/1/forms

Response¶

[
    {
        "url": "https://api.ona.io/api/v1/forms/28058",
        "formid": 28058,
        "uuid": "853196d7d0a74bca9ecfadbf7e2f5c1f",
        "id_string": "Birds",
        "sms_id_string": "Birds",
        "title": "Birds",
        "allows_sms": false,
        "bamboo_dataset": "",
        "description": "",
        "downloadable": true,
        "encrypted": false,
        "owner": "ona",
        "public": false,
        "public_data": false,
        "date_created": "2013-07-25T14:14:22.892Z",
        "date_modified": "2013-07-25T14:14:22.892Z",
        "tags": [],
        "users": [
            {
                "role": "owner",
                "user": "alice",
                ...
            },
            ...
        ]
    },
    ...
]

Get list of projects with specific tag(s)¶

Use the tags query parameter to filter the list of projects, tags should be a comma separated list of tags.

GET /api/v1/projects?tags=tag1,tag2

List projects tagged smart or brand new or both. Request ^^^^^^^^

curl -X GET https://api.ona.io/api/v1/projects?tag=smart,brand+new

Response¶

 HTTP 200 OK

[
    {
        "url": "https://api.ona.io/api/v1/projects/1",
        "owner": "https://api.ona.io/api/v1/users/ona",
        "name": "project 1",
        "date_created": "2013-07-24T13:37:39Z",
        "date_modified": "2013-07-24T13:37:39Z"
    },
    ...
]

Get list of Tags for a specific Project¶

GET /api/v1/project/{pk}/labels

Request¶

curl -X GET https://api.ona.io/api/v1/projects/28058/labels

Response¶

["old", "smart", "clean house"]

Tag a Project¶

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/projects/{pk}/labels

Payload

{"tags": "tag1, tag2"}

Remove a tag from a Project¶

DELETE /api/v1/projects/{pk}/labels/tag_name

Request¶

curl -X DELETE https://api.ona.io/api/v1/projects/28058/labels/tag1

or to delete the tag “hello world”

curl -X DELETE https://api.ona.io/api/v1/projects/28058/labels/hello%20world

Response¶

HTTP 200 OK

Add a star to a project¶

POST /api/v1/projects/{pk}/star

Remove a star to a project¶

DELETE /api/v1/projects/{pk}/star

Get user profiles that have starred a project¶

GET /api/v1/projects/{pk}/star