Mobileforce API Design and Documentation
  • 05 Apr 2023
  • 5 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.

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

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

HTTP Header:

api_key: <api-key provided by Mobileforce Support>

:::(Info) (Note:)Dev/Stage/Production environment might have different API key.
:::
Note:

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).

HTTP POST Parameters

* 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 preformed 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.

# RESPONSE

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

Example ServiceTask object

Create action

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

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

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

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

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

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

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

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

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

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?