NAV
cURL R

Introduction

The ActivityInfo API allows you to query and update public and private ActivityInfo databases. You can also push updates to ActivityInfo databases for which you have write permissions.

ActivityInfo offers a JSON-based API that mostly follows RESTful principles, so you can either use your favorite REST client library to send and receive JSON, or you can use a client library for R for convenience.

Authentication

The ActivityInfo API supports Basic Authentication, a standard method of authentication supported by most HTTP Clients.

When authenticating to activityinfo.org, clients should submit an authorized user’s email and password as the username and password.

Resource IDs

In order to allow ActivityInfo clients to work while disconnected from the internet, most identifiers are generated by the client using a combination of a timestamp, a local counter, and random numbers.

This means when submitting a request to add a new database, folder, form, etc, you will need to generate the id of the new resource.

The Collision-resistant ids (CUID) project has libraries in a number of languages for generating IDs that will be accepted by ActivityInfo.

Databases

Add a database

Add a new database to ActivityInfo.

Only users who have a billing account with ActivityInfo are permitted to add new databases.

HTTP Request

POST https://www.activityinfo.org/resources/databases

Request Body application/json

object
id string The id of the new database. required
label string Human readable name of the database. required
templateId string The id of the template to use in creating the new database. The the two templates currently supported are "reporting" (Multi-partner reporting) and "casemanagement." If ommitted, a blank database with three simple roles will be added. required
description string An optional, longer description for the database. optional

Responses application/json

Status CodeError CodeDescription
200Database was successfully created.
401AUTHENTICATION_REQUIREDThe request must be authenticated, using basic authentication.
400BILLING_ACCOUNT_NOT_ACTIVEThe authenticated user's billing account is not active.
400NO_BILLING_ACCOUNTThe authenticated user has no billing account, and so cannot add a database.
409DATABASE_EXISTSA database with this id already exists.

List databases

Lists all the databases that the requesting user owns, or that have been shared with the requesting user.

HTTP Request

GET https://www.activityinfo.org/resources/databases

curl -u me@example.com:mypassword \
  https://www.activityinfo.org/resources/databases
The above command returns JSON structured like this:
[
  {
    "databaseId": "ck8oykh8m5",
    "label": "2018 IRQ Internally Displaced Persons (IDP)",
    "description": "",
    "ownerId": "432201",
    "billingAccountId": 3.4298234040238E13,
    "suspended": false
  },
  {
    "databaseId": "cbi8pxnkhyvhmcs2",
    "label": "COVID-19 Response",
    "description": "",
    "ownerId": "432201",
    "billingAccountId": 3.4298234040238E13,
    "suspended": false
  }
]

Successful Response application/json

array[object]
databaseId string The globally-unique id of this database. required
label string The human-readable name of this database. required
description string A longer, optional description for this database. required
ownerId string The id of the user who owns this database. required
billingAccountId integer The id of the billing account to which this database belongs required
suspended boolean True if this database belongs to a billing account that has been suspended. required

Get a database's tree

The database tree includes the key elements of a database, including:

The tree includes only resources visible to the requesting user, along with the requesting user's permission grants for the database.

HTTP Request

GET https://www.activityinfo.org/resources/databases/{databaseId}

curl -u me@example.com:mypassword \
  https://www.activityinfo.org/resources/databases/ck8oykh8m5

Successful Response application/json

object
databaseId string This database's id required
userId string The id of the requesting user. The contents of the tree depends on the permissions of the requesting user. required
version string The monotonically-increasing version of the database tree. The version number is incremented whenever a change is made that affects the database tree. required
label string This database's human-readable label. required
description string required
owner boolean True if the requesting user is the database's owner required
ownerName string required
ownerEmail string required
suspended boolean True if this database is suspended for billing reasons required
storage string Opaque string that provides information about where and how this database is stored. Used to support data migration. required
role object The requesting user's assigned role in this database. required
roles array[object] The roles that have been defined for this database. required
resources array[object] The set of resources (folders, forms, and subforms) that belong to this database. required
locks array[object] The record locks that have been defined on this database. required
grants array[object] The permission grants that have been made to the requesting user for this database. required
billingAccountId integer required

