View on GitHub

Vtiger-mobile-client-ios

A client sample app for vTigerCRM Mobile API written in Objective-C, built for iOS

Download this project as a .zip file Download this project as a tar.gz file

vTiger Mobile API

Please note: this documents refers to the Mobile API of vTiger CRM, not the webservice, which is available at http://crm-base-url/webservice.php and whose operations are described at the official vTiger Wiki page, as well as on published books.

Endpoint

http://localhost:8888/vtigercrm520/modules/Mobile/api.php

All operations are POST requests.

File Structure

How modules work

Modules follow the following rules:

Operations

Dump of operations from php files

Details of Operations

NOTE: Looks like all operations support more parameters than the ones that are needed. Parameters such as action, file and search can be left out and what happens is that php.log will display Notice-level errors. Depending on the php.ini configuration, this can clutter the log file.

Operations described in this document:

login

Params:

Name Value
_operation login
username username
password password

Response:

{
"success": true,
"result": {
    "login": {
        "userid": "1",
        "session": "fa000f0a6c5a414e62dcc4cbf99175d6",
        "vtiger_version": "5.2.0",
        "mobile_module_version": "1.2.1"
    }
}
}

loginAndFetchModules

It’s used by the mobile web client to display a list of modules to the user after the login is successful. It’s also useful to check if a module is enabled or not.

Params:

Name Value
_operation login
username username
password password

Response:

{
"success": true,
"result": {
    "login": {
        "userid": "1",
        "session": "fa000f0a6c5a414e62dcc4cbf99175d6",
        "vtiger_version": "5.2.0",
        "mobile_module_version": "1.2.1"
    },
    "modules": [
        {
            "id": "1",
            "name": "Calendar",
            "isEntity": true,
            "label": "Calendar",
            "singular": "To Do"
        },
        {
            "id": "2",
            "name": "Leads",
            "isEntity": true,
            "label": "Leads",
            "singular": "Lead"
        },
        {
            "id": "3",
            "name": "Accounts",
            "isEntity": true,
            "label": "Accounts",
            "singular": "Account"
        },
        {
            "id": "4",
            "name": "Contacts",
            "isEntity": true,
            "label": "Contacts",
            "singular": "Contact"
        },
        {
            "id": "5",
            "name": "Potentials",
            "isEntity": true,
            "label": "Potentials",
            "singular": "Potential"
        },
        {
            "id": "6",
            "name": "Products",
            "isEntity": true,
            "label": "Products",
            "singular": "Product"
        },
        {
            "id": "7",
            "name": "Documents",
            "isEntity": true,
            "label": "Documents",
            "singular": "Document"
        },
        {
            "id": "8",
            "name": "Emails",
            "isEntity": true,
            "label": "Email",
            "singular": "Email"
        },
        {
            "id": "9",
            "name": "HelpDesk",
            "isEntity": true,
            "label": "Trouble Tickets",
            "singular": "Ticket"
        },
        {
            "id": "10",
            "name": "Faq",
            "isEntity": true,
            "label": "FAQ",
            "singular": "Faq"
        },
        {
            "id": "11",
            "name": "Vendors",
            "isEntity": true,
            "label": "Vendors",
            "singular": "Vendor"
        },
        {
            "id": "12",
            "name": "PriceBooks",
            "isEntity": true,
            "label": "Price Books",
            "singular": "PriceBook"
        },
        {
            "id": "13",
            "name": "Quotes",
            "isEntity": true,
            "label": "Quotes",
            "singular": "Quote"
        },
        {
            "id": "14",
            "name": "PurchaseOrder",
            "isEntity": true,
            "label": "Purchase Order",
            "singular": "PurchaseOrder"
        },
        {
            "id": "15",
            "name": "SalesOrder",
            "isEntity": true,
            "label": "Sales Order",
            "singular": "SalesOrder"
        },
        {
            "id": "16",
            "name": "Invoice",
            "isEntity": true,
            "label": "Invoice",
            "singular": "Invoice"
        },
        {
            "id": "17",
            "name": "Campaigns",
            "isEntity": true,
            "label": "Campaigns",
            "singular": "Campaign"
        },
        {
            "id": "23",
            "name": "PBXManager",
            "isEntity": true,
            "label": "PBX Manager",
            "singular": "SINGLE_PBXManager"
        },
        {
            "id": "24",
            "name": "ServiceContracts",
            "isEntity": true,
            "label": "Service Contracts",
            "singular": "Service Contract"
        },
        {
            "id": "25",
            "name": "Services",
            "isEntity": true,
            "label": "Services",
            "singular": "Service"
        },
        {
            "id": "26",
            "name": "Assets",
            "isEntity": true,
            "label": "Assets",
            "singular": "Asset"
        },
        {
            "id": "27",
            "name": "ModComments",
            "isEntity": true,
            "label": "Comments",
            "singular": "Comment"
        },
        {
            "id": "28",
            "name": "ProjectMilestone",
            "isEntity": true,
            "label": "Project Milestones",
            "singular": "Project Milestone"
        },
        {
            "id": "29",
            "name": "ProjectTask",
            "isEntity": true,
            "label": "Project Tasks",
            "singular": "Project Task"
        },
        {
            "id": "30",
            "name": "Project",
            "isEntity": true,
            "label": "Projects",
            "singular": "Project"
        },
        {
            "id": "31",
            "name": "SMSNotifier",
            "isEntity": true,
            "label": "SMSNotifier",
            "singular": "SMS Info"
        }
    ]
}
}

