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

  • invitation_pk - is the project invitation id

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

Example 1: Sharing with a specific user

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

Response

HTTP 204 NO CONTENT

Example 2: Sharing with mutliple users

curl -X PUT -d username=alice,jake -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 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

Get Project Invitation List

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

Example

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

Response

[
    {
        "id": 1,
        "email":"janedoe@example.com",
        "role":"readonly",
        "status": 1

    },
    {
        "id": 2,
        "email":"johndoe@example.com",
        "role":"editor",
        "status": 2,
    }
]

Get a list of project invitations with a specific status

The available choices are:

  • 1 - Pending. Invitations which have not been accepted by recipients.

  • 2 - Accepted. Invitations which have been accepted by recipients.

  • 3 - Revoked. Invitations which were cancelled.

GET /api/v1/projects/{pk}/invitations?status=2

Example

curl -X GET https://api.ona.io/api/v1/projects/1/invitations?status=2

Response

[

    {
        "id": 2,
        "email":"johndoe@example.com",
        "role":"editor",
        "status": 2,
    }
]

Create a new project invitation

Invite an unregistered user to a project. An email will be sent to the user which has a link for them to create an account.

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

Example

curl -X POST -d "email=janedoe@example.com" -d "role=readonly" https://api.ona.io/api/v1/projects/1/invitations

email: The email address of the unregistered user.

  • Should be a valid email. If the PROJECT_INVITATION_EMAIL_DOMAIN_WHITELIST setting has been enabled, then the email domain has to be in the whitelist for it to be also valid

Example

PROJECT_INVITATION_EMAIL_DOMAIN_WHITELIST=["foo.com", "bar.com"]
  • Email should not be that of a registered user

role: The user’s role for the project.

  • Must be a valid role

Response

{
    "id": 1,
    "email": "janedoe@example.com",
    "role": "readonly",
    "status": 1,
}

The link embedded in the email will be of the format http://{url} where:

  • url - is the URL the recipient will be redirected to on clicking the link. The default is {domain}/api/v1/profiles where domain is domain where the API is hosted.

Normally, you would want the email recipient to be redirected to a web app. This can be achieved by adding the setting PROJECT_INVITATION_URL

Example

PROJECT_INVITATION_URL = {'*': 'https://example.com/register'}

Update a project invitation

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

Example

curl -X PUT -d "email=janedoe@example.com" -d "role=editor" -d "invitation_id=1"  https://api.ona.io/api/v1/projects/1/invitations/1

Response

{
    "id": 1,
    "email": "janedoe@example.com",
    "role": "editor",
    "status": 1,
}

Resend a project invitation

Resend a project invitation email

POST /api/v1/projects/{pk}/resend-invitation

Example

curl -X POST -d "invitation_id=6" https://api.ona.io/api/v1/projects/1/resend-invitation

invitation_id: The primary key of the ProjectInvitation to resend.

  • Must be a ProjectInvitation whose status is Pending

Response

{
    "message": "Success"
}

Revoke a project invitation

Cancel a project invitation. A revoked invitation means that project will not be shared with the new user even if they accept the invitation.

POST /api/v1/projects/{pk}/revoke-invitation

Example

curl -X POST -d "invitation_id=6" https://api.ona.io/api/v1/projects/1/revoke-invitation

invitation_id: The primary key of the ProjectInvitation to resend.

  • Must be a ProjectInvitation whose status is Pending

Response

{
    "message": "Success"
}

Accept a project invitation

Since a project invitation is sent to an unregistered user, acceptance of the invitation is handled when creating a new user.

All pending invitations whose email match the new user’s email will be accepted and projects shared with the user