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

ActivityInfo users can access the ActivityInfo API using a Personal API Token to authenticate to ActivityInfo.

The authentication token can be included in the request as the value of the Authorization header.

curl -H "Authorization: Bearer <API TOKEN>" \ https://www.activityinfo.org/resources/databases

For clients that only support Basic Authentication, the API token can be set as the 'password', with any value in the username field:

curl -u anything:<API TOKEN> \ https://www.activityinfo.org/resources/databases

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 anything:YOUR_API_TOKEN \
  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,
    "publishedTemplate": false
  },
  {
    "databaseId": "c4wb14glfs3a55z2",
    "label": "COVID-19 Response",
    "description": "",
    "ownerId": "432201",
    "billingAccountId": 3.4298234040238E13,
    "suspended": false,
    "publishedTemplate": 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
publishedTemplate boolean True if this database has been published as a template. 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 anything:YOUR_API_TOKEN \
  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. optional
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
ownerRef object required
language string Current database language required
originalLanguage string Original database language optional
languages array[string] The languages that have been defined for this database translation. required
continuousTranslation boolean True if the database continuous automatic translation is enabled required
translationFromDbMemory boolean True if automatic translation from database memory is allowed for the database required
thirdPartyTranslation boolean True if third-party translation is allowed for the database 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
securityCategories array[object] The security categories 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
publishedTemplate boolean 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
languageUpdates array[string] List of languages to add or update required
languageDeletions array[string] List of languages to delete required
originalLanguage string Original language update optional
continuousTranslation boolean Update of continuous automatic translation optional
translationFromDbMemory boolean Update of allowing the translation from database memory optional
thirdPartyTranslation boolean Update of allowing the use of third-party services for translation optional
publishedTemplate boolean optional

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 anything:YOUR_API_TOKEN \
  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:cjt46yclfs3a5hu3"
      },
      "resources": [
        "cn0lxeglfs3a5hu4",
        "cmnwsh3lfs3a5hu5"
      ]
    },
    "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.
400INVALID_ROLE_PARAMETERSThe role parameters must be a JSON object including a value for each of the role parameters.
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

Relocate a form to a new database

Relocating a form moves the form, together with all of its subforms, records, and record history, to a new database.

In order to relocate a form, the user must have "delete" permission in the source database, and permission to add new forms in the target database.

HTTP Request

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

Request Body application/json

object
databaseId string The id of the database to which this form should be transferred required

Responses application/json

Status CodeError CodeDescription
401AUTHENTICATION_REQUIREDThe request must be authenticated, using basic authentication.
200RELOCATEDThe form has been successfully relocated.
400CANNOT_RELOCATE_TO_SAME_DATABASEThe source and target databases are the same.
400SUB_FORMS_CANNOT_BE_RELOCATEDThe form requested to relocate is a subform. Only top level forms can be relocated.
403ADDING_FORM_FORBIDDENThe authenticated user does not have permission to add the form to the target database.
403DELETING_FORM_FORBIDDENThe authenticated user does not have permission to delete the form from its current database.
404DATABASE_NOT_FOUNDEither the source or target database does not exist.
404FORM_NOT_FOUNDNo such form with this id exists in the given database.

Records

Get a record

HTTP Request

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

curl -u anything:YOUR_API_TOKEN \
  https://www.activityinfo.org/resources/form/ck8oyloog8/record/ck34ujs6v8
The above command returns JSON structured like this:
{
  "recordId": "c6kcr2elfs3a5k97",
  "formId": "ca67dy4lfs3a5k96",
  "lastEditTime": 1.616167934481E12,
  "fields": {
    "co8ffaslfs3a5k98": "Simple text value",
    "cnk4yqplfs3a5k99": {
      "prefix": "AA",
      "number": 3423
    },
    "cpj31rrlfs3a5k9a": 42.5,
    "case12dlfs3a5kab": [
      "cy8ujhglfs3a5kgc",
      "cskv879lfs3a5kgd"
    ],
    "c5gtoa1lfs3a5kme": {
      "latitude": 52.0705,
      "longitude": -4.3007
    },
    "cxifestlfs3a5knf": "ck8oyloog8:ck34ujs6v8",
    "c29d51zlfs3a5kog": "2019-12-31",
    "c2n6cazlfs3a5koh": [
      {
        "mimeType": "application/pdf",
        "width": 0,
        "height": 0,
        "filename": "annual_report.pdf",
        "blobId": "fhodvllfs3a5kpi"
      }
    ]
  }
}

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.

