The Mobenzi API supports event hooks that are triggered when:

  1. A form is sent to a fieldworker. See Form Override event hook.
  2. A submission is received, modified or deleted. See Submission event hooks.


The API also allows you to programatically query and modify your submissions or connect to third-party tools such as PowerBI.


The API can be used to perform powerful server-side logic or integration with third-party systems using Restful ADO.NET Data Services. To simplify the process of mapping the XML or JSON responses back into usable objects, several common wrapper classes have been created in different languages to assist third-party developers. An example of a program using this C# wrapper DLL has been attached to this article (see attachments).


Making use of the C# Wrapper

Once you have added a reference to the DLL (MobenziResearcher.API.dll) and included the Mobenzi Researcher API wrapper namespace (MobenziResearcher.API), you should be able to view the available functionality exposed by examining the IAPIService interface. An example of fetching all submissions for the last day for a specified form is as simple as:



Mobenzi API Entities

  • Survey, SurveySection and Question entities define the structure of a form. A Survey entity contains multiple SurveySection entities that in turn hold multiple Question entities.
  • Submission entities describe captured data with each individual value captured in a Response entity. For field types where the fieldworker has selected an option from a list, the ResponseOptions entity stores the various options that were available.


To review all entities accessible via the Mobenzi API you can navigate to the Mobenzi API service https://console.mobenzi.com/secure/api.svc/ once you have logged in to your account.


If you wish to review data for a particular entity, you can specify this as follows: https://console.mobenzi.com/secure/api.svc/{Entity} – please note that {Entity} should be replaced with the entity you are interested in reviewing. Also note that the API is case-sensitive. For example, if you wished to review all Question (Field) entities for your console (across all forms), you would navigate to https://console.mobenzi.com/secure/api.svc/Questions


Note: Use filters to limit entities returned


Please be aware that when accessing records for a particular entity in the fashion described above, a query to retrieve all data (i.e. no filtering is applied) will be produced. If you access the Response or Submission entities in this manner, all Responses/Submissions will be returned. This may cause your browser to freeze or crash as there are usually a large number of these entities accessible through your console.



Searching and Filtering

ADO.NET Data Services provides a rich query protocol which allows you to search and filter the data you may be interested in.


For example, to review the first 10 Submissions for 2018, you could so as follows:


If you wished to include the actual responses for each of the first 10 Submissions for 2018, you could so as follows:



Query String Options


Option
Description
Example
 expand
The ‘expand’ option allows you to embed one or more sets of related entities in the results. For example, if you want to display a Submission and its Responses, you could execute two requests, one for /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’) and one for /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’)/Responses. 

The ‘expand’ option on the other hand allows you to return the related entities in-line with the response of the parent in a single HTTP request. You may specify multiple navigation properties to expand by separating them with commas, and you may traverse more than one relationship by using a dot to jump to the next navigation property.
A Submission with related Responses: /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’)?$expand=Responses. 

A Submission with related Responses and Response Options related to each Response: /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’)?$expand=Responses/ResponseOptions. 

A Submission with related Responses and Survey: Orders with related /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’)?$expand=Responses,Survey
orderby
Sort the results by the criteria given in this value. Multiple properties can be indicated by separating them with a comma. The sort order can be controlled by using the “asc” (default) and “desc” modifiers.
/Submissions?$orderby=uploaddate /Submissions?$orderby=uploaddate desc 
/Submissions?$orderby=uploaddate,survey_id desc
skip
Skip a given number of rows when returning results. This is useful in combination with “top” to implement paging (e.g. if using 10-entity pages, saying $skip=30&top=$10 would return the fourth page). NOTE: Skip only makes sense on sorted sets; if an orderby option is included, ‘skip’ will skip entities in the order given by that option. If no orderby option is given, ‘skip’ will sort the entities by their primary key and then perform the skip operation.
Return all Submissions except the first 10: 
/Submissions?$skip=10 

