Mobileforce API Design and Documentation

Updated

• Updated on Jan 7, 2025
• Published on Sep 2, 2022
• 9 minute(s) read
• TL
• MS
• RS

MobileForce API V2 Documentation

This version (V2) supersedes the previous versions of Mobileforce API.

Mobileforce API Structure

Mobileforce API can be used by external applications to list, search, create, read, update or delete Mobileforce specific objects such as Service Tasks, Work Orders, Appointments, etc. and Form submissions. With Mobileforce APIs, you can create, read, update, and delete individual objects in the table, as well as fetch multiple objects in a table.

Calling the API

API Key

To use the MobileForce API, you need an API key. This key is specific to your account and will be provided to you by MobileForce support.

The Mobileforce API is authenticated thru an API key which is generated onetime by MobileForce administrator. External applications should make sure that the API key is securely stored and all network connection should use the secure http ( "https" ) protocol.

API Endpoints

The Mobileforce API key may be different for different API Endpoints such as the stage and production versions of the MobileForce platform, so be sure to use the correct key, for the appropriate version.

All MobileForce API calls are made via a HTTPS POST to a single API endpoint. The endpoint API can vary based on your geographic region and whether you are using the production or staging version of MobileForce platform.

URI

HTTP Header:

The API endpoint requires these HTTP headers:

• Content-Type: The content encoding type. Should be application/x-www-form-urlencoded or multipart/form-data.
• api_key: API key provided by MobileForce support.

Note: dev/stage/production environment might have different API key.

HTTP Method

POST - You should use POST HTTP method for all the API calls using form-data method (key value pair for each field). If files need to be updated, you need to post data as multipart form-data (application/x-www-form-urlencoded).

The API endpoint must be invoked via a HTTP POST using one of the standard form encoding types: form-data method (key value pair for each field).

If files need to be updated, you need to post data as multipart form-data (application/x-www-form-urlencoded).

The following encoding types are supported:

• application/x-www-form-urlencoded
• multipart/form-data

HTTP POST params

The following POST parameters are required for all API actions:

* table - This specifies the object name that need to be created. For e.g. ServiceTask, Account etc.

* action - This specifies the action that needs to be performed on the object. Following are the action that are currently supported - create and update.

* d_ - All the fields starting with prefix "d_" should be present in object property spec.

Additional POST parameters may be required or accepted based on the action type.

Passing in object fields

The create and update actions require passing object fields to the server.

This is done by passing in POST parameters whose names are of the form d_<field-name>, where <field-name> is the name of the field.

For example, to update the name field of an object, you must set the POST parameter d_name.

* d_ - All the fields starting with prefix "d_" should be present in object property spec.

RESPONSE

Response will be HTTP 200 with JSON string.

This JSON object will have the following fields:

• status: The status of the response. May be success or failure.
• message: The status message. If the action failed, this will contain the failure message.

Success response

Code snippet

{
    "status" : "success",
    "message" : "Update success",
    "id" : "id"
}

Failure response

Code snippet

{
    "status" : "failure",
    "message" : "Invalid api_key"
}

Error Message info

Mobileforce APIs can be invoked programmatically via CURL calls from any language that supports making CURL calls. This is the recommended method since it lets you compose Mobileforce APIs with other elements of your UI and backend interaction to create powerful composable UIs, in addition to better performance.

Example 1: Invoking Mobileforce CPQ APIs via POSTMAN

Since the Mobileforce CPQ application often is embedded within a CRM User Interface (UI), invoking Mobileforce CPQ often involves passing data between the CRM and Mobileforce. Mobileforce supports almost all modern CRMs, thus enabling easy migration from one CRM to another, without having to also change your CPQ or other RevOps applications.

In order to invoke Mobileforce CPQ APIs, one needs the API_KEY which can be obtained by contacting Mobileforce Support

The example below shows using HubSpot, for which an OAuth token is also needed (in order to programmatically access HubSpot via API calls). HubSpot recommends a private app access token, which can be easily obtained by (a) creating a private app within your HubSpot Instance via the navigation: Settings --> Integrations --> Private Apps.

Headers

Params