HTTP Request

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

curl -u anything:YOUR_API_TOKEN \
  https://www.activityinfo.org/form/ck8oyloog8/query
The above command returns JSON structured like this:
[
  {
    "record": "cs24y79lfs3a5kzj",
    "partnerId": "ck8oyloog8:ck34ujs6v8",
    "partnerName": "NRC",
    "num_kits": 42,
    "choose_any_id_you_like": 84,
    "date": "2020-01-31",
    "year": 2020
  },
  {
    "record": "cfz0at0lfs3a5kzk",
    "partnerName": "NRC",
    "num_kits": null,
    "choose_any_id_you_like": null,
    "date": "2020-01-31",
    "year": 2020
  }
]

Query records as GeoJSON points

HTTP Request

GET https://www.activityinfo.org/form/{formId}/query/points?x={longitudeFormula}&y={latitudeFormula}

curl -u anything:YOUR_API_TOKEN \
  https://www.activityinfo.org/form/ck8oyloog8/query/points?x={longitudeFormula}&y={latitudeFormula}

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": "c4ua9y2lfs3a5l9l",
      "recordId": "calw287lfs3a5l9m",
      "parentRecordId": null,
      "deleted": false,
      "fields": {
        "ccif8tilfs3a5l9n": "Simple text value",
        "cwtlnjlfs3a5l9o": {
          "prefix": "AA",
          "number": 3423
        },
        "cms1onxlfs3a5l9p": 42.5,
        "ct8kqlalfs3a5l9q": [
          "cpackq5lfs3a5l9r",
          "cuhzq3xlfs3a5l9s"
        ],
        "c3zt0eylfs3a5l9t": {
          "latitude": 52.0705,
          "longitude": -4.3007
        },
        "clz7jt1lfs3a5l9u": "ck8oyloog8:ck34ujs6v8",
        "cu44s2nlfs3a5l9v": "2019-12-31",
        "cirz03plfs3a5l9w": [
          {
            "mimeType": "application/pdf",
            "width": 0,
            "height": 0,
            "filename": "annual_report.pdf",
            "blobId": "y7xfjtlfs3a5l9x"
          }
        ]
      }
    }
  ]
}
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 anything:YOUR_API_TOKEN \
  https://www.activityinfo.org/resources/reports/cht8p4kdeimokm5
The above command returns JSON structured like this:
{
  "id": "cht8p4kdeimokm5",
  "ownerType": "PERSONAL",
  "ownerId": "432201",
  "ownerName": "",
  "databaseId": null,
  "label": "My report",
  "published": true,
  "grants": {
    "roles": [
      
    ]
  },
  "layout": "SINGLE",
  "icon": "",
  "sources": {
    "forms": [
      "ck8pu9ha07"
    ],
    "reports": [
      
    ],
    "calculatedTables": [
      
    ]
  },
  "components": [
    {
      "id": "cv5wyndkqv9yuuq2",
      "type": "ANALYSIS",
      "content": "My table",
      "subtitle": null,
      "analysisType": "pivot",
      "visualizationType": null,
      "dataUrl": null,
      "visible": true,
      "position": null
    }
  ],
  "editType": "EDITABLE",
  "pages": [
    
  ]
}

Get an analysis definition

HTTP Request

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

curl -u anything:YOUR_API_TOKEN \
  https://www.activityinfo.org/resources/reports/cht8p4kdeimokm5/analyses/cv5wyndkqv9yuuq2
