Managing devices, fieldworkers and form assignments via the API : Help Center

The Mobenzi API allows you to:

Manage your field team by listing, adding, updating and deleting fieldworkers. You must authenticate with the credentials of a user who has "Manage all team members" permission.
Manage your devices by adding, updating, deleting and assigning/unassigning handsets. You must authenticate with the credentials of a user who has "Manage all handsets" permission.
Manage the forms that are assigned to a fieldworker. You must authenticate with the credentials of a user who has "Manage who can collect data" permission for the relevant project.

Retrieving Fieldworkers and Devices

The Mobenzi API allows you to programatically query and retrieve fieldworkers and devices. 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).

To retrieve a list of Fieldworker entities via the API, you would query the Fieldworkers API service: https://console.mobenzi.com/secure/api.svc/Fieldworkers.

To retrieve a specific Fieldworker, you can use the Fieldworker's unique identifier as follows: https://console.mobenzi.com/secure/api.svc/Fieldworkers(guid'<fieldworker_id>').

To retrieve a list of Device entities (handsets) via the API, you would query the Devices API service: https://console.mobenzi.com/secure/api.svc/Devices.

To retrieve a specific Device, you can use the Device's unique identifier as follows: https://console.mobenzi.com/secure/api.svc/Devices(guid'<device_id>'). This would return something like:

<?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/Devices(guid'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')</id>
  <title type="text"></title>
  <updated>2020-10-13T17:07:53Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="Device" href="Devices(guid'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/DeviceSurveyRelationships" type="application/atom+xml;type=feed" title="DeviceSurveyRelationships" href="Devices(guid'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')/DeviceSurveyRelationships" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Model" type="application/atom+xml;type=entry" title="Model" href="Devices(guid'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')/Model" />
  <category term="BLL.DAL.API.Device" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <content type="application/xml">
    <m:properties>
      <d:id m:type="Edm.Guid">xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</d:id>
      <d:mobilenumber></d:mobilenumber>
      <d:imei>xxxxxxxxxxxxxxx</d:imei>
      <d:assetcode>Example Code</d:assetcode>
      <d:model_id m:type="Edm.Int32">13355</d:model_id>
      <d:prepaid m:type="Edm.Boolean">false</d:prepaid>
      <d:userid m:type="Edm.Guid">xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</d:userid>
      <d:createdon m:type="Edm.DateTime">2019-10-17T10:51:17.793</d:createdon>
      <d:lastmodifiedon m:type="Edm.DateTime">2019-10-28T14:39:05.84</d:lastmodifiedon>
      <d:createdby>System</d:createdby>
      <d:lastmodifiedby>System</d:lastmodifiedby>
      <d:assignable m:type="Edm.Boolean">true</d:assignable>
      <d:enabled m:type="Edm.Boolean">true</d:enabled>
    </m:properties>
  </content>
</entry>

Adding a Fieldworker

To add a Fieldworker to your account, you would issue an HTTP POST request to the https://console.mobenzi.com/secure/api.svc/AddFieldworker endpoint. The following POST parameters are available:

firstName [Required] - Fieldworker's first name
middleName [Optional] - Fieldworker's middle name
lastName [Required] - Fieldworker's last name
studyId [Optional] - An integer identifying the study (project) that the new Fieldworker should be given access to. If not specified, the Fieldworker will not have access to any forms until they are explicitly given permission to a project.

// Common node package includes
const axios = require("axios"); //axios is a common HTTP client for the browser and node.js
const FormData = require('form-data'); // formdata is available in the browser by default or from NPM at https://www.npmjs.com/package/formdata-node

// Specify the credentials of the user who will be making the API requests.
// Note: the user must have "Design Survey" permission to the relevant project.
var config = {
    auth : {
        username: 'api@yourdomain.com',
        password: 'apiuserpassword'
    }
};

// Prepare your request data
var url = "https://console.mobenzi.com/secure/api.svc/AddFieldworker"; 
let formData = new FormData();
formData.append("firstName", "<FIRST_NAME>");
formData.append("middleName", "<MIDDLE_NAME>");
formData.append("lastName", "<LAST_NAME>"); 
formData.append("studyId", "<STUDY_ID>"); 
config.headers = formData.getHeaders();

