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

Get a paginated list of Projects¶

Returns a list of projects 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. The maximum number of items that can be requested in a page via the page_size query param is 10,000

GET /api/v1/projects?page=1page_size=2

Example¶

curl -X GET https://api.ona.io/api/v1/projects?page=1&page_size=2

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 user(s)¶

You can share a project with a user or multiple users by PUT a payload with

username of the user you want to share the form with or a list of users separated by a comma and
role you want the user(s) to have on the project.Available roles are readonly, dataentry, editor, manager.

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

Response¶

HTTP 204 NO CONTENT

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 PUT 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 PUT -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

Projects¶

Register a new Project¶

Example¶

List of Projects¶

Example¶

Response¶

Get a paginated list of Projects¶

Example¶

Response¶

List of Projects filter by owner/organization¶

Example¶

Retrieve Project Information¶

Example¶

Response¶

Update Project Information¶

Example¶

Response¶

Available Permission Roles¶

Share a project with user(s)¶

Example 1: Sharing with a specific user¶

Response¶

Example 2: Sharing with mutliple users¶

Response¶

Send an email to users on project share¶

Example¶

Response¶

Remove a user from a project¶

Example¶

Response¶

Assign a form to a project¶

Example¶

Response¶

Upload XLSForm to a project¶

Example¶

Response¶

Get forms for a project¶

Example¶

Response¶

Get list of projects with specific tag(s)¶

Response¶

Get list of Tags for a specific Project¶

Request¶

Response¶

Tag a Project¶

Examples¶

Remove a tag from a Project¶

Request¶

Response¶

Add a star to a project¶

Remove a star to a project¶

Get user profiles that have starred a project¶