Mobileforce API Design and Documentation
  • 17 Jul 2023
  • 10 Minutes to read
  • Contributors
  • Dark
    Light

Mobileforce API Design and Documentation

  • Dark
    Light

Article Summary

This article describes the general structure of Mobileforce APIs including how to use the APIs. In addition, it also describes specific FSM (Field Service Management) APIs.

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. This key may be different
when using the stage and production versions of the MobileForce platform.

API Endpoints

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

The Mobileforce API is authenticated through the API key which is generated one time by a Mobileforce administrator. External applications should ensure that the API key is stored securely, and that all network connection should use secured internet protocols, https, for communication.

URI for supported API endpoints

InstanceAPI endpoint
Productionhttps://apps.mobileforcesoftware.com/adlwebui/service/mf_api.php
Stagehttps://apps.mobileforcesoftware.com/stage/adlwebui/service/mf_api.php

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 updated, you need to post data as multipart form-data(application/x-www-form-urlencoded).

Required HTTP Headers

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.

HTTP POST Parameters

The API endpoint must be invoked via a
HTTP POST
using one of the standard form encoding types.
The following encoding types are supported:

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

Use multipart/form-data if you need to upload a file. Otherwise, use application/x-www-form-urlencoded.

The following POST parameters are required for all API actions:

* object or table - This specifies the object name that need to be created, read, or updated. For e.g. ServiceTask, Account etc.
* action - This specifies the action that needs to be preformed on the object. Following are the action that are currently supported - create, read, update, delete, or list.

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.

API RESPONSE

All API responses will be JSON objects. 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.

Response will be HTTP 200 with JSON string.

Success response

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

On create/update action, the response will always have "id" field which corresponds to the newly created or updated object.

Failure response

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

Error Message info

ErrorDescription
Version <v2> not supportedCheck mf_api key header value
Invalid datatable responseInternal error. Please contact MF Support
Action <action> not supportedCheck the POST param "action". Only "create" and "update" actions are supported.
Invalid api_keyCheck the header API key
Object access deniedObject is not exposed to external world. Please contact MF Support.
Missing api_key headerCheek the POST http header.
Missing account or app parameterProblem with api_key. Please contact MF support

Create action

Request

The create action accepts the following POST parameters:

  • object: (required) The name of the MobileForce object to read or update.
  • action: (required) Must be create.
  • d_<field-name>: Value of the field to update in object. One can specify multiple
    fields by providing a d_<field-name> parameter for each field

Response

The response is a JSON object with the following parameters:

  • 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.
  • id: ID of the newly created object
    "d_name" should be unique value, otherwise API will return error response.

Example:

Request:

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=ServiceTask
d_name=Name
d_service_task_status_id=1
d_service_task_type_id=9
d_causale_c__c=CAUSALE DI CHIUSURA TICKET DA REINSTALLAZIONE
d_argomento__c=Abilitare alle carte di credito
d_work_order_id=<work_order_id>
d_termid_id__c=<Termid ID>
d_sugarcrm_account__c={"key":"140177","value":"TOT PER LA MUSICA"}
d_description=test description
d_note_apertura__c=
d_closing_notes=
d_data_scadenza__c=<yyyy-mm-dd>
d_office_id=13
d_street_address=924 Borregas Ave
d_city - Optional=Son Jose
d_state_or_province=CA
d_zip_or_postal_code=95059
d_country=United States of America
d_phone=3334445555
d_email=test@test.com
d_office_id=
d_service_estimated_hours=1
d_service_estimated_days=1
d_billable=1
d_service_amount_due=100
d_payment_date=
d_payment_type=
d_alfaticket__c=
d_data_ape__c=2022-01-01
d_ttdatult__c=2022-01-01
d_data_pianificazione__c=2022-01-01
d_reinvio_pianificazione__c=
d_note_task_piani__c=

Response

Content-Type: application/json

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

Update action

The update action updates one or more fields in the object with the given ID.

Request

  • object: (required) The name of the MobileForce object to read or update.
  • action: (required) Must be update.
  • id: (required) The ID of the object to update.
  • d_<field-name>: Value of the field to update in object. One can specify multiple
    fields by providing a d_<field-name> parameter for each field

Response

The response is a JSON object with the following parameters:

  • 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.
  • id: ID of the object
  • items: Array of fields and their values for the object. Each element will have the following fields:
    • name: Field name
    • label: Displayed label for the field.
    • value: Field value
      For update action "id" must be specified. Object with "id" will be updated accordingly.

Example

