API overview : Help Center

The Mobenzi API consists of 3 core components:

Server-side endpoints that allow you to programmatically do most of what is possible via the console
A set of submission event hooks that you can use to drive custom workflow
A JavaScript API that allows you to interact with a form that is in progress using a custom widget

Terminology differences between the console and server-side API

For backward compatibility the API uses slightly different terminology to the console:

Handsets (console) -> Devices (API)
Projects (console) -> Studies (API)
Forms (console) -> Surveys (API)

Overview of the server-side endpoints

The server-side API utilises Microsoft's WCF Data Services (formerly known as "ADO.NET Data Services"). This enables you to execute queries using familiar .NET Framework programming patterns, including using language integrated query (LINQ).

The server-side API is accessed via a set of endpoints that allow you to interact with the various entities within the system. Using these endpoints, you are are able to write code to:

Retrieve information about the projects and forms in your account
Retrieve captured data - List and filter submissions and retrieve captured data
Modify and delete captured data
Manage project resources that are used by forms
Manage devices, fieldworkers and form assignments
Interact with a form using a custom widget

Authentication and permissions

The API must be accessed via the SSL/HTTPS URL - https://console.mobenzi.com/secure/api.svc/. This ensures that any data accessed through the API is encrypted while being transferred. The API supports basic HTTPAuthentication.

To access the API programmatically, you will need to set the "Authorization" HTTP header when executing the web request to the relevant API endpoint. Please note that the credentials used should be that of a valid user setup in your console. We recommend creating a new user and specifying the permissions that you wish to use via the API and only for the projects you want to grant access to.

Please note that if the user account used to access the API is linked to more than one console, a custom HTTP header ("AccountID") must be set. The value of this header should be set to the unique identifier for the account you are targeting. If you are unsure what your unique console/account ID is, please contact support.

Listing projects and forms

When you query an endpoint to retrieve data, the API returns an XML response depending on the type of entity you are dealing with.

For example, to retrieve a list of projects that the user you are using to authenticate has access to, you would query the Studies endpoint - https://console.mobenzi.com/secure/api.svc/Studies. This would return an XML response with a structure similar to the following example:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<feed xml:base="http://console.mobenzi.com/secure/api.svc/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom">
  <title type="text">Studies</title>
  <id>http://console.mobenzi.com/secure/api.svc/Studies</id>
  <updated>2020-10-21T06:46:17Z</updated>
  <link rel="self" title="Studies" href="Studies" />
  <entry>
    <id>http://console.mobenzi.com/secure/api.svc/Studies(3505)</id>
    <title type="text"></title>
    <updated>2020-10-21T06:46:17Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" title="Study" href="Studies(3505)" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Surveys" type="application/atom+xml;type=feed" title="Surveys" href="Studies(3505)/Surveys" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SurveyFieldworkers" type="application/atom+xml;type=feed" title="SurveyFieldworkers" href="Studies(3505)/SurveyFieldworkers" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SurveySections" type="application/atom+xml;type=feed" title="SurveySections" href="Studies(3505)/SurveySections" />
    <category term="BLL.DAL.API.Study" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <content type="application/xml">
      <m:properties>
        <d:id m:type="Edm.Int32">3505</d:id>
        <d:name>Demo Project</d:name>
        <d:createdon m:type="Edm.DateTime">2018-09-27T16:29:42.727</d:createdon>
        <d:lastmodifiedon m:type="Edm.DateTime">2019-10-17T10:48:11.49</d:lastmodifiedon>
        <d:createdby>System</d:createdby>
        <d:lastmodifiedby>Demo User</d:lastmodifiedby>
        <d:archived m:type="Edm.Boolean">false</d:archived>
      </m:properties>
    </content>
  </entry>
</feed>

The Study (project) entity has the following properties:

Property	Type	Description
id	Integer	Unique identifier for the project (study)
name	String	User-defined name of the project (study)
createdon	Date/time	Date/time of when the project (study) was created
lastmodifiedon	Date/time	Date/time of when the project (study) was modified
createdby	String	Name of the user who created the project (study)
lastmodifiedby	String	Name of the user who modified the project (study)
archived	Boolean	Flag indicating whether or not the project has been archived

The Survey (form) entity has the following properties:

Property	Type	Description
id	Integer	Unique identifier for the form (survey)
title	String	Deprecated
name	String	User-defined name of the form - this will appear in the console and to fieldworkers/respondents completing the form
study_id	Integer	Unique identifier of the project (study) to which the form (survey) belongs
createdon	Date/time	Date/time of when the form (survey) was created
lastmodifiedon	Date/time	Date/time of when the form (survey) was modified
createdby	String	Name of the user who created the form (survey)
lastmodifiedby	String	Name of the user who modified the form (survey)
revision	Integer	Each time a new version of the form is published, the revision number increments automatically
status	String	Indicates the form status - i.e. "Draft", "Published", "Closed"
external_id	String	User-defined identifier assigned to the form (survey). This can be configured in the API settings for the form.

To retrieve a list of forms (Surveys) for a specific project (Study), you would use a LINQ query on the Surveys endpoint that specifies which project (study) you were interested in.

E.g. https://console.mobenzi.com/secure/api.svc/Surveys?filter=study_id eq 3505