Update a database's tree

Add, update or delete a resource, lock, or role in the database tree.

HTTP Request

POST https://www.activityinfo.org/resources/databases/{databaseId}

Request Body application/json

object
resourceUpdates array[object] List of resources to add or update. required
resourceDeletions array[string] List of resource ids to delete from the database. required
lockUpdates array[object] List of locks to add or update required
lockDeletions array[string] List of lock ids to delete required
roleUpdates array[object] List of roles to add or update. required
roleDeletions array[string] List of role ids to delete. required

Responses application/json

Status CodeError CodeDescription
200The database was successfully updated
401AUTHENTICATION_REQUIREDThe request must be authenticated, using basic authentication.
400INVALID_UPDATEOne of the items to be deleted could not be found
403PERMISSION_DENIED
404DATABASE_NOT_FOUND

Database Users

Get list of database users

HTTP Request

GET https://www.activityinfo.org/resources/databases/{databaseId}/users

curl -u me@example.com:mypassword \
  https://www.activityinfo.org/resources/databases/ck8oykh8m5/users
The above command returns JSON structured like this:
[
  {
    "databaseId": "ck8oykh8m5",
    "userId": "401",
    "name": "Bob",
    "email": "bob@example.com",
    "role": {
      "id": "admin",
      "parameters": null,
      "resources": [
        "ck8oykh8m5"
      ]
    },
    "version": 34,
    "inviteDate": "",
    "deliveryStatus": "OK",
    "inviteAccepted": true
  },
  {
    "databaseId": "ck8oykh8m5",
    "userId": "499",
    "name": "Amin",
    "email": "amin@abc.org",
    "role": {
      "id": "rp",
      "parameters": {
        "partner": "ck8oyloog8:cokq8v0khyvhmkl3"
      },
      "resources": [
        "csfkoqakhyvhmkl4",
        "cdhmz9khyvhmkm5"
      ]
    },
    "version": 34,
    "inviteDate": "",
    "deliveryStatus": "OK",
    "inviteAccepted": true
  }
]

Successful Response application/json

array[object]
databaseId string required
userId string required
name string The user's name, provided either when invited or by the user themselves after activating their account. required
email string This user's email address. required
role object This user's assigned role in the database. required
version integer A monotonically-increasing version number. This version is incremented each time a change is made to the users permissions. required
inviteDate string The date on which the user was invited to this database. required
deliveryStatus string Values:
UNKNOWN
No record of email delivery is available for this user.
OK
Email has been successfully delivered to this user.
HARD_BOUNCE
Attempts to email this user failed with a "hard bounce," meaning that the account does not exist, or the domain is not accepting email.
SPAM_COMPLAINT
Attempts to email this user were rejected as spam by their mail server. No additional attempt will be made to send email to this user.
MANUAL_SUPPRESSION
Mail to this address have been manually blocked by ActivityInfo support staff.
required
inviteAccepted boolean True if the user has accept the invitation to create an ActivityInfo account. required

Add a database user

HTTP Request

POST https://www.activityinfo.org/resources/databases/{databaseId}/users

Request Body application/json

object
email string The email of the user to add required
name string The name of the user to add. This is only used in the email invitation to the user if there is no existing ActivityInfo account with this email address. required
locale string The locale to use when sending an email invite to the user. required
role object The role to assign to the user. required
grants array[object] Additional permissions to grant to the user. required

Responses application/json

Status CodeError CodeDescription
200User successfully added to database
401AUTHENTICATION_REQUIREDThe request must be authenticated, using basic authentication.
400CANNOT_ADD_OWNERThe owner of a database cannot be added as a user.
400CANNOT_ADD_SELFYou cannot add yourself to a database.
400DATABASE_NOT_FOUNDA database with this id could not be found
400INVALID_LOCALEThe requested locale is invalid or not available.
400ROLE_NOT_FOUNDA role with the requested id could not be found in this database.
400USER_ALREADY_ADDEDA user with this email address has already been added to the database.
402BILLING_ACCOUNT_CLOSEDThe billing account associated with this database has been closed and so no additional users can be added.
402BILLING_ACCOUNT_SUSPENDEDThe billing account associated with this database has been suspended so no additional users can be added.
402USER_LIMIT_EXCEEDEDThe user limit of the billing account associated with this database has been exceeded so no additional users can be added.
403PERMISSION_DENIEDYou do not have sufficient permission to add a user to this database.
500INTERNAL_SERVER_ERROR