##### Request

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=update
object=ServiceTask
id=213074
d_name=Name
d_service_task_status_id=1
d_service_task_type_id=9
d_causale_c__c=CAUSALE DI CHIUSURA TICKET DA REINSTALLAZIONE
d_argomento__c=Abilitare alle carte di credito
d_work_order_id=<work_order_id>
d_termid_id__c=<Termid ID>
d_sugarcrm_account__c={"key":"140177","value":"TOT PER LA MUSICA"}
d_description=test description
d_note_apertura__c=
d_closing_notes=
d_data_scadenza__c=<yyyy-mm-dd>
d_office_id=13
d_street_address=924 Borregas Ave
d_city - Optional=Son Jose
d_state_or_province=CA
d_zip_or_postal_code=95059
d_country=United States of America
d_phone=3334445555
d_email=test@test.com
d_office_id=
d_service_estimated_hours=1
d_service_estimated_days=1
d_billable=1
d_service_amount_due=100
d_payment_date=
d_payment_type=
d_alfaticket__c=
d_data_ape__c=2022-01-01
d_ttdatult__c=2022-01-01
d_data_pianificazione__c=2022-01-01
d_reinvio_pianificazione__c=
d_note_task_piani__c=

Response

Content-Type: application/json

{
  "status": "success",
  "message": "",
  "id": 213074,
  "items" : [
    {"name":"name","label":"Name","value":"Test API11 update3"},
    {"name":"service_task_status_id","label":"Service Task Status","value":"4"},
    .....
    .....
   ]
}

Field details

  • d_name - Required and it should be unique
  • d_service_task_type_id - Required. Expected values : 1 - Aperto, 2 - Pianificato, 3 - In consegna, 4 - Chiuso, 5 - Annullato, 9 - Chiuso da eliminare, 10 - Chiuso KO, 11 - Consegnato
  • d_service_task_type_id - Required. Expected values : 9 - Installazione, 10 - Manutenzione ordinaria, 11 - Manutenzione straordinaria, 12 - Ritiro terminali, 13 - Argentea, 14 - Flex, 15 - Autoconfigurazione
  • d_causale_c__c - CAUSALE DI CHIUSURA TICKET DA REINSTALLAZIONE, MANUTENZIONE ORDINARIA|MANUTENZIONE ORDINARIA etc.
  • d_argomento__c - Abilitare alle carte di credito,Aggiornamento Chiavi CB2 etc.
  • d_work_order_id - Work order ID
  • d_termid_id__c - Teamid ID
  • d_sugarcrm_account__c - JSON dictionary string with key and value. For eg. {"key":"140177","value":"TOT PER LA MUSICA"}
  • d_description - Optional field. Max 1000 characters
  • d_note_apertura__c - Optional field. Max 255 characters
  • d_closing_notes - Optional field. Max 1000 characters
  • d_data_scadenza__c - date ISO 8601 format
  • d_street_address - - Optional field. Max 255 characters
  • d_city - Optional - Max 255 characters
  • d_state_or_province - State
  • d_zip_or_postal_code - Postal Code
  • d_country - United States of America. Expected values: ´United States of America, Australia...etc
  • d_phone - Phone number
  • d_email - Email
  • d_office_id - Office Id
  • d_service_estimated_hours - Hours
  • d_service_estimated_days - Days
  • d_billable - 0/1
  • d_service_amount_due - Amount due
  • d_payment_date - <yyyy-mm-dd>
  • d_payment_type - Free form text. Max 100 characters.
  • d_alfaticket__c - Free form text. Max 255 characters
  • d_data_ape__c - <yyyy-mm-dd>
  • d_ttdatult__c - <yyyy-mm-dd>
  • d_data_pianificazione__c - <yyyy-mm-dd>
  • d_reinvio_pianificazione__c - Number format
  • d_note_task_piani__c - Free form text. Max 255 characters

Delete action

The delete action deleted the object with the given ID.

Request

  • object: (required) The name of the MobileForce object to read or update.
  • action: (required) Must be delete.
  • id: (required) The ID of the object to delete.

Response

The response is a JSON object with the following parameters:

  • 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.
  • id: ID of the deleted object.
    For delete action "id" must be specified. Object with "id" will be deleted accordingly.

Example

Request

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=delete
object=ServiceTask
id=213074

Response

Content-Type: application/json

{
  "status": "success",
  "message": "Record deleted successfully",
  "id": 213074,
  "items" : []
}

Read action

The read action reads the object with the given ID.

Request

  • object: (required) The name of the MobileForce object to read or update.
  • action: (required) Must be read.
  • id: (required) The ID of the object to read.

Response

The response is a JSON object with the following parameters:

  • 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.
  • id: ID of the object
  • items: Array of fields and their values for the object. Each element will have the following fields:
    • name: Field name
    • label: Displayed label for the field.
    • value: Field value

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

Example

Request

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=read
object=ServiceTask
id=213074

Response

Content-Type: application/json