The above command returns JSON structured like this:
{
  "id": "cv5wyndkqv9yuuq2",
  "model": {
    "visualization": "TABLE",
    "measures": [
      {
        "id": "bfrxqvlfs3a5m8y",
        "code": "",
        "label": "Number",
        "formId": "ck8pu9ha07",
        "formula": "Number",
        "statistics": [
          "SUM"
        ],
        "calculated": false
      }
    ],
    "dimensions": [
      {
        "id": "o137y4lfs3a5mfz",
        "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
      }
    ]
  },
  "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 anything:YOUR_API_TOKEN \
  https://www.activityinfo.org/resources/reports/cht8p4kdeimokm5/rows
The above command returns JSON structured like this:
[
  {
    "Gender": "Female",
    "Value": 97
  },
  {
    "Gender": "Male",
    "Value": 42
  }
]

Jobs

Some requests, like exporting whole forms or databases, may take time to proccess. We call these "batch jobs" and they have a common API for starting batch jobs and retrieving their results.

For example, if you wanted to export an entire database, you would:

  1. Submit a request to Start a batch job
  2. Get the job's status until the job's state is COMPLETED or FAILED.
  3. Use the downloadUrl in the job result to retrieve the export.

Export form

HTTP Request

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

curl -X POST https://www.activityinfo.org/resources/jobs \
  -u me@example.com:mypassword \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "type": "exportForm",
  "descriptor": {
    "model": {
      "formId": "ck8pu9ha07",
      "columns": [
        
      ],
      "ordering": [
        {
          "formula": "AGE",
          "ascending": false
        }
      ],
      "filter": "AGE > 18"
    },
    "format": "TEXT",
    "utcOffset": 120
  },
  "locale": "en"
}
EOF

Request Body application/json

object
type string The type of the job to start. Must be 'exportForm' required
descriptor object required
The above command returns JSON structured like this:
{
  "type": "exportForm",
  "descriptor": {
    "model": {
      "formId": "ck8pu9ha07",
      "columns": [
        
      ],
      "ordering": [
        {
          "formula": "AGE",
          "ascending": false
        }
      ],
      "filter": "AGE > 18"
    },
    "format": "TEXT",
    "utcOffset": 120
  },
  "locale": "en"
}

Export database forms

HTTP Request

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

curl -X POST https://www.activityinfo.org/resources/jobs \
  -u me@example.com:mypassword \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "type": "exportDatabaseForms",
  "descriptor": {
    "databaseId": "ck8oykh8m5",
    "folderId": "ceponkikiswy1bt2",
    "format": "LONG",
    "fileFormat": "XLSX",
    "filter": "Month == '2021-01'",
    "includeBlanks": false,
    "utcOffset": 120
  },
  "locale": "en"
}
EOF

Request Body application/json

object
type string The type of the job to start. Must be 'exportDatabaseForms' required
descriptor object required
The above command returns JSON structured like this:
{
  "id": "c8my7utlfs3a5oq10",
  "userId": "432201",
  "type": "exportDatabaseForms",
  "descriptor": {
    "databaseId": "ck8oykh8m5",
    "folderId": "ceponkikiswy1bt2",
    "format": "LONG",
    "fileFormat": "XLSX",
    "filter": "Month == '2021-01'",
    "includeBlanks": false,
    "utcOffset": 120
  },
  "state": "completed",
  "locale": "EN",
  "percentComplete": 100,
  "result": {
    "downloadUrl": "resources/jobs/AXSDddl2aXR5aW5m32AJFDFadsl/My_database__20201124_124106_UTC.xlsx",
    "filename": "My_database__20201124_124106_UTC.xlsx"
  }
}

Get a batch job's status

HTTP Request

GET https://www.activityinfo.org/resources/jobs/{jobId}

Successful Response application/json

object
id string The job's id required
userId string The id of the user who started the job required
descriptor object The job descriptor used to start this job required
state string The job's current stateValues:
STARTED
The job has started processing.
COMPLETED
The job has completed successfully.
FAILED
The job has failed.
required
jobResult object required
locale string The localeValues:
EN
English
ID
Indonesian
ES
Spanish
EL
Greek
FR
French
HU
Hungarian
NL
Dutch
PL
Polish
PT
Portugese
RO
Romanian
RU
Russian
UK
Ukranian
TR
Turkish
AR
Arabic
FA
Persian
PS
Pashto
MY
Burmese
required
percentComplete float required
error object If the job state is FAILED, the reason for the failure. optional
The above command returns JSON structured like this:
{
  "id": "cce3i84lfs3a5pq11",
  "userId": "432201",
  "type": "exportDatabaseForms",
  "descriptor": {
    "databaseId": "ck8oykh8m5",
    "folderId": "ceponkikiswy1bt2",
    "format": "LONG",
    "fileFormat": "XLSX",
    "filter": "Month == '2021-01'",
    "includeBlanks": false,
    "utcOffset": 120
  },
  "state": "completed",
  "locale": "EN",
  "percentComplete": 100,
  "result": {
    "downloadUrl": "resources/jobs/AXSDddl2aXR5aW5m32AJFDFadsl/My_database__20201124_124106_UTC.xlsx",
    "filename": "My_database__20201124_124106_UTC.xlsx"
  }
}