Update a user's role

HTTP Request

POST https://www.activityinfo.org/resources/databases/{databaseId}/users/{userId}

Request Body application/json

object
assignments array[object] required

Deletes a user from a database

HTTP Request

DELETE https://www.activityinfo.org/resources/databases/{databaseId}/users/{userId}

Request Body application/json

object
assignments array[object] required

Responses application/json

Status CodeError CodeDescription
401AUTHENTICATION_REQUIREDThe request must be authenticated, using basic authentication.
200OKThe user was successfully deleted from the database
400DATABASE_DELETEDThe database was deleted and no longer exists.
400DATABASE_NOT_FOUNDA database with this id could not be found.
400USER_NOT_FOUNDA user with this id could not be found in the database.
403DELETED_USERS_PERMISSION_SUPERIORThe user with this id has permissions superior to yours and so you may not delete the user.
403MANAGE_USER_PERMISSION_MISSINGYou do not have the permission to manage users in this database.

Forms

Get a form's schema

HTTP Request

GET https://www.activityinfo.org/resources/form/{formId}

Update a form's schema

HTTP Request

POST https://www.activityinfo.org/resources/form/{formId}

Request Body application/json

object
id string required
label string required
schemaVersion string required
databaseId string required
parentFormId string optional
elements array[object] required

Records

Get a record

HTTP Request

GET https://www.activityinfo.org/resources/form/{formId}/record/{recordId}

curl -u me@example.com:mypassword \
  https://www.activityinfo.org/resources/form/ck8oyloog8/record/ck34ujs6v8
The above command returns JSON structured like this:
{
  "recordId": "cfso4igkhyvhmlv7",
  "formId": "cur8eeakhyvhmlv6",
  "fields": {
    "cgi0dqfkhyvhmlv8": "Simple text value",
    "cu30s7jkhyvhmlv9": {
      "prefix": "AA",
      "number": 3423
    },
    "c36jketkhyvhmlva": 42.5,
    "c9tmlsqkhyvhmlvb": [
      "crq4om7khyvhmm0c",
      "c5d64btkhyvhmm0d"
    ],
    "cll1culkhyvhmm6e": {
      "latitude": 52.0705,
      "longitude": -4.3007
    },
    "cljrnkwkhyvhmm7f": "ck8oyloog8:ck34ujs6v8",
    "clzjxvgkhyvhmm8g": "2019-12-31",
    "c31mm1bkhyvhmm8h": [
      {
        "mimeType": "application/pdf",
        "width": 0,
        "height": 0,
        "filename": "annual_report.pdf",
        "blobId": "l3cq9jkhyvhmm9i"
      }
    ]
  }
}

Query records in a form

Queries the form's records as list of JSON objects.

The request returns a list of JSON objects, with one object for each record.

Where provided, a field's code is used as the JSON field name, otherwise the field's label will be used.

By default, text values will be truncated to 128 characters. Truncation can be disabled by passing the query parameter _truncate=false.

Note that response size is limited to 32mb. You can reduce the size of the result set by querying for fewer columns, or using shorter column labels.

If you need to export more data than 32mb, consider using the Export API.

HTTP Request

GET https://www.activityinfo.org/form/{formId}/query/rows

curl -u me@example.com:mypassword \
  https://www.activityinfo.org/form/ck8oyloog8/query/rows