describe

Describe queries the API for a specified module and returns its configuration.

Custom fields are returned.

Parameters:

Name Value
_operation describe
_session session (from Login)
module Module

Allowed values for module:

Example of return result:

{
"success": true,
"result": {
    "describe": {
        "label": "Calendar",
        "name": "Calendar",
        "createable": true,
        "updateable": true,
        "deleteable": true,
        "retrieveable": true,
        "fields": [
            {
                "name": "subject",
                "label": "Subject",
                "mandatory": true,
                "type": {
                    "name": "string"
                },
                "nullable": false,
                "editable": true,
                "uitype": null
            },
            {
                "name": "assigned_user_id",
                "label": "Assigned To",
                "mandatory": true,
                "type": {
                    "name": "owner"
                },
                "nullable": false,
                "editable": true,
                "default": "0",
                "uitype": null
            },
            {
                "name": "date_start",
                "label": "Start Date & Time",
                "mandatory": true,
                "type": {
                    "format": "yyyy-mm-dd",
                    "name": "date"
                },
                "nullable": false,
                "editable": true,
                "uitype": null
            },
            {
                "name": "time_start",
                "label": "Time Start",
                "mandatory": false,
                "type": {
                    "name": "time"
                },
                "nullable": true,
                "editable": true,
                "uitype": 252
            },
            {
                "name": "time_end",
                "label": "End Time",
                "mandatory": false,
                "type": {
                    "name": "time"
                },
                "nullable": true,
                "editable": true,
                "uitype": 252
            },
            {
                "name": "due_date",
                "label": "Due Date",
                "mandatory": true,
                "type": {
                    "format": "yyyy-mm-dd",
                    "name": "date"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "parent_id",
                "label": "Related to",
                "mandatory": false,
                "type": {
                    "refersTo": [
                        "Accounts",
                        "HelpDesk",
                        "Leads",
                        "Potentials",
                        "Invoice",
                        "Quotes",
                        "PurchaseOrder",
                        "SalesOrder",
                        "Campaigns"
                    ],
                    "name": "reference"
                },
                "nullable": false,
                "editable": true,
                "uitype": null
            },
            {
                "name": "contact_id",
                "label": "Contact Name",
                "mandatory": false,
                "type": {
                    "refersTo": [
                        "Contacts"
                    ],
                    "name": "reference"
                },
                "nullable": false,
                "editable": true,
                "default": "0",
                "uitype": null
            },
            {
                "name": "taskstatus",
                "label": "Status",
                "mandatory": true,
                "type": {
                    "picklistValues": [
                        {
                            "label": "Not Started",
                            "value": "Not Started"
                        },
                        {
                            "label": "In Progress",
                            "value": "In Progress"
                        },
                        {
                            "label": "Completed",
                            "value": "Completed"
                        },
                        {
                            "label": "Pending Input",
                            "value": "Pending Input"
                        },
                        {
                            "label": "Deferred",
                            "value": "Deferred"
                        },
                        {
                            "label": "Planned",
                            "value": "Planned"
                        }
                    ],
                    "defaultValue": "Not Started",
                    "name": "picklist"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "eventstatus",
                "label": "Status",
                "mandatory": false,
                "type": {
                    "picklistValues": [
                        {
                            "label": "Planned",
                            "value": "Planned"
                        },
                        {
                            "label": "Held",
                            "value": "Held"
                        },
                        {
                            "label": "Not Held",
                            "value": "Not Held"
                        }
                    ],
                    "defaultValue": "Planned",
                    "name": "picklist"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "taskpriority",
                "label": "Priority",
                "mandatory": false,
                "type": {
                    "picklistValues": [
                        {
                            "label": "High",
                            "value": "High"
                        },
                        {
                            "label": "Medium",
                            "value": "Medium"
                        },
                        {
                            "label": "Low",
                            "value": "Low"
                        }
                    ],
                    "defaultValue": "High",
                    "name": "picklist"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "sendnotification",
                "label": "Send Notification",
                "mandatory": false,
                "type": {
                    "name": "boolean"
                },
                "nullable": false,
                "editable": true,
                "default": "0",
                "uitype": null
            },
            {
                "name": "createdtime",
                "label": "Created Time",
                "mandatory": false,
                "type": {
                    "name": "datetime"
                },
                "nullable": false,
                "editable": false,
                "uitype": null
            },
            {
                "name": "modifiedtime",
                "label": "Modified Time",
                "mandatory": false,
                "type": {
                    "name": "datetime"
                },
                "nullable": false,
                "editable": false,
                "uitype": null
            },
            {
                "name": "activitytype",
                "label": "Activity Type",
                "mandatory": false,
                "type": {
                    "picklistValues": [
                        {
                            "label": "Call",
                            "value": "Call"
                        },
                        {
                            "label": "Meeting",
                            "value": "Meeting"
                        }
                    ],
                    "defaultValue": "Call",
                    "name": "picklist"
                },
                "nullable": false,
                "editable": true,
                "uitype": null
            },
            {
                "name": "visibility",
                "label": "Visibility",
                "mandatory": false,
                "type": {
                    "picklistValues": [
                        {
                            "label": "Private",
                            "value": "Private"
                        },
                        {
                            "label": "Public",
                            "value": "Public"
                        }
                    ],
                    "defaultValue": "Private",
                    "name": "picklist"
                },
                "nullable": false,
                "editable": true,
                "default": "all",
                "uitype": null
            },
            {
                "name": "description",
                "label": "Description",
                "mandatory": false,
                "type": {
                    "name": "text"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "duration_hours",
                "label": "Duration",
                "mandatory": false,
                "type": {
                    "name": "time"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "duration_minutes",
                "label": "Duration Minutes",
                "mandatory": false,
                "type": {
                    "picklistValues": [
                        {
                            "label": "00",
                            "value": "00"
                        },
                        {
                            "label": "15",
                            "value": "15"
                        },
                        {
                            "label": "30",
                            "value": "30"
                        },
                        {
                            "label": "45",
                            "value": "45"
                        }
                    ],
                    "defaultValue": "00",
                    "name": "picklist"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "location",
                "label": "Location",
                "mandatory": false,
                "type": {
                    "name": "string"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "reminder_time",
                "label": "Send Reminder",
                "mandatory": false,
                "type": {
                    "name": "integer"
                },
                "nullable": false,
                "editable": true,
                "uitype": null
            },
            {
                "name": "recurringtype",
                "label": "Recurrence",
                "mandatory": false,
                "type": {
                    "picklistValues": [
                        {
                            "label": "--None--",
                            "value": "--None--"
                        },
                        {
                            "label": "Day(s)",
                            "value": "Daily"
                        },
                        {
                            "label": "Week(s)",
                            "value": "Weekly"
                        },
                        {
                            "label": "Month(s)",
                            "value": "Monthly"
                        },
                        {
                            "label": "Year",
                            "value": "Yearly"
                        }
                    ],
                    "defaultValue": "--None--",
                    "name": "picklist"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "notime",
                "label": "No Time",
                "mandatory": false,
                "type": {
                    "name": "boolean"
                },
                "nullable": false,
                "editable": true,
                "default": "0",
                "uitype": null
            },
            {
                "name": "cf_617",
                "label": "Telefono da chiamare per chiarimenti",
                "mandatory": false,
                "type": {
                    "name": "phone"
                },
                "nullable": true,
                "editable": true,
                "uitype": null
            },
            {
                "name": "id",
                "label": "activityid",
                "mandatory": false,
                "type": {
                    "name": "autogenerated"
                },
                "editable": false,
                "nullable": false,
                "default": "",
                "uitype": null
            }
        ],
        "idPrefix": "1",
        "isEntity": true,
        "labelFields": "subject"
    }
}
}

syncModuleRecords

Performs a sync of records for specified modules, returning the updated and deleted records since last sync. (Identified by syncToken parameter)

IMPORTANT: syncModuleRecords does not display custom fields (apparently)

Parameters:

Name Value
_operation syncModuleRecords
_session session (from Login)
module Module
syncToken [empty, or the token from previous sync]
mode PRIVATE
page integer

Allowed values for module:

Allowed values for mode:

Page can be empty.

{
"success": true,
"result": {
    "sync": {
        "nextSyncToken": 1385311551,
        "deleted": [],
        "updated": [
            {
                "blocks": [
                    {
                        "label": "Task Information",
                        "fields": [
                            {
                                "name": "subject",
                                "value": "Meeting with Lead",
                                "label": "Subject",
                                "uitype": "2"
                            },
                            {
                                "name": "reminder_time",
                                "value": "0",
                                "label": "Send Reminder",
                                "uitype": "30"
                            },
                            {
                                "name": "assigned_user_id",
                                "value": {
                                    "value": "19x1",
                                    "label": "Administrator"
                                },
                                "label": "Assigned To",
                                "uitype": "53",
                                "type": {
                                    "defaultValue": {
                                        "value": "19x1",
                                        "label": "Administrator"
                                    }
                                }
                            },
                            {
                                "name": "date_start",
                                "value": "2014-01-13",
                                "label": "Start Date & Time",
                                "uitype": "6"
                            },
                            {
                                "name": "time_end",
                                "value": "10:45",
                                "label": "End Time",
                                "uitype": 252
                            },
                            {
                                "name": "time_start",
                                "value": "09:45",
                                "label": "Time Start",
                                "uitype": 252
                            },
                            {
                                "name": "due_date",
                                "value": "2014-01-13",
                                "label": "Due Date",
                                "uitype": "23"
                            },
                            {
                                "name": "recurringtype",
                                "value": "",
                                "label": "Recurrence",
                                "uitype": "16"
                            },
                            {
                                "name": "parent_id",
                                "value": {
                                    "value": "2x37",
                                    "label": "Davis Jennifer"
                                },
                                "label": "Related to",
                                "uitype": "66"
                            },
                            {
                                "name": "contact_id",
                                "value": {
                                    "value": "",
                                    "label": ""
                                },
                                "label": "Contact Name",
                                "uitype": "57"
                            },
                            {
                                "name": "eventstatus",
                                "value": "Planned",
                                "label": "Status",
                                "uitype": "15"
                            },
                            {
                                "name": "taskpriority",
                                "value": "High",
                                "label": "Priority",
                                "uitype": "15"
                            },
                            {
                                "name": "sendnotification",
                                "value": "",
                                "label": "Send Notification",
                                "uitype": "56"
                            },
                            {
                                "name": "createdtime",
                                "value": "2013-11-18 09:44:20",
                                "label": "Created Time",
                                "uitype": "70"
                            },
                            {
                                "name": "modifiedtime",
                                "value": "2013-11-18 09:44:20",
                                "label": "Modified Time",
                                "uitype": "70"
                            },
                            {
                                "name": "activitytype",
                                "value": "Meeting",
                                "label": "Activity Type",
                                "uitype": "15"
                            },
                            {
                                "name": "duration_hours",
                                "value": "1",
                                "label": "Duration",
                                "uitype": "63"
                            },
                            {
                                "name": "visibility",
                                "value": "Private",
                                "label": "Visibility",
                                "uitype": "16"
                            },
                            {
                                "name": "duration_minutes",
                                "value": "0",
                                "label": "Duration Minutes",
                                "uitype": "16"
                            },
                            {
                                "name": "location",
                                "value": "via dei mille 45, Brescia, Italia",
                                "label": "Location",
                                "uitype": "1"
                            },
                            {
                                "name": "notime",
                                "value": "0",
                                "label": "No Time",
                                "uitype": "56"
                            }
                        ]
                    },
                    {
                        "label": "",
                        "fields": [
                            {
                                "name": "description",
                                "value": "description of meeting with Lead",
                                "label": "Description",
                                "uitype": "19"
                            }
                        ]
                    },
                    {
                        "label": "Custom Information",
                        "fields": []
                    }
                ],
                "id": "18x1207",
                "labelFields": [
                    "subject"
                ]
            },
            {
                "blocks": [
                    {
                        "label": "Task Information",
                        "fields": [
                            {
                                "name": "subject",
                                "value": "Meeting with Lead",
                                "label": "Subject",
                                "uitype": "2"
                            },
                            {
                                "name": "reminder_time",
                                "value": "0",
                                "label": "Send Reminder",
                                "uitype": "30"
                            },
                            {
                                "name": "assigned_user_id",
                                "value": {
                                    "value": "19x1",
                                    "label": "Administrator"
                                },
                                "label": "Assigned To",
                                "uitype": "53",
                                "type": {
                                    "defaultValue": {
                                        "value": "19x1",
                                        "label": "Administrator"
                                    }
                                }
                            },
                            {
                                "name": "date_start",
                                "value": "2014-01-12",
                                "label": "Start Date & Time",
                                "uitype": "6"
                            },
                            {
                                "name": "time_end",
                                "value": "10:45",
                                "label": "End Time",
                                "uitype": 252
                            },
                            {
                                "name": "time_start",
                                "value": "09:45",
                                "label": "Time Start",
                                "uitype": 252
                            },
                            {
                                "name": "due_date",
                                "value": "2014-01-12",
                                "label": "Due Date",
                                "uitype": "23"
                            },
                            {
                                "name": "recurringtype",
                                "value": "",
                                "label": "Recurrence",
                                "uitype": "16"
                            },
                            {
                                "name": "parent_id",
                                "value": {
                                    "value": "2x37",
                                    "label": "Davis Jennifer"
                                },
                                "label": "Related to",
                                "uitype": "66"
                            },
                            {
                                "name": "contact_id",
                                "value": {
                                    "value": "",
                                    "label": ""
                                },
                                "label": "Contact Name",
                                "uitype": "57"
                            },
                            {
                                "name": "eventstatus",
                                "value": "Planned",
                                "label": "Status",
                                "uitype": "15"
                            },
                            {
                                "name": "taskpriority",
                                "value": "High",
                                "label": "Priority",
                                "uitype": "15"
                            },
                            {
                                "name": "sendnotification",
                                "value": "",
                                "label": "Send Notification",
                                "uitype": "56"
                            },
                            {
                                "name": "createdtime",
                                "value": "2013-11-18 09:44:19",
                                "label": "Created Time",
                                "uitype": "70"
                            },
                            {
                                "name": "modifiedtime",
                                "value": "2013-11-18 09:44:19",
                                "label": "Modified Time",
                                "uitype": "70"
                            },
                            {
                                "name": "activitytype",
                                "value": "Meeting",
                                "label": "Activity Type",
                                "uitype": "15"
                            },
                            {
                                "name": "duration_hours",
                                "value": "1",
                                "label": "Duration",
                                "uitype": "63"
                            },
                            {
                                "name": "visibility",
                                "value": "Private",
                                "label": "Visibility",
                                "uitype": "16"
                            },
                            {
                                "name": "duration_minutes",
                                "value": "0",
                                "label": "Duration Minutes",
                                "uitype": "16"
                            },
                            {
                                "name": "location",
                                "value": "via dei mille 45, Brescia, Italia",
                                "label": "Location",
                                "uitype": "1"
                            },
                            {
                                "name": "notime",
                                "value": "0",
                                "label": "No Time",
                                "uitype": "56"
                            }
                        ]
                    },
                    {
                        "label": "",
                        "fields": [
                            {
                                "name": "description",
                                "value": "description of meeting with Lead",
                                "label": "Description",
                                "uitype": "19"
                            }
                        ]
                    },
                    {
                        "label": "Custom Information",
                        "fields": []
                    }
                ],
                "id": "18x1206",
                "labelFields": [
                    "subject"
                ]
            }
        ],
        "nextPage": 0
    }
}
}

fetchRecord

Fetches a single record. Fields are laid out in a simple key:value association, and all additional keys (such as uitype, label) are skipped.

IMPORTANT: fetchRecord fetches Custom Fields correctly, but does not display a label for them.

Parameters:

Name Value
_operation fetchRecord
_session session (from Login)
record module_idXrecord_id

Allowed values for module:

Record must be in the form module_idXrecord_id such as 1x1151

{
"success": true,
"result": {
    "record": {
        "subject": "new todo with very long title  that in iOS will be cut somewhere!",
        "assigned_user_id": {
            "value": "19x1",
            "label": "Administrator"
        },
        "date_start": "2013-05-27",
        "time_start": "15:40",
        "time_end": "",
        "due_date": "2013-05-27",
        "parent_id": {
            "value": "",
            "label": ""
        },
        "contact_id": {
            "value": "",
            "label": ""
        },
        "taskstatus": "Not Started",
        "eventstatus": "",
        "taskpriority": "High",
        "sendnotification": "0",
        "createdtime": "2013-05-26 15:39:57",
        "modifiedtime": "2013-05-26 15:39:57",
        "activitytype": "Task",
        "visibility": "",
        "description": "desc",
        "duration_hours": "",
        "duration_minutes": "",
        "location": "",
        "reminder_time": "",
        "recurringtype": "",
        "notime": "0",
        "cf_617": "",
        "id": "1x1151"
    }
}
}

fetchRecordWithGrouping

Fetches a single record and returns fields with the complete representation containing uitype, label (translated), value and name.

IMPORTANT: fetchRecord fetches Custom Fields and it’s sent in the 3rd "block" of fields.

Parameters:

Name Value
_operation fetchRecordWithGrouping
_session session (from Login)
record module_idXrecord_id

Record must be in the form module_idXrecord_id such as 1x1151

{
"success": true,
"result": {
    "record": {
        "blocks": [
            {
                "label": "Task Information",
                "fields": [
                    {
                        "name": "subject",
                        "value": "new todo with very long title  that in iOS will be cut somewhere!",
                        "label": "Subject",
                        "uitype": "2"
                    },
                    {
                        "name": "reminder_time",
                        "value": "",
                        "label": "Send Reminder",
                        "uitype": "30"
                    },
                    {
                        "name": "assigned_user_id",
                        "value": {
                            "value": "19x1",
                            "label": "Administrator"
                        },
                        "label": "Assigned To",
                        "uitype": "53",
                        "type": {
                            "defaultValue": {
                                "value": "19x1",
                                "label": "Administrator"
                            }
                        }
                    },
                    {
                        "name": "date_start",
                        "value": "2013-05-27",
                        "label": "Start Date & Time",
                        "uitype": "6"
                    },
                    {
                        "name": "time_end",
                        "value": "",
                        "label": "End Time",
                        "uitype": 252
                    },
                    {
                        "name": "time_start",
                        "value": "15:40",
                        "label": "Time Start",
                        "uitype": 252
                    },
                    {
                        "name": "due_date",
                        "value": "2013-05-27",
                        "label": "Due Date",
                        "uitype": "23"
                    },
                    {
                        "name": "recurringtype",
                        "value": "",
                        "label": "Recurrence",
                        "uitype": "16"
                    },
                    {
                        "name": "parent_id",
                        "value": {
                            "value": "",
                            "label": ""
                        },
                        "label": "Related to",
                        "uitype": "66"
                    },
                    {
                        "name": "taskstatus",
                        "value": "Not Started",
                        "label": "Status",
                        "uitype": "15"
                    },
                    {
                        "name": "contact_id",
                        "value": {
                            "value": "",
                            "label": ""
                        },
                        "label": "Contact Name",
                        "uitype": "57"
                    },
                    {
                        "name": "eventstatus",
                        "value": "",
                        "label": "Status",
                        "uitype": "15"
                    },
                    {
                        "name": "taskpriority",
                        "value": "High",
                        "label": "Priority",
                        "uitype": "15"
                    },
                    {
                        "name": "sendnotification",
                        "value": "0",
                        "label": "Send Notification",
                        "uitype": "56"
                    },
                    {
                        "name": "createdtime",
                        "value": "2013-05-26 15:39:57",
                        "label": "Created Time",
                        "uitype": "70"
                    },
                    {
                        "name": "modifiedtime",
                        "value": "2013-05-26 15:39:57",
                        "label": "Modified Time",
                        "uitype": "70"
                    },
                    {
                        "name": "activitytype",
                        "value": "Task",
                        "label": "Activity Type",
                        "uitype": "15"
                    },
                    {
                        "name": "duration_hours",
                        "value": "",
                        "label": "Duration",
                        "uitype": "63"
                    },
                    {
                        "name": "visibility",
                        "value": "",
                        "label": "Visibility",
                        "uitype": "16"
                    },
                    {
                        "name": "duration_minutes",
                        "value": "",
                        "label": "Duration Minutes",
                        "uitype": "16"
                    },
                    {
                        "name": "location",
                        "value": "",
                        "label": "Location",
                        "uitype": "1"
                    },
                    {
                        "name": "notime",
                        "value": "0",
                        "label": "No Time",
                        "uitype": "56"
                    }
                ]
            },
            {
                "label": "",
                "fields": [
                    {
                        "name": "description",
                        "value": "desc",
                        "label": "Description",
                        "uitype": "19"
                    }
                ]
            },
            {
                "label": "Custom Information",
                "fields": [
                    {
                        "name": "cf_617",
                        "value": "",
                        "label": "Telefono da chiamare per chiarimenti",
                        "uitype": "11"
                    }
                ]
            }
        ],
        "id": "1x1151"
    }
}
}

fetchRecordsWithGrouping

Fetches an array of records and returns fields with the complete representation containing uitype, label (translated), value and name. Custom fields are fetched.

IMPORTANT: fetchRecord fetches Custom Fields and it’s sent in the 3rd "block" of fields.

Parameters:

Name Value
_operation fetchRecordsWithGrouping
_session session (from Login)
ids ["module_idXrecord_id","module_idXrecord_id"]
alertid (optional)

Allowed values for module:

Records must be in the form module_idXrecord_id, such as 1x1151, and the ids parameter should be formatted as a JSON string (["18x1164", "1x1151"]).

{
"success": true,
"result": {
    "records": [
        {
            "blocks": [
                {
                    "label": "Task Information",
                    "fields": [
                        {
                            "name": "subject",
                            "value": "new todo with very long title  that in iOS will be cut somewhere!",
                            "label": "Subject",
                            "uitype": "2"
                        },
                        {
                            "name": "reminder_time",
                            "value": "",
                            "label": "Send Reminder",
                            "uitype": "30"
                        },
                        {
                            "name": "assigned_user_id",
                            "value": {
                                "value": "19x1",
                                "label": "Administrator"
                            },
                            "label": "Assigned To",
                            "uitype": "53",
                            "type": {
                                "defaultValue": {
                                    "value": "19x1",
                                    "label": "Administrator"
                                }
                            }
                        },
                        {
                            "name": "date_start",
                            "value": "2013-05-27",
                            "label": "Start Date & Time",
                            "uitype": "6"
                        },
                        {
                            "name": "time_end",
                            "value": "",
                            "label": "End Time",
                            "uitype": 252
                        },
                        {
                            "name": "time_start",
                            "value": "15:40",
                            "label": "Time Start",
                            "uitype": 252
                        },
                        {
                            "name": "due_date",
                            "value": "2013-05-27",
                            "label": "Due Date",
                            "uitype": "23"
                        },
                        {
                            "name": "recurringtype",
                            "value": "",
                            "label": "Recurrence",
                            "uitype": "16"
                        },
                        {
                            "name": "parent_id",
                            "value": {
                                "value": "",
                                "label": ""
                            },
                            "label": "Related to",
                            "uitype": "66"
                        },
                        {
                            "name": "taskstatus",
                            "value": "Not Started",
                            "label": "Status",
                            "uitype": "15"
                        },
                        {
                            "name": "contact_id",
                            "value": {
                                "value": "",
                                "label": ""
                            },
                            "label": "Contact Name",
                            "uitype": "57"
                        },
                        {
                            "name": "eventstatus",
                            "value": "",
                            "label": "Status",
                            "uitype": "15"
                        },
                        {
                            "name": "taskpriority",
                            "value": "High",
                            "label": "Priority",
                            "uitype": "15"
                        },
                        {
                            "name": "sendnotification",
                            "value": "0",
                            "label": "Send Notification",
                            "uitype": "56"
                        },
                        {
                            "name": "createdtime",
                            "value": "2013-05-26 15:39:57",
                            "label": "Created Time",
                            "uitype": "70"
                        },
                        {
                            "name": "modifiedtime",
                            "value": "2013-05-26 15:39:57",
                            "label": "Modified Time",
                            "uitype": "70"
                        },
                        {
                            "name": "activitytype",
                            "value": "Task",
                            "label": "Activity Type",
                            "uitype": "15"
                        },
                        {
                            "name": "duration_hours",
                            "value": "",
                            "label": "Duration",
                            "uitype": "63"
                        },
                        {
                            "name": "visibility",
                            "value": "",
                            "label": "Visibility",
                            "uitype": "16"
                        },
                        {
                            "name": "duration_minutes",
                            "value": "",
                            "label": "Duration Minutes",
                            "uitype": "16"
                        },
                        {
                            "name": "location",
                            "value": "",
                            "label": "Location",
                            "uitype": "1"
                        },
                        {
                            "name": "notime",
                            "value": "0",
                            "label": "No Time",
                            "uitype": "56"
                        }
                    ]
                },
                {
                    "label": "",
                    "fields": [
                        {
                            "name": "description",
                            "value": "desc",
                            "label": "Description",
                            "uitype": "19"
                        }
                    ]
                },
                {
                    "label": "Custom Information",
                    "fields": [
                        {
                            "name": "cf_617",
                            "value": "",
                            "label": "Telefono da chiamare per chiarimenti",
                            "uitype": "11"
                        }
                    ]
                }
            ],
            "id": "1x1151"
        }
    ]
}
}

saveRecord

Updates or creates a record, depending whether the record id is set or not.

Parameters:

Name Value
_operation saveRecord
_session session (from Login)
module Module
record module_idXrecord_id
values json string

Allowed values for module:

Example of JSON String to set in the values parameter:

{
  "date_start": "2014-01-18",
  "due_date": "2014-01-18",
  "start_time": "14:44",
  "activitytype": "Call",
  "location": "Overhoeksplein 2, Amsterdam",
  "subject": "Call Smith",
  "assigned_user_id": "19x1",
  "taskstatus": "Planned",
  "visibility": "Private"
}

Note the absence of "id" because we want to create a new record.

For setting the assigned user, The id must be in the form of moduleid x entityid.

Record must be in the form module_idXrecord_id such as 1x1151.

Example of successful response: (basically returns the entire record created)

{
"success": true,
"result": {
    "record": {
        "blocks": [
            {
                "label": "Task Information",
                "fields": [
                    {
                        "name": "subject",
                        "value": "Call Smith",
                        "label": "Subject",
                        "uitype": "2"
                    },
                    {
                        "name": "reminder_time",
                        "value": "",
                        "label": "Send Reminder",
                        "uitype": "30"
                    },
                    {
                        "name": "assigned_user_id",
                        "value": {
                            "value": "19x1",
                            "label": "Administrator"
                        },
                        "label": "Assigned To",
                        "uitype": "53",
                        "type": {
                            "defaultValue": {
                                "value": "19x1",
                                "label": "Administrator"
                            }
                        }
                    },
                    {
                        "name": "date_start",
                        "value": "2014-01-18",
                        "label": "Start Date & Time",
                        "uitype": "6"
                    },
                    {
                        "name": "time_end",
                        "value": "",
                        "label": "End Time",
                        "uitype": 252
                    },
                    {
                        "name": "time_start",
                        "value": "",
                        "label": "Time Start",
                        "uitype": 252
                    },
                    {
                        "name": "due_date",
                        "value": "2014-01-18",
                        "label": "Due Date",
                        "uitype": "23"
                    },
                    {
                        "name": "recurringtype",
                        "value": "",
                        "label": "Recurrence",
                        "uitype": "16"
                    },
                    {
                        "name": "parent_id",
                        "value": {
                            "value": "",
                            "label": ""
                        },
                        "label": "Related to",
                        "uitype": "66"
                    },
                    {
                        "name": "taskstatus",
                        "value": "",
                        "label": "Status",
                        "uitype": "15"
                    },
                    {
                        "name": "contact_id",
                        "value": {
                            "value": "",
                            "label": ""
                        },
                        "label": "Contact Name",
                        "uitype": "57"
                    },
                    {
                        "name": "eventstatus",
                        "value": "",
                        "label": "Status",
                        "uitype": "15"
                    },
                    {
                        "name": "taskpriority",
                        "value": "",
                        "label": "Priority",
                        "uitype": "15"
                    },
                    {
                        "name": "sendnotification",
                        "value": "0",
                        "label": "Send Notification",
                        "uitype": "56"
                    },
                    {
                        "name": "createdtime",
                        "value": "2013-11-25 13:43:49",
                        "label": "Created Time",
                        "uitype": "70"
                    },
                    {
                        "name": "modifiedtime",
                        "value": "2013-11-25 13:43:49",
                        "label": "Modified Time",
                        "uitype": "70"
                    },
                    {
                        "name": "activitytype",
                        "value": "Call",
                        "label": "Activity Type",
                        "uitype": "15"
                    },
                    {
                        "name": "duration_hours",
                        "value": "0",
                        "label": "Duration",
                        "uitype": "63"
                    },
                    {
                        "name": "visibility",
                        "value": "Private",
                        "label": "Visibility",
                        "uitype": "16"
                    },
                    {
                        "name": "duration_minutes",
                        "value": "",
                        "label": "Duration Minutes",
                        "uitype": "16"
                    },
                    {
                        "name": "location",
                        "value": "",
                        "label": "Location",
                        "uitype": "1"
                    },
                    {
                        "name": "notime",
                        "value": "0",
                        "label": "No Time",
                        "uitype": "56"
                    }
                ]
            },
            {
                "label": "",
                "fields": [
                    {
                        "name": "description",
                        "value": "",
                        "label": "Description",
                        "uitype": "19"
                    }
                ]
            },
            {
                "label": "Custom Information",
                "fields": [
                    {
                        "name": "cf_617",
                        "value": "",
                        "label": "Telefono da chiamare per chiarimenti",
                        "uitype": "11"
                    }
                ]
            }
        ],
        "id": "1x1225"
    }
 }
 }

"success": true,
"result": {
    "record": {
        "blocks": [
            {
                "label": "Task Information",
                "fields": [
                    {
                        "name": "subject",
                        "value": "Call Smith",
                        "label": "Subject",
                        "uitype": "2"
                    },
                    {
                        "name": "reminder_time",
                        "value": "",
                        "label": "Send Reminder",
                        "uitype": "30"
                    },
                    {
                        "name": "assigned_user_id",
                        "value": {
                            "value": "19x1",
                            "label": "Administrator"
                        },
                        "label": "Assigned To",
                        "uitype": "53",
                        "type": {
                            "defaultValue": {
                                "value": "19x1",
                                "label": "Administrator"
                            }
                        }
                    },
                    {
                        "name": "date_start",
                        "value": "2014-01-18",
                        "label": "Start Date & Time",
                        "uitype": "6"
                    },
                    {
                        "name": "time_end",
                        "value": "",
                        "label": "End Time",
                        "uitype": 252
                    },
                    {
                        "name": "time_start",
                        "value": "",
                        "label": "Time Start",
                        "uitype": 252
                    },
                    {
                        "name": "due_date",
                        "value": "2014-01-18",
                        "label": "Due Date",
                        "uitype": "23"
                    },
                    {
                        "name": "recurringtype",
                        "value": "",
                        "label": "Recurrence",
                        "uitype": "16"
                    },
                    {
                        "name": "parent_id",
                        "value": {
                            "value": "",
                            "label": ""
                        },
                        "label": "Related to",
                        "uitype": "66"
                    },
                    {
                        "name": "taskstatus",
                        "value": "",
                        "label": "Status",
                        "uitype": "15"
                    },
                    {
                        "name": "contact_id",
                        "value": {
                            "value": "",
                            "label": ""
                        },
                        "label": "Contact Name",
                        "uitype": "57"
                    },
                    {
                        "name": "eventstatus",
                        "value": "",
                        "label": "Status",
                        "uitype": "15"
                    },
                    {
                        "name": "taskpriority",
                        "value": "",
                        "label": "Priority",
                        "uitype": "15"
                    },
                    {
                        "name": "sendnotification",
                        "value": "0",
                        "label": "Send Notification",
                        "uitype": "56"
                    },
                    {
                        "name": "createdtime",
                        "value": "2013-11-25 13:43:49",
                        "label": "Created Time",
                        "uitype": "70"
                    },
                    {
                        "name": "modifiedtime",
                        "value": "2013-11-25 13:43:49",
                        "label": "Modified Time",
                        "uitype": "70"
                    },
                    {
                        "name": "activitytype",
                        "value": "Call",
                        "label": "Activity Type",
                        "uitype": "15"
                    },
                    {
                        "name": "duration_hours",
                        "value": "0",
                        "label": "Duration",
                        "uitype": "63"
                    },
                    {
                        "name": "visibility",
                        "value": "Private",
                        "label": "Visibility",
                        "uitype": "16"
                    },
                    {
                        "name": "duration_minutes",
                        "value": "",
                        "label": "Duration Minutes",
                        "uitype": "16"
                    },
                    {
                        "name": "location",
                        "value": "",
                        "label": "Location",
                        "uitype": "1"
                    },
                    {
                        "name": "notime",
                        "value": "0",
                        "label": "No Time",
                        "uitype": "56"
                    }
                ]
            },
            {
                "label": "",
                "fields": [
                    {
                        "name": "description",
                        "value": "",
                        "label": "Description",
                        "uitype": "19"
                    }
                ]
            },
            {
                "label": "Custom Information",
                "fields": [
                    {
                        "name": "cf_617",
                        "value": "",
                        "label": "Telefono da chiamare per chiarimenti",
                        "uitype": "11"
                    }
                ]
            }
        ],
        "id": "1x1225"
    }
}
}

Example of error:

{
  "success": false,
  "error": {
    "code": "MANDATORY_FIELDS_MISSING",
    "message": "assigned_user_id does not have a value"
  }
}

Module-specific considerations

Contacts

Contacts have a picture field available, but it can be accessed only through the web interface and its content (e.g. the file name) are not retrieved either by the webservice.php or any operation such as syncModuleRecords. When displaying the fields as grouped, a "block" contains the file information but the array is actually empty, even when a contact picture is uploaded.

{
 "label": "Contact Image Information:",
 "fields": []
}

Documents

Documents should be designed to contain files, but the file data is not accessible through the webservice. In fact, even from the official vTiger Mobile application (for iOS), only the metadata of the document are accessible, but the filename and download URL are not accessible through the mobile API.

HelpDesk (Trouble Tickets)

Trouble Tickets have the possibility to have Comments associated to each, and when trtrieving the records there is even a Comments block containing an array. But the array is empty independently from the presence of comments.

{
  "label": "COMMENTS",
  "fields": []
}