Note the URL (https://apps.mobileforcesoftware.com/adlwebui/service/mf_api.php) and that the call is a POST. Finally, note that no params are needed.

Authorization

Note that the Authorization is of Auth Type "Bearer Token", where the token itself is the HubSpot Access Token for the "private" app created above.

Body

If these parameters are correctly specified, once you click "Send" in the Postman interface, you would get a JSON response from a successful API call.

Example 2: ServiceTask object

Create action

"d_name" should be unique value, otherwise API will return error response.

Code snippet

POST https://apps01.mobileforcesoftware.com/prabu/adlwebui/service/mf_api.php HTTP/1.1
Content-Type: application/x-www-form-urlencoded
api_key: $mf3$AwGOfDJYhfFjN3RVlF+rlR1dCe7f3JvmqZwv3

POST DATA
-----------------------------------
action=create
object=User
d_name=mobileforcedemo1@gmail.com
d_email=MobileForceDemo
d_role=18
d_parent_id=1
d_street_address=3733 Jasmine cir
d_city=San Jose
d_state_or_province=CA
d_zip_or_postal_code=95135
d_mobile_phone=3334445555

Update action

For update action "id" must be specified. Object with "id" will be updated accordingly.

Code snippet

POST https://apps01.mobileforcesoftware.com/prabu/adlwebui/service/mf_api.php HTTP/1.1
Content-Type: application/x-www-form-urlencoded
api_key: $mf3$AwGQ6eEWoqPu0zQKU+zGNV8EgdcBT+a9aLZDs9XS1pZIk47a3TMlEpLkyKnyBlXbYOiP2N4VaUOD5YH+lRtZk0yggRXrxCzQYiGigxw03unLavi6tCR/DQ+szsdVGxsUIqvyT2CSSDnCm7wJGBt14G7af0P7tbZTMB9RbOTKMWloLeDthEtOLJgePtd5UY365uk=

POST DATA
action=update
object=User
id=70
d_id=70
d_name=Prabu test 7
d_email=mobileforcedemo1@gmail.com
d_employer=MobileForce
d_role_id=18
d_parent_id=1
d_street_address=3733 Jasmine cir
d_city=San Jose
d_state_or_province=CA
d_zip_or_postal_code=95135
d_mobile_phone=3334445555

Delete action

For delete action "id" must be specified. Object with "id" will be deleted accordingly.

Code snippet

POST DATA action=delete object=User id=70 d_id=70

### Read action

For read action "id" must be specified. Object with "id" will be read accordingly.

Code snippet

POST DATA
action=read
object=User
id=61

Search/list action

Default value for "length" is 10. You specify SQL like search string.

Code snippet

POST DATA

action=list object=Users offset=0 length=10 search=name like '%test%'

## Response

Code snippet

```text
Content-Type: application/json

{
  "status": "success",
  "message": null,
  "items": [
    {
      "id": "1",
      "name": "MobileForce Support",
      "email": support@mobileforcesoftware.com,
      "role_id": {"key":"1","value":"MobileForce Admin"},
      "parent_id": null,
      "employer": "MobileForce Software",
      "employeeid": null,
      "designation": null,
      "department": null,
      "is_user_contractor": "No",
      "subcontractor_id": null,
      "mobile_phone": "6695551212",
      "street_address": "924 Borregas Ave",
      "city": "Sunnyvale",
      "state_or_province": "CA",
      "zip_or_postal_code": "94089",
      "country": "United States of America",
      "available_on_call": "No",
      "is_sick": "No",
      "sick_start_date_time": null,
      "sick_end_date_time": null,
      "is_on_vacation": "No",
      "vacation_start_date_time": null,
      "vacation_end_date_time": null,
      "is_on_freeze": "No",
      "freeze_start_date_time": null,
      "freeze_end_date_time": null,
      "is_user_active": "Yes",
      "login": "loginEnabled",
      "created_date": "2019-01-01 00:00:00",
      "modified_date": "2019-01-01 00:00:00"
    },
    ...
  ],
  "rowcount": "50"
}

Example 3: Invoking Mobileforce API via CURL

Create action

Code snippet

curl -X POST \
-H 'api_key: $mf3$AwEfE5I0gCL7YalrOoqZrVc1Swwo038n+me2Vt3lNExI5CGBDXhvLvfiLkRTvLeq3QHG5aR89Mctw4mAsDSTZEZhwdBSBVCtHJ7+ao/OfnIPfGXLGKFKrx92gzeYErCGbMPP/bj083/+39cFyDL4ghkNwetJt0WoNnxKQsv0cbtA8w==' \
-F 'action=create' \
-F 'object=ServiceTask' \
-F 'd_name=Test API111' \
-F 'd_service_task_status_id=4' \
-F 'd_service_task_type_id=9' \
-F 'd_email=test@test.com' \
-F 'd_description=test description' \
-F 'd_office_id=13' \
-F 'd_sugarcrm_account__c={"key":"140177","value":"TOT PER LA MUSICA"}' \
-F 'd_skill_ids=1,2' \
-F 'd_data_ape__c=2022-01-01 21:59:59' \
-F 'd_ttdatult__c=2022-01-01' \
https://apps01.mobileforcesoftware.com/prabu/adlwebui/service/mf_api.php

List action (All)

Code snippet

curl -X POST \
-H 'api_key: $mf3$AwGQ6eEWoqPu0zQKU+zGNV8EgdcBT+a9aLZDs9XS1pZIk47a3TMlEpLkyKnyBlXbYOiP2N4VaUOD5YH+lRtZk0yggRXrxCzQYiGigxw03unLavi6tCR/DQ+szsdVGxsUIqvyT2CSSDnCm7wJGBt14G7af0P7tbZTMB9RbOTKMWloLeDthEtOLJgePtd5UY365uk=' \
-F 'action=list' \
-F 'object=User' \
-F 'offset=0' \
-F 'length=5' \
https://apps01.mobileforcesoftware.com/prabu/adlwebui/service/mf_api.php

MF API Generation

To generate the mf-api-key run the following command.

Code snippet

$ cd /ebs/www/html/stage/adlwebui/tools
$ php -f mf_api_generator_v2.php <account> <app> <tph>

ADL configuration

Code snippet

    <prop key="mf-api-key-11110646482">$mf3$AwEfE5I0gCL7YalrOoqZrVc1Swwo038n+me2Vt3lNExI5CGBDXhvLvfiLkRTvLeq3QHG5aR89Mctw4mAsDSTZEZhwdBSBVCtHJ7+ao/OfnIPfGXLGKFKrx92gzeYErCGbMPP/bj083/+39cFyDL4ghkNwetJt0WoNnxKQsv0cbtA8w==</prop>
    <prop key="mf-api-tables">{"ServiceTask" : "Home;easyclm-ServiceTask", ".*" : "Home;easyclm-ServiceTask"}</prop>

• mf-api-key- - Update with key that got generated by running mf_api_generator.php
• mf-api-tables - JSON dictionary. Whitelist all the table with respective screen ID. It supports regex expression also.

Mobileforce APIs are intended for use only by registered customers and partners who have obtained licenses to use Mobileforce FSM and CPQ as well as the Mobileforce platform. Mobileforce trial users do not have access to Mobileforce APIs.

Mobileforce CPQ APIs

Mobileforce CPQ APIs are derived from the Mobileforce APIs and inherit the same structure. Further Details about the Mobileforce CPQ API Structure can be found here