Integration

In the REST API topic you saw how to build APIs to access CRM data, but in the real world an organization uses hundreds of applications for their employees and data is spread across them. Very often there is need to either sync the data with other applications or bring/send some parts of data to/from CRM.

Connect applications having REST APIs

Connecting to other applications that has REST APIs exposed has become easy with VTAP platform now, you can use API Designer, build an API, connect to them using Javascript APIs and display them on a widget inside Vtiger or post data to the other application. These outbound REST APIs allow you to create, update, read or delete data on an application that supports REST architecture. To build any REST APIs you need to use VADL which provides xml nodes, we have used them to build custom CRM data APIs.

Use cases for REST APIs

Connect to Slack and post a message to channels from CRM.
Perform email or phone validation when the entering the data in CRM.
Get latest exchange currency rates and apply them when creating Invoice or Quotes etc.
Show weather details of a Contact or Lead real time.
Enrich customer data using email address or company domain and many more.

Parts of REST API

Rest API compromises of below parts:

Name	Description	VADL equivalent	Example
Endpoint	This is used to connect the application where the data resides. For dynamic parts of the url pass them as attributes in the url xml as shown in example 2.	url	`1. <url>https://example.com/api/v1/get_contacts</url>` `2.<url SHEETID="@sheetid" OPTIONS="values/Sheet1!A1:append?valueInputOption=RAW">https://sheets.googleapis.com/v4/spreadsheets/$SHEETID/$OPTIONS</url>`
Method	This tells what is the type of request, like get, post, put or delete.	Default is get type.	method
Header parameters	There can be many headers which notifies the target app about the details of the request.	headers	`<headers><header name="content-type" value="application/json"></header></headers>`
Authentication parameters	This will tell which type of authentication are used, like basic auth or bearer token, or oauth.	auth	`<auth><basic username="" password=""></basic></auth>`
Query parameters	Additional data needed for the request endpoint to perform required action.	parameters	`<parameters><parameter name="id" value="@id"></parameter></parameters>`
Raw json	send parameters as json	raw-post-data	`<parameters raw-post-data="true"><parameter name="id" value="@id"></parameter></parameters>`

How to add REST API?

Go to main menu, under Platform you need to select API Designer.
Click on Add Api button, you will given two option to select, one is Rest Api and other Webhook.
Select Rest api, provide the name of the api which will be used later to make calls, link to the module and enable the status to active.

General structure of REST API

To use a REST API with an external domain (e.g. https://something.com), you first need to allow the domain in your platform settings. To do that follow these steps:

Navigate to Apps > Platform > API Designer
Click the Settings icon in the top-right corner.
In the API Settings menu:

Select the module for which you are building the API.
Add the external domain (https://something.com) to the list of allowed domains.

This will enable the external domain for use in API requests.

Additionally, you can dynamically bind URL parameters using placeholders like $id. For example, in the URL https://something.com?params=$id, $id is a dynamic value.

<?xml version="1.0"?>
<api method="post">
    <rest method="post">
        <url id="@id">https://something.com?params=$id</url>
        <headers>
            <header name="" value=""></header>
        </headers>
        <auth>
            <basic username="" password=""></basic>
        </auth>
        <parameters>
            <parameter name="id" value="@id"></parameter>
        </parameters>
    </rest>
</api>

Examples of REST APIs

Send json POST request

<?xml version="1.0"?>
<api method="post">

    <rest method="post">
        <url>https://httpbin.org/anything</url>

        <headers>
            <header name="Content-Type" value="application/json"></header>
        </headers>

        <parameters raw-post-data="true">
            <parameter name='identifier' value='@identifier'></parameter>
            <parameter name='managerId' value='@managerId'></parameter>
            <parameter name='managerName' value='@managerName'></parameter>
        </parameters>
    </rest>
</api>

Build a weather app api to get the weather data.

<?xml version="1.0"?>
<api method="get">
    <rest method="get">
        <url>https://api.openweathermap.org/data/2.5/weather</url>
        <parameters>
            <parameter name="appid" value="@apiKey"></parameter>
            <parameter name="q" value="@city"></parameter>
            <parameter name="units" value="@unit"></parameter>
            <parameter name="lang" value="@lang"></parameter>
        </parameters>
    </rest>
</api>

Connect applications having OAuth support

We will add documentation on this soon, in the mean while you can watch this webinar video on our youtube channel.

Connect application having SOAP APIs

TBD

FAQs

I am getting error "unauthorized domain! Please whitelist https://xxx.xxx.xxx

To connect to any external application the adminstrator has to whitelist the domain, before you can start calling the API. For this you need to go to Apps > Platform > Api Designer, on the top right side we have provided Settings icon. Click on it to see Api Settings, here you can select the module for which you are building the API and add the external domain which can be used in building API.

Is it possible to make get/post type of request?

Yes, you can build GET, POST, PUT or DELETE type of request. When building api using VADL, inside api xml node you need to pass type attribute with one of the above values.

Vtiger Application Platform Documentation