// Use axios to issue the HTTP request (note: your code should add error checking on the response and handle appropriately.
axios.post(url, formData, config).then(result => {
    var fieldworkerId = result.data.d.AddFieldworker;
    console.log(fieldworkerId);
}).catch(error => {
    console.log(error);
});

Editing a Fieldworker

To edit a Fieldworker, you would issue an HTTP POST request to the https://console.mobenzi.com/secure/api.svc/EditFieldworker endpoint. The following POST parameters are available:

userId [Required] - The identifier (GUID) of the Fieldworker you wish to modify
firstName [Required] - Fieldworker's first name
middleName [Optional] - Fieldworker's middle name
lastName [Required] - Fieldworker's last name

// Common node package includes
const axios = require("axios"); //axios is a common HTTP client for the browser and node.js
const FormData = require('form-data'); // formdata is available in the browser by default or from NPM at https://www.npmjs.com/package/formdata-node

// Specify the credentials of the user who will be making the API requests.
// Note: the user must have "Design Survey" permission to the relevant project.
var config = {
    auth : {
        username: 'api@yourdomain.com',
        password: 'apiuserpassword'
    }
};

// Prepare your request data
var url = "https://console.mobenzi.com/secure/api.svc/EditFieldworker"; 
let formData = new FormData();
formData.append("userId", "<USER_ID>"); 
formData.append("firstName", "<FIRST_NAME>");
formData.append("middleName", "<MIDDLE_NAME>");
formData.append("lastName", "<LAST_NAME>"); 
config.headers = formData.getHeaders();

// Use axios to issue the HTTP request (note: your code should add error checking on the response and handle appropriately.
axios.post(url, formData, config).then(result => {
    console.log(result.data);
}).catch(error => {
    console.log(error);
});

Adding a Device

To add a Device to your account, you would issue an HTTP POST request to the https://console.mobenzi.com/secure/api.svc/AddDevice endpoint. The following POST parameters are available:

identifier [Required] - The unique manufacturer IMEI or Android Id of the device
assetCode [Optional] - A custom string to help you identify the device in the console
mobileNumber [Optional] - An internationally formatted mobile number
fieldworkerId [Optional] - A fieldworker to assign the device to. If you do not set this to a fieldworker in the account, the device will be "unassigned".

// Common node package includes
const axios = require("axios"); //axios is a common HTTP client for the browser and node.js
const FormData = require('form-data'); // formdata is available in the browser by default or from NPM at https://www.npmjs.com/package/formdata-node

// Specify the credentials of the user who will be making the API requests.
// Note: the user must have "Design Survey" permission to the relevant project.
var config = {
    auth : {
        username: 'api@yourdomain.com',
        password: 'apiuserpassword'
    }
};

// Prepare your request data
var url = "https://console.mobenzi.com/secure/api.svc/AddDevice"; 
let formData = new FormData();
formData.append("identifier", "<IMEI_OR_ANDROIDID>"); 
formData.append("assetCode", "<ASSET_CODE>");
formData.append("mobileNumber", "<MOBILE_NUMBER>");
formData.append("fieldworkerId", "<FIELDWORKER_ID>"); 
config.headers = formData.getHeaders();

// Use axios to issue the HTTP request (note: your code should add error checking on the response and handle appropriately.
axios.post(url, formData, config).then(result => {
    let fieldworkerId = result.data.d.AddDevice;
    console.log(fieldworkerId);
}).catch(error => {
    console.log(error);
});

Editing a Device

To edit a Device, you would issue an HTTP POST request to the https://console.mobenzi.com/secure/api.svc/EditDevice endpoint. The following POST parameters are available:

deviceId [Required] - The identifier (GUID) of the Device you wish to modify
identifier [Required] - The manufacturer IMEI or Android Id of the device
assetCode [Optional] - A custom string to help you identify the device in the console
mobileNumber [Optional] - An internationally formatted mobile number
fieldworkerId [Optional] - A fieldworker to assign the device to
enabled [Required] - A boolean flag (true/false) indicating whether the device is currently enabled or not

// Common node package includes
const axios = require("axios"); //axios is a common HTTP client for the browser and node.js
const FormData = require('form-data'); // formdata is available in the browser by default or from NPM at https://www.npmjs.com/package/formdata-node

// Specify the credentials of the user who will be making the API requests.
// Note: the user must have "Design Survey" permission to the relevant project.
var config = {
    auth : {
        username: 'api@yourdomain.com',
        password: 'apiuserpassword'
    }
};