The above command returns JSON structured like this:
[
  {
    "record": "cbbhp94khyvhmmoj",
    "partnerId": "ck8oyloog8:ck34ujs6v8",
    "partnerName": "NRC",
    "num_kits": 42,
    "choose_any_id_you_like": 84,
    "date": "2020-01-31",
    "year": 2020
  },
  {
    "record": "cryj3p6khyvhmmok",
    "partnerName": "NRC",
    "num_kits": null,
    "choose_any_id_you_like": null,
    "date": "2020-01-31",
    "year": 2020
  }
]

Add, update, or delete records

Add, update, or delete one or more records.

The request can include up to 10 changes that are applied together.

When adding or updating records, fields objects should contain the new field values, with the field's id or code as the property name.

HTTP Request

POST https://www.activityinfo.org/resources/update

curl -X POST https://www.activityinfo.org/resources/update \
  -u me@example.com:mypassword \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "changes": [
    {
      "formId": "ck8oyloog8",
      "recordId": "ck34ujs6v8",
      "parentRecordId": null,
      "deleted": true,
      "fields": null
    },
    {
      "formId": "cum53sdkhyvhmmyl",
      "recordId": "c2ctpsvkhyvhmmym",
      "parentRecordId": null,
      "deleted": false,
      "fields": {
        "c1f3iv3khyvhmmyn": "Simple text value",
        "cjz39gwkhyvhmmyo": {
          "prefix": "AA",
          "number": 3423
        },
        "chmko3mkhyvhmmyp": 42.5,
        "cq28z3wkhyvhmmyq": [
          "cfmj33bkhyvhmmyr",
          "cna1rd4khyvhmmys"
        ],
        "csyxyt2khyvhmmyt": {
          "latitude": 52.0705,
          "longitude": -4.3007
        },
        "c1x3xd9khyvhmmyu": "ck8oyloog8:ck34ujs6v8",
        "ckmz4fkhyvhmmyv": "2019-12-31",
        "c1xlis1khyvhmmyw": [
          {
            "mimeType": "application/pdf",
            "width": 0,
            "height": 0,
            "filename": "annual_report.pdf",
            "blobId": "3y9i3ckhyvhmmyx"
          }
        ]
      }
    }
  ]
}
EOF

Request Body application/json

object
changes array[object] required

Reports

Get a report's definition

HTTP Request

GET https://www.activityinfo.org/resources/reports/{reportId}

curl -u me@example.com:mypassword \
  https://www.activityinfo.org/resources/reports/cht8p4kdeimokm5
The above command returns JSON structured like this:
{
  "id": "cht8p4kdeimokm5",
  "ownerId": "432201",
  "ownerName": "",
  "label": "My table",
  "model": {
    "visualization": "TABLE",
    "forms": [
      "ck8pu9ha07"
    ],
    "reports": [
      
    ],
    "measures": [
      {
        "id": "2f39q3khyvhmnny",
        "code": "",
        "label": "Number",
        "formId": "ck8pu9ha07",
        "formula": "Number",
        "statistics": [
          "SUM"
        ]
      }
    ],
    "dimensions": [
      {
        "id": "iirc81khyvhmnrz",
        "label": "",
        "mappings": [
          {
            "formula": "Gender",
            "type": "VALUE"
          }
        ],
        "axis": "ROW",
        "totals": false,
        "missingIncluded": false,
        "percentage": false,
        "dateLevel": null,
        "totalLabel": null,
        "missingLabel": null,
        "categoryMappings": [
          {
            "label": "Male",
            "source": [
              "Male"
            ],
            "visible": false
          }
        ],
        "mapTemplateId": null
      }
    ]
  },
  "grants": {
    "roles": [
      
    ]
  },
  "published": true,
  "modelType": "pivot"
}

Get a report's results as rows

Queries a pivot table's rows as list of JSON objects.

The request returns a list of JSON objects, with one object for each row in the report.

HTTP Request

GET https://www.activityinfo.org/resources/reports/{reportId}/rows

curl -u me@example.com:mypassword \
  https://www.activityinfo.org/resources/reports/cht8p4kdeimokm5/rows
The above command returns JSON structured like this:
[
  {
    "Gender": "Female",
    "Value": 97
  },
  {
    "Gender": "Male",
    "Value": 42
  }
]