Return the 4th page where each page shows only 10
Submissions: /Submissions?$skip=30&$top=10
top
Restrict the maximum number of entities to be returned. This option is useful both by itself and in combination with skip, where it can be used to implement paging as discussed in the description of ‘skip’.
Top 10 Submissions: /Submissions?$top=10 
Get the last 10 Submissions: /Submissions?$orderby=uploaddate desc&$top=10
filter
Restrict the entities returned from a query by applying the expression specified in this operator to the entity set identified by the last segment of the URL path.
Get all Submissions for Survey with Id 101 : 
/Submissions?$filter=survey_id eq 101 
Get all Questions where the question name contains “health”: /Questions?$filter=substringof(‘health’, name)


Logical Operators


Operator
Description
Example
  eq
  Equal
 /Questions?filter=name eq ‘Health district’
  ne
  Not equal 
/Questions?filter=name ne ‘Health district’
  gt
  Greater than
 /Submissions?$filter=year(uploaddate) gt 2009
  ge
  Greater than or equal
/Submissions?$filter=year(uploaddate) ge 2010
  lt
  Less than
 /Submissions?$filter=year(uploaddate) lt 2009
  le
  Less than or equal
/Submissions?$filter=year(uploaddate) le 2010
  and
  Logical and
 /Submissions?$filter=year(uploaddate) le 2010 and survey_id = 101
  or
  Logical or
/Submissions?$filter=year(uploaddate) eq 2008 or year(uploaddate) eq 2010
  not
  Logical negation
 /Questions?$filter=not endswith(name,‘test.’)


Arithmetic Operators


Operator
Description
Example
add
 Addition
 /Submissions?$filter=hour(uploaddate) add 5 gt 10
sub
 Subtraction
 /Submissions?$filter=hour(uploaddate) sub 5 gt 3
mul
Multiplication
 /Submissions?$filter=minute(uploaddate) mul 0.5 lt 3
div
Division
/Submissions?$filter=minute(uploaddate) div 2 lt 3
 mod
Modulo
 /Submissions?$filter=minute(uploaddate) mod 2 eq 3


Grouping Operators


Operator
Description
Example
 ()
 Precedence grouping
 /Responses?filter=(year(Submission/uploaddate) sub 5) lt 2005


Other Functions


String Functions
Date Functions
Math Functions
 bool substringof(string p0, string p1)
 int day(DateTime p0)
 double round(double p0)
 bool endswith(string p0, string p1)
 int hour(DateTime p0)
decimal round(decimal p0)
bool startswith(string p0, string p1)
int minute(DateTime p0)
 double floor(double p0)
int length(string p0)
 int month(DateTime p0)
 decimal floor(decimal p0)
 int indexof(string arg)
int second(DateTime p0)
 double ceiling(double p0)
 string insert(string p0, int pos, string p1)
 int year(DateTime p0)
decimal ceiling(decimal p0)
 string remove(string p0, int pos)
 
 
 string remove(string p0, int pos, int length)
 
 
string replace(string p0, string find, string replace)
 
 
 string substring(string p0, int pos)
 
 
 string substring(string p0, int pos, int length)
 
 
string tolower(string p0)
 
 
 string toupper(string p0)
 
 
 string trim(string p0)
 
 
 string concat(string p0, string p1)
 
 


Authentication


The API should always be accessed via the SSL/HTTPS endpoint. 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. To access the Submission and Response data, the user should be setup with the View Responses permission.


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


Updating and Deleting API Entities


Currently, it is only possible to update and delete Response entities via the API. In future, the API will be upgraded to support modification and deletes of other entities such as Submissions. Please review the section on request authentication above to ensure that all requests to update/delete entities via the API carry the correct authentication tokens.


To delete a response, the response ID is required. The following HTTP DELETE action will delete a response with the ID ‘E271F157-4356-4E16-B63B-AD681AED7BEE’:


To update a response, the response ID is required. The HTTP MERGE method action and payload will update a response with ID ‘E271F157-4356-4E16-B63B-AD681AED7BEE’: