The Mobenzi API allows you to programatically query and retrieve captured data and to pull data into third-party databases or analysis tools such as PowerBI. The 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).


Submissions and Responses


In the Mobenzi console, when a form is uploaded, a Submission entity is created. Linked to the submission entity are the individual values corresponding to each field in the form (survey). Each value is stored in a Response entity.


To access Submission entities via the API, you would query the Submissions API service: https://console.mobenzi.com/secure/api.svc/Submissions. 


This request would return all submissions in your account - across all projects and forms. In most scenarios, this is not the desired behaviour and you would use a filter to select the submission(s) you were looking for - e.g. by date range or matching a specific set of criteria.


When a Submission entity is created, it is given a globally unique identifier (GUID) - for example 87c28027-9078-4512-ac4e-377cb319ace5. If you wished to retrieve this specific submission, you could use the guid in the request as follows: https://console.mobenzi.com/secure/api.svc/Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5'). 


This would return XML describing the specified submission, e.g.:


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry 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">
  <id>http://console.mobenzi.com/secure/api.svc/Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')</id>
  <title type="text"></title>
  <updated>2020-10-09T16:19:20Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="Submission" href="Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Responses" type="application/atom+xml;type=feed" title="Responses" href="Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')/Responses" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Survey" type="application/atom+xml;type=entry" title="Survey" href="Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')/Survey" />
  <category term="BLL.DAL.API.Submission" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <content type="application/xml">
    <m:properties>
      <d:id m:type="Edm.Guid">87c28027-9078-4512-ac4e-377cb319ace5</d:id>
      <d:survey_id m:type="Edm.Int32">29350</d:survey_id>
      <d:uploaddate m:type="Edm.DateTime">2020-10-09T16:17:01.927</d:uploaddate>
      <d:surveystartdate m:type="Edm.DateTime">2020-10-09T16:17:13</d:surveystartdate>
      <d:surveyenddate m:type="Edm.DateTime">2020-10-09T16:17:20</d:surveyenddate>
      <d:language_id m:type="Edm.Int32">1</d:language_id>
      <d:fieldworker_id m:type="Edm.Guid">01ee8946-6b13-4886-b54a-72158e54318b</d:fieldworker_id>
      <d:uploadedby>Some User</d:uploadedby>
      <d:lastmodifiedby>Some User</d:lastmodifiedby>
      <d:lastmodifieddate m:type="Edm.DateTime">2020-10-09T16:17:01.927</d:lastmodifieddate>
      <d:IsIncomplete m:type="Edm.Boolean">false</d:IsIncomplete>
      <d:ReasonForIncompletion>Web collection in progress</d:ReasonForIncompletion>
    </m:properties>
  </content>
</entry>


Note that a Submission entity itself does not store any user-captured data - it is a container that includes details about the submission (stored in the properties section):


PropertyTypeDescription
id
GUIDUnique identifier for the submission.
survey_idInteger
Unique identifier of the survey (form) to which the submission belongs. See how to retrieve survey (form) details.
uploaddateDate/TimeDate/time at which the submission was received by the server (UTC).
suveystartdateDate/TimeDate/time at which the submission was started. If this was captured via the mobile app, this will be based on the handset's date/time settings.
surveyenddateDate/TimeDate/time at which the submission was completed. If this was captured via the mobile app, this will be based on the handset's date/time settings.
language_idIntegerIdentifies which language the survey / form was captured in. See API lookup reference.
fieldworker_idGUIDIf the submission was captured by a fieldworker, this will specify their unique identifier. See how to retrieve fieldworker details.
uploadedbyStringIf the submission was captured by a fieldworker, this provides their name, as it appeared at the time the submission was uploaded.
lastmodifiedbyStringThis stores the name of the user who last modified the submission.
IsIncompleteBooleanIf the submission is still in progress, this will be set to true. Once complete, this will be updated to false.
ReasonForIncompletionStringIf the submission is still in progress, the reason why the submission has not yet been completed will be indicated - e.g. they user has not yet finished completing the form. If you enable "submit incomplete" fieldworker collection setting, the fieldworker can specify why the submission could not be completed.


