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 Code	Error Code	Description
200		Database was successfully created.
401	AUTHENTICATION_REQUIRED	The request must be authenticated, using basic authentication.
400	BILLING_ACCOUNT_NOT_ACTIVE	The authenticated user's billing account is not active.
400	NO_BILLING_ACCOUNT	The authenticated user has no billing account, and so cannot add a database.
409	DATABASE_EXISTS	A 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 list of resources (folders, forms, and sub-forms)
• The user roles defined for the database
• The record locks in force

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
id	string		required
name	string		required
email	string		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
roleId	string	The id of the role assigned to this user.	required
roleParameters	object	The values of the parameters defined for this role.	required
roleResources	array[string]	The resources (database, folder, forms, or subforms) to which the role's permissions are to apply.	required
roles	array[object]	The roles that have been defined for this database.	required
id	string	This role's id	required
label	string	This role's human-readable label	required
permissions	array[object]	Permissions granted this role.	required
operation	string	Values: VIEW View the resource, whether a form, folder, or database. ADD_RECORD Add a record within a form contained by this folder or form. EDIT_RECORD Edit a record's values within a form contained by this folder or form. MANAGE_REFERENCE_DATA Add, edit, and delete records within reference forms DELETE_RECORD Delete a record within this form. BULK_DELETE Bulk record delete within this form EXPORT_RECORDS Export Records from a form, folder or database. MANAGE_USERS Grant permissions to a user to this database, folder, or form. LOCK_RECORDS Add, modify, or remove locks on records. ADD_RESOURCE Create a new Resource (Form or Folder) EDIT_RESOURCE Edit a Resource's schema, structure, attributes or data. DELETE_RESOURCE Delete a Resource (Form or Folder) MANAGE_COLLECTION_LINKS Manage (open/close) collection links for the given form AUDIT Access the Audit logs for a database (or a subset) SHARE_REPORTS Allow the user to share reports with other roles in the database. PUBLISH_REPORTS Allows the user to publish reports. MANAGE_ROLES Add, modify and delete roles MANAGE_TRANSLATIONS Allows the user to manage the translations.	required
filter	string	A formula which restricts a permission to specific records. Only record-level permissions can be filtered.	optional
securityCategories	array[string]		required
parameters	array[object]	Parameters defined for this role. Parameters can be referenced in filtering formulas.	required
parameterId	string		required
label	string		required
range	string		required
filters	array[object]	Pre-defined filters. Role filters allow other users to choose filters for permissions without having to write formulas themselves.	required
id	string	This filter's id.	required
label	string	This filter's human-readable label	required
filter	string	A formula that can be used to filter a record-level permission.	required
grants	array[object]		required
resourceId	string		required
operations	array[string]		required
version	integer		required
grantBased	boolean		required
securityCategories	array[object]	The security categories that have been defined for this database.	required
id	string	This security category's id	required
label	string	This security category's human-readable label	required
resources	array[object]	The set of resources (folders, forms, and subforms) that belong to this database.	required
id	string	The resource's id. Form and subform resources must have globally-unique ids (across all of ActivityInfo) but folder ids are only guaranteed to be unique within a single database.	required
type	string	The resource type.Values: DATABASE FOLDER REPORT FORM SUB_FORM	required
parentId	string	The id of this resource's parent, for example, a folder id. If this is a top-level folder or form, the the parentId will be the id of the database itself.	required
label	string	The resource's human-readable label.	required
visibility	string	The resource's visibility.Values: PUBLIC Public. Visible to *all* Users on system, regardless of assigned permissions. DATABASE_USERS Visible to any user who has been add PRIVATE Visible only to users given explicit permissions. REFERENCE Visible only if another Resource on the Database is visible to the current User. Used to provide Forms with data to be referenced, but not requiring an explicit grant to be generated for the User.	required
locks	array[object]	The record locks that have been defined on this database.	required
id	string	This lock's id.	required
label	string	A human-readable label for this lock	required
resourceId	string	The resource (database, folder, form, or subform) to which this lock applies.	required
dateRange	object	The date range to which this lock applies.	optional
startDate	local_date		required
endDate	local_date		required
formula	string	The formula to which this rule based lock applies.	optional
message	string	user descroption pf the rule based lock.	optional
deactivated	boolean		required
grants	array[object]	The permission grants that have been made to the requesting user for this database.	required
resourceId	string		required
operations	array[string]		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
id	string	The resource's id. Form and subform resources must have globally-unique ids (across all of ActivityInfo) but folder ids are only guaranteed to be unique within a single database.	required
type	string	The resource type.Values: DATABASE FOLDER REPORT FORM SUB_FORM	required
parentId	string	The id of this resource's parent, for example, a folder id. If this is a top-level folder or form, the the parentId will be the id of the database itself.	required
label	string	The resource's human-readable label.	required
visibility	string	The resource's visibility.Values: PUBLIC Public. Visible to *all* Users on system, regardless of assigned permissions. DATABASE_USERS Visible to any user who has been add PRIVATE Visible only to users given explicit permissions. REFERENCE Visible only if another Resource on the Database is visible to the current User. Used to provide Forms with data to be referenced, but not requiring an explicit grant to be generated for the User.	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
id	string	This lock's id.	required
label	string	A human-readable label for this lock	required
resourceId	string	The resource (database, folder, form, or subform) to which this lock applies.	required
dateRange	object	The date range to which this lock applies.	optional
startDate	local_date		required
endDate	local_date		required
formula	string	The formula to which this rule based lock applies.	optional
message	string	user descroption pf the rule based lock.	optional
deactivated	boolean		required
lockDeletions	array[string]	List of lock ids to delete	required
roleUpdates	array[object]	List of roles to add or update.	required
id	string	This role's id	required
label	string	This role's human-readable label	required
permissions	array[object]	Permissions granted this role.	required
operation	string	Values: VIEW View the resource, whether a form, folder, or database. ADD_RECORD Add a record within a form contained by this folder or form. EDIT_RECORD Edit a record's values within a form contained by this folder or form. MANAGE_REFERENCE_DATA Add, edit, and delete records within reference forms DELETE_RECORD Delete a record within this form. BULK_DELETE Bulk record delete within this form EXPORT_RECORDS Export Records from a form, folder or database. MANAGE_USERS Grant permissions to a user to this database, folder, or form. LOCK_RECORDS Add, modify, or remove locks on records. ADD_RESOURCE Create a new Resource (Form or Folder) EDIT_RESOURCE Edit a Resource's schema, structure, attributes or data. DELETE_RESOURCE Delete a Resource (Form or Folder) MANAGE_COLLECTION_LINKS Manage (open/close) collection links for the given form AUDIT Access the Audit logs for a database (or a subset) SHARE_REPORTS Allow the user to share reports with other roles in the database. PUBLISH_REPORTS Allows the user to publish reports. MANAGE_ROLES Add, modify and delete roles MANAGE_TRANSLATIONS Allows the user to manage the translations.	required
filter	string	A formula which restricts a permission to specific records. Only record-level permissions can be filtered.	optional
securityCategories	array[string]		required
parameters	array[object]	Parameters defined for this role. Parameters can be referenced in filtering formulas.	required
parameterId	string		required
label	string		required
range	string		required
filters	array[object]	Pre-defined filters. Role filters allow other users to choose filters for permissions without having to write formulas themselves.	required
id	string	This filter's id.	required
label	string	This filter's human-readable label	required
filter	string	A formula that can be used to filter a record-level permission.	required
grants	array[object]		required
resourceId	string		required
operations	array[string]		required
version	integer		required
grantBased	boolean		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 Code	Error Code	Description
200		The database was successfully updated
401	AUTHENTICATION_REQUIRED	The request must be authenticated, using basic authentication.
400	INVALID_UPDATE	One of the items to be deleted could not be found
403	PERMISSION_DENIED
404	DATABASE_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
roleId	string	The id of the role assigned to this user.	required
roleParameters	object	The values of the parameters defined for this role.	required
roleResources	array[string]	The resources (database, folder, forms, or subforms) to which the role's permissions are to apply.	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
roleId	string	The id of the role assigned to this user.	required
roleParameters	object	The values of the parameters defined for this role.	required
roleResources	array[string]	The resources (database, folder, forms, or subforms) to which the role's permissions are to apply.	required
grants	array[object]	Additional permissions to grant to the user.	required
resourceId	string		required
operations	array[string]		required

Responses application/json

Status Code	Error Code	Description
200		User successfully added to database
401	AUTHENTICATION_REQUIRED	The request must be authenticated, using basic authentication.
400	CANNOT_ADD_OWNER	The owner of a database cannot be added as a user.
400	CANNOT_ADD_SELF	You cannot add yourself to a database.
400	DATABASE_NOT_FOUND	A database with this id could not be found
400	INVALID_LOCALE	The requested locale is invalid or not available.
400	INVALID_ROLE_PARAMETERS	The role parameters must be a JSON object including a value for each of the role parameters.
400	ROLE_NOT_FOUND	A role with the requested id could not be found in this database.
400	USER_ALREADY_ADDED	A user with this email address has already been added to the database.
402	BILLING_ACCOUNT_CLOSED	The billing account associated with this database has been closed and so no additional users can be added.
402	BILLING_ACCOUNT_SUSPENDED	The billing account associated with this database has been suspended so no additional users can be added.
402	USER_LIMIT_EXCEEDED	The user limit of the billing account associated with this database has been exceeded so no additional users can be added.
403	PERMISSION_DENIED	You do not have sufficient permission to add a user to this database.
500	INTERNAL_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
roleId	string	The id of the role assigned to this user.	required
roleParameters	object	The values of the parameters defined for this role.	required
roleResources	array[string]	The resources (database, folder, forms, or subforms) to which the role's permissions are to apply.	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
roleId	string	The id of the role assigned to this user.	required
roleParameters	object	The values of the parameters defined for this role.	required
roleResources	array[string]	The resources (database, folder, forms, or subforms) to which the role's permissions are to apply.	required

Responses application/json

Status Code	Error Code	Description
401	AUTHENTICATION_REQUIRED	The request must be authenticated, using basic authentication.
200	OK	The user was successfully deleted from the database
400	DATABASE_DELETED	The database was deleted and no longer exists.
400	DATABASE_NOT_FOUND	A database with this id could not be found.
400	USER_NOT_FOUND	A user with this id could not be found in the database.
403	DELETED_USERS_PERMISSION_SUPERIOR	The user with this id has permissions superior to yours and so you may not delete the user.
403	MANAGE_USER_PERMISSION_MISSING	You 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
id	string		required
code	string		required
label	string		required
relevanceCondition	string		required
validationCondition	string		required
visible	boolean		required
required	boolean		required
key	boolean		required
type	string		required
securityCategoryId	string		optional
typeParameters	object		required
units	string		optional
inputMask	string		optional
cardinality	string		optional
range	object		optional
formId	string		optional
items	array[object]		optional
formula	string		optional
prefixFormula	string		optional

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 Code	Error Code	Description
401	AUTHENTICATION_REQUIRED	The request must be authenticated, using basic authentication.
200	RELOCATED	The form has been successfully relocated.
400	CANNOT_RELOCATE_TO_SAME_DATABASE	The source and target databases are the same.
400	SUB_FORMS_CANNOT_BE_RELOCATED	The form requested to relocate is a subform. Only top level forms can be relocated.
403	ADDING_FORM_FORBIDDEN	The authenticated user does not have permission to add the form to the target database.
403	DELETING_FORM_FORBIDDEN	The authenticated user does not have permission to delete the form from its current database.
404	DATABASE_NOT_FOUND	Either the source or target database does not exist.
404	FORM_NOT_FOUND	No 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
formId	string		required
recordId	string		required
parentRecordId	string		optional
deleted	boolean		required
fields	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
tableModel	object		required
formId	string	The id of the form from which the table should be created.	required
columns	array[object]	A list of columns to include in the table. If the list is empty, a list of columns will be computed from the form's fields.	required
id	string	The id of the column. This is used to identify the column in the result.	required
label	string	The text to use as the column's header.	optional
width	integer	The width, in pixels of the column.	required
formula	string	The formula used to compute this column's values.	required
ordering	array[object]	List of columns to use in ordering the form's records.	required
formula	string		required
ascending	boolean		required
filter	string	A boolean-valued formula which filters which records are included.	optional
format	string	Values: XLSX Office Open XML .xlsx file. DOCX Office Open XML .xlsx file. PDF Adobe Portable Document Format (PDF) TEXT UTF-8 encoded text file, with rows seperated by newline characters ('\n') and columns seperated by the INFORMATION SEPARATOR control character (U+001F). Can only be used for a single form, or for database forms exported using the LONG format.	required
utcOffset	integer	The time zone to use for time values, as an offset from Universal Coordinate Time (UTC) in minutes,	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
databaseId	string	The id of the database containing the forms to export.	required
folderId	string	Optionally, the folder or form to include in the export. If ommitted, then all forms in the database will be included.	optional
format	string	The format of the table structure.Values: LONG All forms are exported in one long table. Each quantity appears its own row, and text fields, single select fields, and reference field keys appear in columns. WIDE Forms are exported one form per sheet, with each record in a new row. Each field is in its own column.	required
fileFormat	string	The file format.Values: XLSX Office Open XML .xlsx file. DOCX Office Open XML .xlsx file. PDF Adobe Portable Document Format (PDF) TEXT UTF-8 encoded text file, with rows seperated by newline characters ('\n') and columns seperated by the INFORMATION SEPARATOR control character (U+001F). Can only be used for a single form, or for database forms exported using the LONG format.	required
filter	string	A formula that is applied to each form to filter the resulting records.	optional
includeBlanks	boolean	True if the export should include rows for blank quantities. Only applies to the LONG format.	required
utcOffset	integer	The time zone to use for time values, as an offset from Universal Coordinate Time (UTC) in minutes,	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
filename	string	The filename of the export.	required
downloadUrl	string	The (par	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
code	string		required
message	string		required
localizedMessage	string		required

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"
  }
}