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 or Python for convenience.

Authentication

At this time, 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. Be sure to submit the requests over HTTPS to avoid sending plaintext passwords over the wire.

Form Model

The core concept in ActivityInfo is the Form. Users can create their own forms, by defining the fields that belong to that form.

ActivityInfo forms are analogous to "tables" in relational databases, but support richer field types.

Each FormField has a number of common properties:

Property	Type	Required	Description
label	string	Yes	A concise, human-readable label for the field.
description	string	No	A longer, more complete description of the field that may include instructions.
code	string	No	A short identifier that can be used to reference the field in the API and in formulas
required	string	Yes	If true, then a value must be supplied for this field
relevanceCondition	string	No	If provided, a boolean formula that determines the field is relevant
type	string	Yes	The field's type. (see below)
typeParameters	object	No	Additional properties specific to the field's type. (see below)

Field Types

Varying field types allow users to collect a rich set of data and enforce data quality rules.

text

The text field type allows up to 1024 characters of text on a single line.

They are encoded in input and output as JSON strings.

narrative

The narrative field type allows up to 4096 characters of text over multiple lines.

narrative values are encoded in input and output as JSON strings.

quantity

The quantity field type allows the input of real-valued numbers.

Parameter	Type	Description
units	string	Human-readable unit of measure. Used only for display purposes

They are encoded in input and output as JSON numbers.

date

The date field type represents a value in the ISO-8601 calendar

date values are encoded as JSON strings in the format "YYYY-MM-dd"

enumerated

The enumerated field type represents a choice between a set of pre-defined values.

Parameter	Type	Description
cardinality	string	Either "single" or "multiple"
values	array	An array of choices for the field.

enumerated choices are defined by both an id, which can never change, and a human-readable label, which can be changed.

A field that allows the user to choose the donor of a School Reconstruction, for example, could be described as follows:

{ "id": "ciwz6q9tkb", "label": "Donor", "visible": true, "required": true, "type": "enumerated", "typeParameters": { "cardinality": "single", "values": [ { "id": "ciwz6q9tlc", "label": "USAID" }, { "id": "ciwz6q9tld", "label": "DFID" }, { "id": "ciwz6q9tle", "label": "ECHO" } ] } }

geopoint

The geographic point type represents a point on the earth's surface as a latitude / longitude pair within the WGS 84 coordinate reference system.

geopoint values are encoded as JSON objects in the form { longitude: number, latitude: number }, for example:

{ latitude: 30.425, longitude: -136.325 }

geoarea

The geographic area type represents an area on the earth's surface described by a polygon.

calculated

Calculated fields do not store a value of their own but rather calculate their value based on the values of other fields in the same record.

Parameter	Type	Description
formula	string	Formula used to calculate the field's value

reference

Reference fields refer to records in other Forms, effectively creating relationships between forms.

The "range" parameter of a reference field is the set of forms to which the field can refer.

For example, a user might define two forms in their database: a "School" form and a "Student" form.

To link each "Student" record to the "School" record that s/he attends, the user could add a reference field to the Student Form, with the "School" form as its range:

{ label: "School", required: true, type: "reference", typeParameters: { range: [ { formId: "school_form" } ] }

attachment

The attachment field allows users to upload and store arbitrary documents or files in a form field.

Parameter	Type	Description
cardinality	string	Either "single" or "multiple"
kind	array	Either "image" or "attachment"

Migrating from the 2.x API

ActivityInfo was originally designed with a narrow set of use cases related to output monitoring in the field.

However, over time it became clear that the users appreciated the flexibility that even this constrained schema afforded and wanted to apply it to a larger range of use cases that required more flexibilty.

Forms API

Get a Form's Schema

{
  "id": "cjpmlu99a9",
  "schemaVersion": 0,
  "databaseId": "d0000000054",
  "label": "NFI Distribution",
  "description": "Form for collecting results of NFI distributions in North Kivu",
  "elements": [
    {
      "id": "cjpmlu99ca",
      "code": null,
      "label": "Date of Distribution",
      "description": null,
      "relevanceCondition": null,
      "visible": true,
      "required": true,
      "type": "date"
    },
    {
      "id": "a00000000330000000007",
      "code": null,
      "label": "Partner",
      "description": "The implementing partner who conducted the distribution",
      "relevanceCondition": null,
      "visible": true,
      "required": true,
      "type": "reference",
      "typeParameters": {
        "cardinality": "single",
        "range": [
          {
            "formId": "P0000000054"
          }
        ]
      }
    },
    {
      "id": "cjpmlu99ib",
      "code": null,
      "label": "Donor",
      "description": null,
      "relevanceCondition": null,
      "visible": true,
      "required": true,
      "type": "enumerated",
      "typeParameters": {
        "cardinality": "single",
        "presentation": "automatic",
        "values": [
          {
            "id": "cjpmlu99jc",
            "label": "USAID"
          },
          {
            "id": "cjpmlu99jd",
            "label": "DFID"
          },
          {
            "id": "cjpmlu99je",
            "label": "ECHO"
          }
        ]
      }
    },
    {
      "id": "cjpmlu99jf",
      "code": null,
      "label": "Number of households receiving a kit",
      "description": null,
      "relevanceCondition": null,
      "visible": true,
      "required": true,
      "type": "quantity",
      "typeParameters": {
        "units": "households",
        "aggregation": "SUM"
      }
    }
  ]
}

Retrieves the schema that describes this form's fields. A form in ActivityInfo is a set of records that have a common set of fields, or schema. A form can be a user-defined form created by a user, or it can be an application-defined like the set of countries, which has the id `_countries`.

HTTP Request

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

Parameters

Parameter	Optional?	Description
formId		Id of the form

Response

FormSchema {

id (string, required)

databaseId (string, required)

parentFormId (string, optional)

label (string, required)

code (string, optional)

description (string, optional)

elements (array, required)

}

Response Codes

Status	Description
200	The form's schema
401	The authenticated user does not have permission to view this form
404	The form does not exist.

Get a Form's Schema as XLSForm

Retrieves a Form's Schema, formatted as an XLSForm. XLSForm are Excel Workbooks that contain a tab called "survey" with the list of fields, and a tab called "choices" that contain the options for single and multiple select fields.

HTTP Request

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

Parameters

Parameter	Optional?	Description
formId		Id of the Form

Response Codes

Status	Description
200	The form's schema, converted to an XLSForm
401	The authenticated user does not have permission to view this form
404	The form does not exist.

Get a List of Forms

This endpoint provides access to a hierarchy of Forms that are visible to the authenticated user.

HTTP Request

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

Parameters

Parameter	Optional?	Description
parent	Yes	Fetches children of this parent.

Response Codes

Status	Description
200	The catalog

Updates a Form's Schema

Updates the form

HTTP Request

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

Parameters

Parameter	Optional?	Description
formId		Id of the Form

Response Codes

Status	Description
200	The form's schema was updated
400	The update was invalid. Not all changes to a schema are permitted. For example, a field's type cannot be changed.
401	The authenticated user does not have permission to update this form
404	The specified form does not exist

Records API

Create a New Record

HTTP Request

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

Parameters

Parameter	Optional?	Description
formId		Id of the Form

Response Codes

Status	Description
200	The record was updated
401	The authenticated user does not have permission to view this form
404	No form with `formId` exists.

Get All Records

Gets all records belonging to a Form.

HTTP Request

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

Parameters

Parameter	Optional?	Description
formId		Id of the Form containing the Record
parentId	Yes	Limits the records to those which are sub-records of this parent record id.

Response

FormRecordSet {

formId (string, optional)

records (array, optional)

}

Response Codes

Status	Description
200	The requested records
401	The authenticated user does not have permission to view this form
404	No form with `formId` exists

Get a Record's History

HTTP Request

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

Parameters

Parameter	Optional?	Description
formId		Id of the Form
recordId		Id of the record

Response Codes

Status	Description
200	The requested record
401	The authenticated user does not have permission to view this form or record
404	No record with `formId` exists

Get a Single Form Record

{
  "recordId": "cjpmlu98q2",
  "formId": "cjpmlu98q1",
  "fields": {
    "cjpmlu98u3": "Text Value",
    "cjpmlu98v4": 1500,
    "cjpmlu98v5": "2016-10-05",
    "cjpmlu98w6": {
      "latitude": 52.078663,
      "longitude": 4.288788
    },
    "cjpmlu98x7": "cjpmlu9918"
  }
}

HTTP Request

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

Parameters

Parameter	Optional?	Description
formId		Id of the Form
recordId		Id of the record

Response

FormRecord {

recordId (string, optional)

formId (string, optional)

parentRecordId (string, optional)

keyId (string, optional)

fields (object, optional)

}

Response Codes

Status	Description
200	The requested record
401	The authenticated user does not have permission to view this form or record
404	No record with `formId` exists

Update a Form Record

HTTP Request

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

Parameters

Parameter	Optional?	Description
formId		Id of the Form
recordId		Id of the record

Response Codes

Status	Description
200	The record was updated
401	The authenticated user does not have permission to view this form or record
404	No record with `formId` exists

Query API

Query Table Columns

HTTP Request

POST https://www.activityinfo.org/resources/query/columns

Parameters

Parameter	Optional?	Description

Response

ColumnSet {

numRows (integer, optional)

columns (array, optional)

}

Response Codes

Status	Description
200	The table as a list of column
401	The authenticated user does not have permission to view this form
404	No form with `formId` exists.