To include the actual response data, you can specify this by using the "expand" keyword in the request:


https://console.mobenzi.com/secure/api.svc/Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')?$expand=Responses


This would return the same information as before, but now will include the Response entities too. In the example below, there are two fields that have been captured: respondent_gender and respondent_name with values "M" and "John" respectively. Each Response entity includes the actual data stored for the corresponding field (e.g. the string "John") as well as meta data about the Response such as the field type.


<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry 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">
  <id>http://console.mobenzi.com/secure/api.svc/Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')</id>
  <title type="text"></title>
  <updated>2020-10-09T16:30:29Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="Submission" href="Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Responses" type="application/atom+xml;type=feed" title="Responses" href="Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')/Responses">
    <m:inline>
      <feed>
        <title type="text">Responses</title>
        <id>http://console.mobenzi.com/secure/api.svc/Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')/Responses</id>
        <updated>2020-10-09T16:30:29Z</updated>
        <link rel="self" title="Responses" href="Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')/Responses" />
        <entry>
          <id>http://console.mobenzi.com/secure/api.svc/Responses(guid'c83996e4-2eb3-4577-8697-04f4b138d12d')</id>
          <title type="text"></title>
          <updated>2020-10-09T16:30:29Z</updated>
          <author>
            <name />
          </author>
          <link rel="edit" title="Response" href="Responses(guid'c83996e4-2eb3-4577-8697-04f4b138d12d')" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ResponseOptions" type="application/atom+xml;type=feed" title="ResponseOptions" href="Responses(guid'c83996e4-2eb3-4577-8697-04f4b138d12d')/ResponseOptions" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ResponseHistories" type="application/atom+xml;type=feed" title="ResponseHistories" href="Responses(guid'c83996e4-2eb3-4577-8697-04f4b138d12d')/ResponseHistories" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Submission" type="application/atom+xml;type=entry" title="Submission" href="Responses(guid'c83996e4-2eb3-4577-8697-04f4b138d12d')/Submission" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SubmissionsWithLocation" type="application/atom+xml;type=entry" title="SubmissionsWithLocation" href="Responses(guid'c83996e4-2eb3-4577-8697-04f4b138d12d')/SubmissionsWithLocation" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/RawSubmission" type="application/atom+xml;type=entry" title="RawSubmission" href="Responses(guid'c83996e4-2eb3-4577-8697-04f4b138d12d')/RawSubmission" />
          <category term="BLL.DAL.API.Response" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
          <content type="application/xml">
            <m:properties>
              <d:id m:type="Edm.Guid">c83996e4-2eb3-4577-8697-04f4b138d12d</d:id>
              <d:submission_id m:type="Edm.Guid">87c28027-9078-4512-ac4e-377cb319ace5</d:submission_id>
              <d:survey_id m:type="Edm.Int32">29350</d:survey_id>
              <d:name>respondent_gender</d:name>
              <d:questiontype>Xform Select One</d:questiontype>
              <d:responsevalue>M</d:responsevalue>
              <d:instance m:type="Edm.Int32">0</d:instance>
              <d:date m:type="Edm.DateTime">2020-10-09T16:17:02.137</d:date>
              <d:question_id m:type="Edm.Int32">1722120</d:question_id>
              <d:question_external_id>respondent_gender</d:question_external_id>
              <d:comment m:null="true" />
            </m:properties>
          </content>
        </entry>
        <entry>
          <id>http://console.mobenzi.com/secure/api.svc/Responses(guid'fe3e57d8-96b1-41e9-8be4-34bc70c27fbc')</id>
          <title type="text"></title>
          <updated>2020-10-09T16:30:29Z</updated>
          <author>
            <name />
          </author>
          <link rel="edit" title="Response" href="Responses(guid'fe3e57d8-96b1-41e9-8be4-34bc70c27fbc')" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ResponseOptions" type="application/atom+xml;type=feed" title="ResponseOptions" href="Responses(guid'fe3e57d8-96b1-41e9-8be4-34bc70c27fbc')/ResponseOptions" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ResponseHistories" type="application/atom+xml;type=feed" title="ResponseHistories" href="Responses(guid'fe3e57d8-96b1-41e9-8be4-34bc70c27fbc')/ResponseHistories" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Submission" type="application/atom+xml;type=entry" title="Submission" href="Responses(guid'fe3e57d8-96b1-41e9-8be4-34bc70c27fbc')/Submission" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SubmissionsWithLocation" type="application/atom+xml;type=entry" title="SubmissionsWithLocation" href="Responses(guid'fe3e57d8-96b1-41e9-8be4-34bc70c27fbc')/SubmissionsWithLocation" />
          <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/RawSubmission" type="application/atom+xml;type=entry" title="RawSubmission" href="Responses(guid'fe3e57d8-96b1-41e9-8be4-34bc70c27fbc')/RawSubmission" />
          <category term="BLL.DAL.API.Response" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
          <content type="application/xml">
            <m:properties>
              <d:id m:type="Edm.Guid">fe3e57d8-96b1-41e9-8be4-34bc70c27fbc</d:id>
              <d:submission_id m:type="Edm.Guid">87c28027-9078-4512-ac4e-377cb319ace5</d:submission_id>
              <d:survey_id m:type="Edm.Int32">29350</d:survey_id>
              <d:name>respondent_name</d:name>
              <d:questiontype>Xform Text</d:questiontype>
              <d:responsevalue>John</d:responsevalue>
              <d:instance m:type="Edm.Int32">0</d:instance>
              <d:date m:type="Edm.DateTime">2020-10-09T16:17:02.137</d:date>
              <d:question_id m:type="Edm.Int32">1722119</d:question_id>
              <d:question_external_id>respondent_name</d:question_external_id>
              <d:comment m:null="true" />
            </m:properties>
          </content>
        </entry>
      </feed>
    </m:inline>
  </link>
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Survey" type="application/atom+xml;type=entry" title="Survey" href="Submissions(guid'87c28027-9078-4512-ac4e-377cb319ace5')/Survey" />
  <category term="BLL.DAL.API.Submission" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <content type="application/xml">
    <m:properties>
      <d:id m:type="Edm.Guid">87c28027-9078-4512-ac4e-377cb319ace5</d:id>
      <d:survey_id m:type="Edm.Int32">29350</d:survey_id>
      <d:uploaddate m:type="Edm.DateTime">2020-10-09T16:17:01.927</d:uploaddate>
      <d:surveystartdate m:type="Edm.DateTime">2020-10-09T16:17:13</d:surveystartdate>
      <d:surveyenddate m:type="Edm.DateTime">2020-10-09T16:17:20</d:surveyenddate>
      <d:language_id m:type="Edm.Int32">1</d:language_id>
      <d:fieldworker_id m:type="Edm.Guid">01ee8946-6b13-4886-b54a-72158e54318b</d:fieldworker_id>
      <d:uploadedby>Some User</d:uploadedby>
      <d:lastmodifiedby>Some User</d:lastmodifiedby>
      <d:lastmodifieddate m:type="Edm.DateTime">2020-10-09T16:17:01.927</d:lastmodifieddate>
      <d:IsIncomplete m:type="Edm.Boolean">false</d:IsIncomplete>
      <d:ReasonForIncompletion>Web collection in progress</d:ReasonForIncompletion>
    </m:properties>
  </content>
</entry>

The full list of Response properties are:


PropertyTypeDescription
idGUIDUnique identifier for the response.
submission_idGUIDUnique identifier of the corresponding submission.
survey_idIntegerUnique identifier of the corresponding survey (form).
nameString
User-defined name for the field configured during form design.
questiontypeStringDefines what type of field was used, e.g. "Xform Single One". See API lookup reference.
responsevalueStringStores the value captured. For media field types, this specifies the resource URL.
instanceIntegerIf the field was part of a repeat group, this property specifies which instance (iteration) the response corresponds to.
dateDate/TimeThis will be the date/time of when the response was uploaded. If the Response has since been modified, this will store the date/time of the last modification.
question_idIntegerUnique (system assigned) identifier of the field.
question_external_idStringUser-defined identifier assigned to the field. This can be configured in the API settings for the form.
commentStringIf the response has been modified, a comment can be stored. This property specifies the comment provided for the most recent modification.