{
  "status": "success",
  "message": "Record deleted successfully",
  "id": 213074,
  "items" : [
    {"name":"name","label":"Name","value":"Test API11 update3"},
    {"name":"service_task_status_id","label":"Service Task Status","value":"4"},
    .....
    .....
   ]
}

Search/list action

The list action is used to read one more objects in a table.

Only a subset of all the fields of an object is fetched. If you need to fetch a field
not in this subset, include it in the additionalcolumns parameter.

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

Request

  • object: (required) The name of the MobileForce object to read or update.
  • action: (required) Must be list.
  • search: Expression to search by. This expression uses SQL WHERE condition syntax. Example search expressions are owner_id = 123 or name LIKE '%john%' AND is_lead = 1.
  • additionalcolumns: Comma-separated list of additional columns to read.
  • offset: Offset of first object to fetch. If not specified, it defaults to 0, the first object in the results.)
  • length: Number of objects to fetch. If not specified, only at most 10 objects are fetched.

Response

The response is a JSON object with the following parameters:

  • 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.
  • items: Array of objects that were fetched.

Each object in the list of objects will have the following fields:

  • id: ID of the object
  • label: Displayed name of the object. Usually the name field in the object.
  • icon: (deprecated) No longer used.
  • link: Mobileforce UI link for object. Will not work outside of a MobileForce UI. Do not use.
  • info: Array of fields and their values for the object. Each element will have the following fields:
    • name: Field name
    • label: Displayed label for the field.
    • value: Field value
    • valueType: Field's type.
    • numLines: (deprecated) No longer used.

Example

Request

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=list
object=ServiceTask
offset=0
length=10
search=name like '%test%'

Response

Content-Type: application/json

{
  "status": "success",
  "message": "",
  "items": [
    {
      "label": "Test API111",
      "id": "213119",
      "icon": "",
      "link": "datatableformscreen.php?path=Home%3Beasyclm-ServiceTask&action=read&table=ServiceTask&s=eJxLrEgtKkutyc1PysxJTcsvSk6tMQQCAzMTMxMLo5pI1-CamhqDGkM9Az0DEKPGK6_Y19DJ0SUivDIDAJ8BFNc&layouttype=&id=213119",
      "info": [
        {
          "name": "name",
          "label": "Nome",
          "value": "Test API111",
          "valueType": "text",
          "numLines": 1
        },
        {
          "name": "service_task_status_id",
          "label": "Stato",
          "value": "Chiuso",
          "valueType": "text",
          "numLines": 1
        },
    
    ....
    ....
    }
   ]
}

Curl examples

Create action

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

Update action

curl -X POST \
-H 'api_key: $mf3$AwEfE5I0gCL7YalrOoqZrVc1Swwo038n+me2Vt3lNExI5CGBDXhvLvfiLkRTvLeq3QHG5aR89Mctw4mAsDSTZEZhwdBSBVCtHJ7+ao/OfnIPfGXLGKFKrx92gzeYErCGbMPP/bj083/+39cFyDL4ghkNwetJt0WoNnxKQsv0cbtA8w==' \
-F 'action=create' \
-F 'object=ServiceTask' \
-F 'id=213112' \
-F 'd_name=Test API11 update3' \
-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

Delete action

curl -X POST \
-H 'api_key: $mf3$AwEfE5I0gCL7YalrOoqZrVc1Swwo038n+me2Vt3lNExI5CGBDXhvLvfiLkRTvLeq3QHG5aR89Mctw4mAsDSTZEZhwdBSBVCtHJ7+ao/OfnIPfGXLGKFKrx92gzeYErCGbMPP/bj083/+39cFyDL4ghkNwetJt0WoNnxKQsv0cbtA8w==' \
-F 'action=delete' \
-F 'object=ServiceTask' \
-F 'id=213112' \
https://apps01.mobileforcesoftware.com/prabu/adlwebui/service/mf_api.php

List/Search action

curl -X POST \
-H 'api_key: $mf3$AwEfE5I0gCL7YalrOoqZrVc1Swwo038n+me2Vt3lNExI5CGBDXhvLvfiLkRTvLeq3QHG5aR89Mctw4mAsDSTZEZhwdBSBVCtHJ7+ao/OfnIPfGXLGKFKrx92gzeYErCGbMPP/bj083/+39cFyDL4ghkNwetJt0WoNnxKQsv0cbtA8w==' \
-F 'action=list' \
-F 'object=ServiceTask' \
-F "search=id='213119'" \
-F 'offset=0' \
-F 'length=1' \
https://apps01.mobileforcesoftware.com/prabu/adlwebui/service/mf_api.php
Note:

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.
For more information about Mobileforce APIs, please contact Mobileforce Support.


Was this article helpful?