This would return an XML response similar to the example below (which returns to Survey entities "Demo Form" and "Eligibility example" which are in the study with ID 3505):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<feed xml:base="http://console.mobenzi.com/secure/api.svc/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom">
  <title type="text">Surveys</title>
  <id>http://console.mobenzi.com/secure/api.svc/Surveys</id>
  <updated>2020-10-21T06:59:27Z</updated>
  <link rel="self" title="Surveys" href="Surveys" />
  <entry>
    <id>http://console.mobenzi.com/secure/api.svc/Surveys(20567)</id>
    <title type="text"></title>
    <updated>2020-10-21T06:59:27Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" title="Survey" href="Surveys(20567)" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Submissions" type="application/atom+xml;type=feed" title="Submissions" href="Surveys(20567)/Submissions" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Questions" type="application/atom+xml;type=feed" title="Questions" href="Surveys(20567)/Questions" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/DeviceSurveyRelationships" type="application/atom+xml;type=feed" title="DeviceSurveyRelationships" href="Surveys(20567)/DeviceSurveyRelationships" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SubmissionsWithLocations" type="application/atom+xml;type=feed" title="SubmissionsWithLocations" href="Surveys(20567)/SubmissionsWithLocations" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SurveyFieldworkers" type="application/atom+xml;type=feed" title="SurveyFieldworkers" href="Surveys(20567)/SurveyFieldworkers" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SurveySections" type="application/atom+xml;type=feed" title="SurveySections" href="Surveys(20567)/SurveySections" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/RawSubmissions" type="application/atom+xml;type=feed" title="RawSubmissions" href="Surveys(20567)/RawSubmissions" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SurveyAccessKeys" type="application/atom+xml;type=feed" title="SurveyAccessKeys" href="Surveys(20567)/SurveyAccessKeys" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Study" type="application/atom+xml;type=entry" title="Study" href="Surveys(20567)/Study" />
    <category term="BLL.DAL.API.Survey" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <content type="application/xml">
      <m:properties>
        <d:id m:type="Edm.Int32">20567</d:id>
        <d:title>Demo Form</d:title>
        <d:name>Demo Form</d:name>
        <d:study_id m:type="Edm.Int32">3505</d:study_id>
        <d:createdon m:type="Edm.DateTime">2018-09-27T16:29:43.513</d:createdon>
        <d:lastmodifiedon m:type="Edm.DateTime">2019-07-30T13:38:13.703</d:lastmodifiedon>
        <d:lastmodifiedby>Demo User</d:lastmodifiedby>
        <d:createdby>System</d:createdby>
        <d:revision m:type="Edm.Int32">29</d:revision>
        <d:status>Closed</d:status>
        <d:external_id>Demo form</d:external_id>
        <d:deleted m:type="Edm.Boolean">false</d:deleted>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>http://console.mobenzi.com/secure/api.svc/Surveys(21166)</id>
    <title type="text"></title>
    <updated>2020-10-21T06:59:27Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" title="Survey" href="Surveys(21166)" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Submissions" type="application/atom+xml;type=feed" title="Submissions" href="Surveys(21166)/Submissions" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Questions" type="application/atom+xml;type=feed" title="Questions" href="Surveys(21166)/Questions" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/DeviceSurveyRelationships" type="application/atom+xml;type=feed" title="DeviceSurveyRelationships" href="Surveys(21166)/DeviceSurveyRelationships" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SubmissionsWithLocations" type="application/atom+xml;type=feed" title="SubmissionsWithLocations" href="Surveys(21166)/SubmissionsWithLocations" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SurveyFieldworkers" type="application/atom+xml;type=feed" title="SurveyFieldworkers" href="Surveys(21166)/SurveyFieldworkers" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SurveySections" type="application/atom+xml;type=feed" title="SurveySections" href="Surveys(21166)/SurveySections" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/RawSubmissions" type="application/atom+xml;type=feed" title="RawSubmissions" href="Surveys(21166)/RawSubmissions" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SurveyAccessKeys" type="application/atom+xml;type=feed" title="SurveyAccessKeys" href="Surveys(21166)/SurveyAccessKeys" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Study" type="application/atom+xml;type=entry" title="Study" href="Surveys(21166)/Study" />
    <category term="BLL.DAL.API.Survey" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <content type="application/xml">
      <m:properties>
        <d:id m:type="Edm.Int32">21166</d:id>
        <d:title>Eligibility example</d:title>
        <d:name>Eligibility example</d:name>
        <d:study_id m:type="Edm.Int32">3505</d:study_id>
        <d:createdon m:type="Edm.DateTime">2018-11-17T12:30:40.65</d:createdon>
        <d:lastmodifiedon m:type="Edm.DateTime">2019-06-25T16:56:17.33</d:lastmodifiedon>
        <d:lastmodifiedby>Demo User</d:lastmodifiedby>
        <d:createdby>Demo User</d:createdby>
        <d:revision m:type="Edm.Int32">22</d:revision>
        <d:status>Published</d:status>
        <d:external_id>Eligibility example</d:external_id>
        <d:deleted m:type="Edm.Boolean">false</d:deleted>
      </m:properties>
    </content>
  </entry>
</feed>

Help Center

How can we help you today?

API overview Print

Terminology differences between the console and server-side API

Overview of the server-side endpoints

Authentication and permissions

Listing projects and forms

How can we help you today?

API overview Print

Terminology differences between the console and server-side API

Overview of the server-side endpoints

Authentication and permissions

Listing projects and forms

Related Articles