NAV
shell 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 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": "cjhlqm5d99",
  "schemaVersion": 0,
  "databaseId": "d0000000054",
  "label": "NFI Distribution",
  "description": "Form for collecting results of NFI distributions in North Kivu",
  "elements": [
    {
      "id": "cjhlqm5dba",
      "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": "cjhlqm5dgb",
      "code": null,
      "label": "Donor",
      "description": null,
      "relevanceCondition": null,
      "visible": true,
      "required": true,
      "type": "enumerated",
      "typeParameters": {
        "cardinality": "single",
        "presentation": "automatic",
        "values": [
          {
            "id": "cjhlqm5dhc",
            "label": "USAID"
          },
          {
            "id": "cjhlqm5dhd",
            "label": "DFID"
          },
          {
            "id": "cjhlqm5dhe",
            "label": "ECHO"
          }
        ]
      }
    },
    {
      "id": "cjhlqm5dhf",
      "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": "cjhlqm5cs2",
  "formId": "cjhlqm5cr1",
  "fields": {
    "cjhlqm5cv3": "Text Value",
    "cjhlqm5cw4": 1500,
    "cjhlqm5cw5": "2016-10-05",
    "cjhlqm5cx6": {
      "latitude": 52.078663,
      "longitude": 4.288788
    },
    "cjhlqm5cy7": "cjhlqm5d18"
  }
}

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.
shell R