// Prepare your request data
var url = "https://console.mobenzi.com/secure/api.svc/EditDevice"; 
let formData = new FormData();
formData.append("deviceId", "<DEVICE_ID>"); 
formData.append("identifier", "<IMEI_OR_ANDROIDID>"); 
formData.append("assetCode", "<ASSET_CODE>");
formData.append("mobileNumber", "<MOBILE_NUMBER>");
formData.append("fieldworkerId", "<FIELDWORKER_ID>"); 
formData.append("enabled", "<TRUE_OR_FALSE>"); 
config.headers = formData.getHeaders();

// Use axios to issue the HTTP request (note: your code should add error checking on the response and handle appropriately.
axios.post(url, formData, config).then(result => {
    console.log(result.data);
}).catch(error => {
    console.log(error);
});

Assigning a Fieldworker to a Survey

To assign a Fieldworker to a Survey (form), you would issue an HTTP POST request to the https://console.mobenzi.com/secure/api.svc/AssignFieldworkerToSurvey endpoint. The following POST parameters are available:

userId [Required] - The identifier (GUID) of the Fieldworker you wish to assign the survey to
surveyId [Required] - The identifier (integer) of the Survey (form) you wish to assign

// Common node package includes
const axios = require("axios"); //axios is a common HTTP client for the browser and node.js
const FormData = require('form-data'); // formdata is available in the browser by default or from NPM at https://www.npmjs.com/package/formdata-node

// Specify the credentials of the user who will be making the API requests.
// Note: the user must have "Design Survey" permission to the relevant project.
var config = {
    auth : {
        username: 'api@yourdomain.com',
        password: 'apiuserpassword'
    }
};

// Prepare your request data
var url = "https://console.mobenzi.com/secure/api.svc/AssignFieldworkerToSurvey"; 
let formData = new FormData();
formData.append("userId", "<FIELDWORKER_ID>"); 
formData.append("surveyId", "<FORM_ID>"); 
config.headers = formData.getHeaders();

// Use axios to issue the HTTP request (note: your code should add error checking on the response and handle appropriately.
axios.post(url, formData, config).then(result => {
    console.log(result.data);
}).catch(error => {
    console.log(error);
});

Unassigning a Fieldworker from a Survey

To unassign a Fieldworker to a Survey (form), you would issue an HTTP POST request to the https://console.mobenzi.com/secure/api.svc/UnassignFieldworkerFromSurvey endpoint. The following POST parameters are available:

userId [Required] - The identifier (GUID) of the Fieldworker you wish to unassign the survey from
surveyId [Required] - The identifier (integer) of the Survey (form) you wish to unassign

// Common node package includes
const axios = require("axios"); //axios is a common HTTP client for the browser and node.js
const FormData = require('form-data'); // formdata is available in the browser by default or from NPM at https://www.npmjs.com/package/formdata-node

// Specify the credentials of the user who will be making the API requests.
// Note: the user must have "Design Survey" permission to the relevant project.
var config = {
    auth : {
        username: 'api@yourdomain.com',
        password: 'apiuserpassword'
    }
};

// Prepare your request data
var url = "https://console.mobenzi.com/secure/api.svc/UnassignFieldworkerFromSurvey"; 
let formData = new FormData();
formData.append("userId", "<FIELDWORKER_ID>"); 
formData.append("surveyId", "<FORM_ID>"); 
config.headers = formData.getHeaders();

// Use axios to issue the HTTP request (note: your code should add error checking on the response and handle appropriately.
axios.post(url, formData, config).then(result => {
    console.log(result.data);
}).catch(error => {
    console.log(error);
});

Help Center

How can we help you today?

Managing devices, fieldworkers and form assignments via the API Print

Retrieving Fieldworkers and Devices

Adding a Fieldworker

Editing a Fieldworker

Adding a Device

Editing a Device

Assigning a Fieldworker to a Survey

Unassigning a Fieldworker from a Survey

How can we help you today?

Managing devices, fieldworkers and form assignments via the API Print

Retrieving Fieldworkers and Devices

Adding a Fieldworker

Editing a Fieldworker

Adding a Device

Editing a Device

Assigning a Fieldworker to a Survey

Unassigning a Fieldworker from a Survey

Related Articles