Short manual about Vtiger API

In this article I will try to give answers to the most frequently asked questions on how to interact with Vtiger CRM via the API in terms of retrieving, modifying or creating records. The system provides an API for third-party applications and web applications to interact with the system.

The developers have tried to provide maximum opportunities for integrating VtigerCRM with other services and systems so that users can expand CRM capabilities for themselves and other users.

Creating your own integrations is not as difficult as it might seem at first glance. To make life easier for the developer, in addition to instructions, I will try to give examples of using the methods and their description in other articles.

So how do you interact with the API?

In order to get the data from Vtiger CRM, you need to introduce yourself and get a special session code, which you will later use to exchange data.

The authorization process takes place in two stages.

Stage 1 - getting token for md5.

We need it in order to encrypt the password to receive the token at the next request. To get an encryption token, you need to send a regular GET request without a password, specifying only the username of the user to whom the token needs to be issued.

GET

http://VTIGER_URL/webservice.php?operation=getchallenge&username=admin

Header

Content-type

application/x-www-form-urlencoded

{

"success": true,

"result": {

"token": "610a740fbbd66",

"serverTime": 1628075023,

"expireTime": 1628075323

}

I usually recommend creating a separate user to interact with Vtiger, or connecting under users with limited rights.

In the response, we see the token line. We will need it for the second stage.

Stage 2 - Getting session code.

First of all, we need to encrypt the password. Encryption takes place as follows:

You need to get the user's Access Key, which you can find in the user's profile (do not confuse it with a password).
Encrypt the key by gluing it to the token and running it through MD5.

If you are using Insomnia or Postman, you can get encrypted key on website: http://www.md5.cz/ . In this case just concatenate two strings: md5(TOKENSTRING + ACCESSKEY)

Where Tokenstring is the token that you received on the first request, Accesskey is the access key in the user profile.

Now that we have an encrypted password, we go through authorization by sending a request to CRM:

POST

http://VTIGER_URL/webservice.php

Request type - Form URL Encoded

operation=login

username=admin

accessKey=md5(TOKENSTRING + <ACCESSKEY>)

Here is the answer from CRM:

{

"success": true,

"result": {

"sessionName": "5c1ad80d610a7a7aabe2e",

"userId": "19x1",

"version": "0.22",

"vtigerVersion": "7.2.0-202008"

}

So, now we have a session number and we can use it when exchanging data with Vtiger.

Let's try to perform the most common operations.

Stage 3 - Getting list of contacts.

GET

http://VTIGER_URL/webservice.php?query=SELECT%20%2A%20FROM%20Contacts%3B&operation=query&sessionName=SESSION_KEY

where SESSION_KEY is our session key received from CRM

Note, that we are essentially getting contacts using an SQL query. The only thing is that in it we indicate not the name of the table, but the name of the module. It can also be extended by specifying additional conditions for the filter, for example, you can add WHERE modifiedtime> '2021-06-01' and it will work.

In the response, you get an array of contacts with limit of 100 entries, where the key will contain the name of the field and the value will contain the data for this field.

Stage 4 - Getting contacts by ID

This is the simplest one. To do this, you need to send a regular GET request:

http://VTIGER_URL/webservice.php?id=12x87&operation=retrieve&sessionName=SESSION_KEY

Here we are trying to get a contact with the number 87. But you probably noticed a special prefix, we are transmitting not just the number 87, but in a special 12x87 format. Thus, we let the CRM understand that we are receiving data from the module with the number 12, i.e. contacts.

You can get a list of all modules with their numbers in the CRM table: vtiger_ws_entity

Stage 5 - create contact

In this case, we need to send a POST request to http: //VTIGER_URL/webservice.php, passing the following fields in the form of a form:

operation=create

sessionName=sessionId

elementType=Contacts

You will also need to pass a special element field, which will contain all the data for the newly created contact as a JSON string.

element =

{

"firstname": "Александр",

"phone": "+7908222448800",

"lastname": "Ivanov",

"otherphone": "+79086789985",

"birthday": "1980-06-08",

"email": "ivanov@sergeyem.ru",

"assigned_user_id": "19x1",

}

You need to pass the required fields to the first queue. To understand which fields are required in the module, try to create a record in CRM manually and look at all the fields marked with an asterisk.

The assigned_user_id field is required in all modules. If you do not know what to transfer there, substitute the administrator number - 19x1

Этап 6 - Обновляем контакт

Similarly, we send a POST request to http://VTIGER_URL/webservice.php with fields:

operation=update

sessionName=sessionId

element=

{

"firstname": "Александр",

"phone": "+7908222448800",

"lastname": "Ivanov",

"otherphone": "+79086789985",

"birthday": "1980-06-15",

"email": "ivanov@sergeyem.ru",

"assigned_user_id": "19x1",

"id": "12x87"

}

As you may have noticed, we are not passing the name of the module. We must pass the ID in the API format, i.e. prefixed with 12x.

Fortunately, there is a special library for easier working with the Vtiger API, which I actively use: https://github.com/salaros/vtwsclib-php

Stage 6 - extend API

The convenience of the API in VtigerCRM is that you can easily extend its functionality by adding a new method.

As an example, consider the ability to get a translation of a specific meaning from CRM. For example, you have a translation file for the Contacts module. And you want to get the Russian value of the SINGLE_Contacts key. Or multiple values by passing an array of translatable parameters.

This is surprisingly easy to do.

Let's create a function that will carry out the translation. Create a file in a folder include/Webservices/GetTranslation.php

with following content:

function vtws_gettranslation($portal_language, $module, $totranslate, $user)

{

global $log, $default_language, $current_language;

$log->debug('> vtws_gettranslation');

foreach ($totranslate as $key => $str) {

$translated[$str] = Vtiger_Functions::getTranslatedString($str, $module, $portal_language);

}

return $translated;

}

This function will be responsible for handling the API request coming to it. Now we just have to register it. To do this, create a scripts folder and a register_gettranslation.php file in it

Content of this file:

$Vtiger_Utils_Log = true;

chdir('../');

include_once 'include/database/PearDatabase.php';

include_once 'include/Webservices/Utils.php';

global $current_user, $adb;

$db = PearDatabase::getInstance();

$operationName = 'gettranslation';

$handler_path = 'include/Webservices/GetTranslation.php';

$handler_method = 'vtws_gettranslation';

$operation_type = 'POST';

$result = $db->pquery("SELECT 1 FROM vtiger_ws_operation WHERE name = ?", array($operationName));

if (!$db->num_rows($result)) {

$operationId = vtws_addWebserviceOperation($operationName, $handler_path, $handler_method, $operation_type);

vtws_addWebserviceOperationParam($operationId, 'totranslate', 'encoded', 0);

vtws_addWebserviceOperationParam($operationId, 'language', 'string', 0);

vtws_addWebserviceOperationParam($operationId, 'module', 'string', 0);

}

echo 'DONE!';

Run it from the browser once and the handler will be registered successfully.

Now, in order to receive translations via the API, you need to send a POST request to the address http: //VTIGER_URL/webservice.php with the parameters: