Articles in this section
The Process Designer Data Source Designer VTAP - App Creator Vtiger Add-ons Publisher Insights Designer VTAP Release Notes VTAPIT - Command line tool VTAP Tables

API Designer in Vtiger CRM

Design API requests and responses and connect them with your CRM fields using Vtiger’s API Designer.
M
Megha KR
27 May, 2025 - Updated  4 days ago

Feature Availability

Vtiger Editions: One Growth | One Professional | One Enterprise | One AI
To learn more about feature limits, click here.
 


Introduction

An API is a structured interface that allows two software systems to exchange data or services. It defines a set of rules and methods that let one program request data or actions from another.

The API Designer is a tool for easily creating and managing API operations for different modules within the Vtiger CRM. It allows you to quickly design, test, and run APIs without the need to write complex code. In the API Designer, you can select specific modules like Contacts, Deals, Products, etc., define the actions you want to perform (such as Create, Read, Update, or Delete), and instantly see the results inside the CRM.

This tool makes it simple for you to:

  • Manage data sharing between the CRM and third-party systems.
  • Quickly test API operations for accuracy.
  • Automate tasks and processes involving Vtiger CRM and external tools.
 

Use Case

Imagine you’re making a weather app. To show live weather, the app needs data from somewhere—usually another service that shares information using an API.
An API designer helps plan how the app will request that data and what kind of response it will get.

When your weather app needs data for a specific city, the API designer defines the process:

  • The app makes a GET request to /weather/current with a city parameter like city=London.
  • The API responds with weather information such as temperature and conditions in JSON format.
  • If the city is not found, the API returns an appropriate error message (e.g., 404 error).

This setup provides clear instructions on how the app communicates with the weather service.

 

Key Features of API Designer

The key features of API Designer include the following:

  • A simple guided interface.
  • Select CRM modules and specific fields to work with.
  • Perform key actions like Create, Read, Update, and Delete (CRUD).
  • Control API user access by setting permissions and limits.
 

Benefits of Using the API Designer

The following are the benefits of using API Designer in Vtiger CRM:

  • Easily connect the CRM to other applications with minimal effort.
  • Design APIs using a simple interface that doesn't need programming skills.
  • Speed up the API setup and testing process, making it quicker to deploy.
  • Modify how data flows between the CRM and other platforms to suit your needs.
  • Control who can access and use APIs with simple access settings.
  • Easily manage different versions of APIs to ensure smooth operation.


In this article, you will learn about:

  • Creating an API in the API Designer
  • Performing REST API operations in the API Designer
  • Using a Webhook in the API Designer
  • Performing API operations using a Webhook


Key Terminology

Field Name

Description

REST API

A REST API is a web service that allows different software applications to communicate with each other over the internet.

Webhook

A Webhook is a user-configured HTTP callback that sends real-time data to a specified URL via an HTTP POST request when triggered by an event.

Token

The token is a secret key that confirms that the Webhook request originates from a trusted source (such as a third-party service or app).

Postman

Postman is a software application that helps you test APIs by sending different types of requests and viewing the results in a simple, organized way.



 

Creating an API 

Follow these steps to create a new REST API in the API Designer module:

  1. Log in to the CRM account.
  2. Go to the Main Menu.
  3. Go to the Platform.
  4. Select API Designer. The API Designer opens.
  5. Click on +Add API. A pop-up will appear with two options. 
  6. Select the API that you want to create.
    1. REST API: Select to create a custom REST API to access data.
    2. Webhook: Select to connect Vtiger with other apps in real time.
  7. Select Create from the REST API option. 
  8. Enter or select the following information for the mandatory fields:
    1. Module: Select the module you want to work with from the drop-down list.
    2. Name: Enter a name to identify the REST API you are creating.
    3. Status: Check the status box to activate and make the Rest API available for use.
 
  1. Click Save. The API Designer interface opens.
 You can now write scripts and perform different API operations in the API Designer interface.
 
 Now, let us understand the various operations required for REST API actions.


 

Performing REST API Operations in API Designer

 

CREATE Operation

In this example, we will use the CREATE operation to create a Contact record.

Performing REST API operations in API Designer requires you to do the following:

  • Step 1: Running the API script within the API Designer interface
  • Step 2: Verifying the CRM record reflects the REST API action


Step 1: Running the API script within the API Designer interface

Follow these steps to perform a CREATE operation for a Contact record:

  1. Log in to the CRM account.
  2. Go to the Main Menu.
  3. Go to the Platform.
  4. Select API Designer. The API Designer opens.
  5. Click on +Add API. A pop-up will appear with two options.
  6. Select REST API to create a custom API endpoint.
  7. Enter or select the following information for the mandatory fields:
    1. Module: Select the module you want to work with from the drop-down list.
    2. Name: Enter a name to identify the REST API you are creating.
    3. Status: Check the status box to activate and make the Rest API available for use.
  8. Click Save. The API Designer interface opens.
 
  1. Add all required fields for the chosen module and specify the operation name based on the action you want to perform.
 
  1. Click the Playground icon on the right side of the API Designer interface.
    1. Enter or select the following details:
      1. URL: The endpoint where the API request is sent.
      2. Request Parameters
        1. firstname: The first name of the contact being created.
        2. lastname: The last name of the contact being created.
        3. email: The email address of the contact.
  2. Click Send. The API Designer will process your request and create a new record with the provided information.  


Step 2: Verifying the CRM record reflects the REST API action

Follow these steps to verify the created record:

  1. Log in to the CRM account.
  2. Go to Essentials > Contacts.
  3. Look for the latest contact record created using the CREATE action.
 
  1. Go to the Updates tab. You will see an update saying API Designer - Created, confirming the record was added using the API Designer.
 

UPDATE Operation

In this example, we will use the UPDATE operation to update a Case record.

Performing REST API operations in API Designer requires you to do the following:

  • Step 1: Running the API script within the API Designer interface
  • Step 2: Verifying the CRM record reflects the REST API action


Step 1: Running the API script within the API Designer interface

Follow these steps to perform an UPDATE operation for a Case record:

  1. Log in to the CRM account.
  2. Go to the Main Menu.
  3. Go to the Platform.
  4. Select API Designer. The API Designer opens.
  5. Click on +Add API. A pop-up will appear with two options.
  6. Select REST API to create a custom API endpoint.
  7. Enter or select the following information for the mandatory fields:
    1. Module: Select the module you want to work with from the drop-down list.
    2. Name: Enter a name to identify the REST API you are creating.
    3. Status: Check the status box to activate and make the Rest API available for use.
  8. Click Save. The API Designer interface opens.
 
  1. Add all required fields for the chosen module and specify the operation name based on the action you want to perform.
  2. Click the Playground icon on the right side of the API Designer interface.
 
  1. Enter or select the following details:
    1. URL: The endpoint where the API request is sent.
    2. Request Parameters
      1. description: The additional details of the record.
      2. Id: Unique identifier of the record that needs to be updated.
      3. Click Send. The API Designer will process your request and update the record with the provided information.


Step 2: Verifying the CRM record reflects the REST API action

Follow these steps to verify the updated record:

  1. Log in to the CRM account.
  2. Go to Help desk > Cases.
  3. Look for the latest case record updated using the UPDATE action.
 
  1. Go to the Updates tab. You will see an update saying API Designer - Update Cases, confirming that the record was updated using the API Designer.


 

GET Operation

In this example, we will use the GET operation to retrieve an Organizations record.

Follow these steps to perform a GET operation for an Organizations record:

  1. Log in to the CRM account.
  2. Go to the Main Menu.
  3. Go to the Platform.
  4. Select API Designer. The API Designer opens.
  5. Click on +Add API. A pop-up will appear with two options.
  6. Select REST API to create a custom API endpoint.
  7. Enter or select the following information for the mandatory fields:
    1. Module: Select the module you want to work with from the drop-down list.
    2. Name: Enter a name to identify the REST API you are creating.
    3. Status: Check the status box to activate and make the Rest API available for use.
  8. Click Save. The API Designer interface opens.
 
  1. Add all required fields for the chosen module and specify the operation name based on the action you want to perform.
  2. Click the Playground icon on the right side of the API Designer interface.
  3. Enter or select the following details:
    1. URL: The endpoint where the API request is sent.
    2. Click Send. 

The API Designer will process the request and return a response containing all organization records along with their respective field values.

 

UPSERT Operation

A UPSERT operation combines the functionality of both update and create actions. It checks whether a record already exists; if it does, the record is updated; if it doesn’t, a new record is created. 

This ensures data is inserted or updated in a single operation.

Rules of UPSERT Operation

  • For the update action using the upsert operation, you must include the record ID along with the fields you want to update.
  • For the create action, make sure to include all mandatory fields along with the selected operation type to complete the upsert process.

In this example, we will use the UPSERT operation for a Contact record.

Performing REST API operations in API Designer requires you to do the following:

  • Step 1: Running the API script within the API Designer interface
  • Step 2: Verifying the CRM record reflects the REST API action


Step 1: Running the API script within the API Designer interface

Follow these steps to perform a UPSERT operation for a Contact record:

  1. Log in to the CRM account.
  2. Go to the Main Menu.
  3. Go to the Platform.
  4. Select API Designer. The API Designer opens.
  5. Click on +Add API. A pop-up will appear with two options.
  6. Select REST API to create a custom API endpoint.
  7. Enter or select the following information for the mandatory fields:
    1. Module: Select the module you want to work with from the drop-down list.
    2. Name: Enter a name to identify the REST API you are creating.
    3. Status: Check the status box to activate and make the Rest API available for use.
  8. Click Save. The API Designer interface opens.
 
  1. Add all required fields for the chosen module and specify the operation name based on the action you want to perform.
  2. Click the Playground icon on the right side of the API Designer interface.
  3. Enter or select the following details:
    1. URL: The endpoint where the API request is sent.
    2. Enter the following Request Parameters:
      1. CRMID: Unique identifier of the record.
      2. email: Email address of the contact record.
      3. card: Custom or reference field to store card details or related identifier.
      4. lastname: Last name of the contact record.
      5. firstname: First name of the contact record.
      6. website: The contact’s website to store web details.
      7. Click Send. The API Designer will process your request and update the record with the provided information.
 

Step 2: Verifying the CRM record reflects the REST API action

Follow these steps to verify the record:

  1. Log in to the CRM account.
  2. Go to Essentials > Contacts.
  3. Hover over the records updated or created using the API action.
 
  1. Go to the Updates tab. You will see an update saying API Designer - Upsert, confirming that the record was created using the API Designer.

Note: When sending additional requests, make sure to change the field values. If the same values are used, the system may return a Duplicate records found error.



 

Using Webhooks in API Designer

You can use the Webhook option to trigger API operations from third-party apps, enabling actions such as CREATE, UPDATE, and GET.

Follow these steps to create a new API using Webhook:

  1. Log in to the CRM account.
  2. Go to the Main Menu.
  3. Go to the Platform.
  4. Select API Designer. The API Designer opens.
 
  1. Click on +Add API. A pop-up will appear with two options. 
 
  1. Select Webhook to connect Vtiger with other apps.
  2. Select Create from the Webhook option. 
 
  1. Enter or select the following mandatory fields.
    1. Module: Select the module you want to work with from the drop-down list.
    2. Name: Enter a name to identify the Webhook you are creating.
    3. Status: Check the status box to activate and make the Webhook available for use.
  2. Click Save. The API interface opens.
Let’s understand the steps to perform different API actions through Webhooks.


 

Performing API Operations using Webhooks

CREATE Operation

Let’s walk through the CREATE operation using the Contacts module as our example in the webhook setup via Postman.

Rules while adding the scripts for the CREATE operation via Webhook:

  • Replace API with WEBHOOK in the script.
  • Add all necessary fields and the operation name in the script.
  • Once the script is done, create a Token to continue the process.

Performing API actions through Webhook requires you to do the following steps:

  • Step 1: Generating a Token in the API Designer
  • Step 2: Using Postman to test an API from the API Designer
 

Step 1: Generating a Token in the API Designer

Follow these steps to generate a Token in the API Designer:

  1. Log in to the CRM account.
  2. Go to the Main Menu.
  3. Go to the Platform.
  4. Select API Designer. The API Designer opens.
  5. Click on +Add API. A pop-up will appear with two options. 
  6. Select Webhook to connect Vtiger with other apps.
  7. Select Create from the Webhook option. 
  8. Enter or select the following mandatory fields:
    1. Module: Select the module you want to work with from the drop-down list.
    2. Name: Enter a name to identify the Webhook you are creating.
    3. Status: Check the status box to activate and make the Webhook available for use.
  9. Click Save. The API interface opens.
 
  1. Add the required fields and specify the operation name for your action in the API interface.
  2. Click on the Security tab on the right side of the API interface.
  3. Click on the Generate New Token icon. The token will be generated and automatically filled in the Token box.

            Note: The token will automatically update when the key icon is clicked.

  1. Select either of the following for Add as:
    1. Header: For Header type, use the Header tab in Postman to add the key.
    2. Query Params: For Query Params, use the Params tab in Postman to enter the key.
​​​​​​​
 

Note: To activate the changes, click Save and Publish before testing the API with the Send option in Postman.


 

Step 2: Using Postman to test an API from the API Designer in Vtiger CRM

To begin testing the API, ensure your Vtiger instance is properly configured in Postman. 

Note: The following steps will be performed in both Postman and Vtiger CRM. Keep both tabs open.

Follow these steps to configure your signed-up Vtiger instance in Postman:

  1. Download and install the latest Postman version for your CRM instance.
  2. Log in to your Vtiger instance.
  3. Click the Settings button.
  4. Click the Edit button to view your username and access key.
  5. Copy your Username and Access Key to a notepad.
  6. Open Postman and click the + icon to create a new request tab.
  7. Select the HTTP method based on the API operation you want to perform.
  8. Navigate to the Authorization tab in Postman.
  9. Select Basic Auth from the dropdown menu.
  10. Copy your Username from the user profile and paste it into the Username field in Postman.
  11. Copy your Access Key from the user profile and paste it into the Password field in Postman.
  12. Paste your Vtiger instance URL into Postman, followed by the appropriate API endpoint for the action you want to perform.
  13. Click Send to execute the request and view the response.

Once you have configured Postman, you can begin making test requests. 
 

Note: The following steps will be performed in both Postman and Vtiger CRM. Keep both the Postman and the CRM tabs open.

Follow these steps to test your API and create a new record using Postman:

  1. Open Postman.
  2. Go to the Authorization tab in Postman.
  3. Select Basic Auth from the type dropdown.
  4. Enter the Vtiger CRM username and access key as the credentials.
  5. Go to API Designer in Vtiger CRM.
​​​​​​​
 
  1. Copy the Token displayed in the API Designer page.
  2. Go back to Postman.
​​​​​​​
 
  1. Select the Headers tab and type Token in the key column.
  2. Paste the Token you copied earlier into the value column.
  3. Select POST from the method dropdown located beside the URL field in Postman.
  4. Copy the endpoint URL from your API Designer (this should be the API endpoint generated).
​​​​​​​
 
  1. Paste the URL into Postman's request URL field.
  2. Go to the Body tab in Postman.
  3. Choose raw and then select JSON as the format.
​​​​​​​
 
  1. Copy the field structure from your API script into the Key and Value columns in Postman.
  2. Click the Send button in Postman.
​​​​​​​
 

Once the contact is created, you can check the Contacts module, and API Designer - Create Webhook will appear in the Updates tab.

 

UPDATE Operation

Let’s walk through the UPDATE operation using the Leads module as our example in the webhook setup via Postman.

Rules while adding the scripts for the CREATE operation via Webhook:

  • Replace API with WEBHOOK in the script.
  • Add all necessary fields and the operation name in the script.
  • Once the script is done, create a Token to continue the process

Performing API actions through Webhook requires you to do the following steps:

  • Step 1: Generating a Token in the API Designer
  • Step 2: Using Postman to test an API from the API Designer in Vtiger CRM


Step 1: Generating a Token in the API Designer

Follow these steps to generate a Token in the API Designer:

  1. Log in to the CRM account.
  2. Go to the Main Menu.
  3. Go to the Platform.
  4. Select API Designer. The API Designer opens.
  5. Click on +Add API. A pop-up will appear with two options. 
  6. Select Webhook to connect Vtiger with other apps.
  7. Select Create from the Webhook option. 
  8. Enter or select the following mandatory fields:
    1. Module: Select the module you want to work with from the drop-down list.
    2. Name: Enter a name to identify the Webhook you are creating.
    3. Status: Check the status box to activate and make the Webhook available for use.
  9. Click Save. The API interface opens.
​​​​​​​
 
  1. Add the required fields and specify the operation name for your action in the API interface.
  2. Click on the Security tab on the right side of the API interface.
  3. Click on the Generate New Token icon. The token will be generated and automatically filled in the Token box.
  4. Select either of the following for Add as:
    1. Header: For Header type, use the Header tab in Postman to add the key.
    2. Query Params: For Query Params, use the Params tab in Postman to enter the key.
​​​​​​​​​​​​​​
 

Note: To activate the changes, click Save and Publish before testing the API with the Send option in Postman.

 

Step 2: Using Postman to test an API from the API Designer in Vtiger CRM

Note: Keep both the Postman and the CRM tabs open.

Follow these steps to test your API and update a record using Postman:

  1. Open Postman.
  2. Go to the Authorization tab in Postman.
  3. Select Basic Auth from the type dropdown.
  4. Enter the Vtiger CRM username and access key as the credentials.
  5. Go to API Designer in Vtiger CRM.
​​​​​​​
 
  1. Copy the Token displayed in the API Designer page.
  2. Go back to Postman.
​​​​​​​
 
  1. Select the Headers tab and type Token in the key column.
  2. Paste the Token you copied earlier into the value column.
  3. In Postman, from the dropdown beside the URL bar, select POST as the request method.
  4. Copy the endpoint URL from your API Designer (this should be the API endpoint generated).
​​​​​​​
 
  1. Paste the URL into Postman's request URL field.
  2. Go to the Body tab in Postman.
  3. Choose raw and then select JSON as the format.
  4. Copy the field structure from your API script.
  5. Click the Send button in Postman.
​​​​​​​
 

You can verify the record was updated via the webhook action by reviewing the details tab of that record.

 

GET Operation

Let’s walk through the GET operation using the Contacts module as our example in the webhook setup via Postman.

Rules while adding the scripts for the GET operation via Webhook:

  • Replace API with WEBHOOK in the script.
  • Add all necessary fields and the operation name in the script.
  • Once the script is done, create a Token to continue the process

Performing API actions through Webhook requires you to do the following steps:

  • Step 1: Generating a Token in the API Designer
  • Step 2: Using Postman to test an API from the API Designer in Vtiger CRM
 

Step 1: Generating a Token in the API Designer

Follow these steps to generate a Token in the API Designer:

  1. Log in to the CRM account.
  2. Go to the Main Menu.
  3. Go to the Platform.
  4. Select API Designer. The API Designer page opens.
  5. Click on +Add API. A pop-up will appear with two options. 
  6. Select Webhook to connect Vtiger with other apps.
  7. Select Create from the Webhook option. 
  8. Enter or select the following mandatory fields.
    1. Module: Select the module you want to work with from the drop-down list.
    2. Name: Enter a name to identify the Webhook you are creating.
    3. Status: Check the status box to activate and make the Webhook available for use.
  9. Click Save. The API interface opens.
​​​​​​​
 
  1. Add the required fields and specify the operation name for your action in the API interface.
  2. Click on the Security tab on the right side of the API interface.
  3. Click on the Generate New Token icon. The token will be generated and automatically filled in the Token box.
  4. Select either of the following for Add as:
    1. Header: For Header type, use the Header tab in Postman to add the key.
    2. Query Params: For Query Params, use the Params tab in Postman to enter the key.
​​​​​​​​​​​​​​
 

Note: To activate the changes, click Save and Publish before testing the API with the Send option in Postman.


 

Step 2: Using Postman to test an API from the API Designer in Vtiger CRM

Note: Keep both the Postman and the CRM tabs open.

Follow these steps to test your API and retrieve information using Postman:

  1. Open Postman.
  2. Go to the Authorization tab in Postman.
  3. Select Basic Auth from the type dropdown.
  4. Enter the Vtiger CRM username and access key as the credentials.
  5. Go to API Designer in Vtiger CRM.
​​​​​​​
 
  1. Copy the Token displayed in the API Designer page.
  2. Go back to Postman.
​​​​​​​
 
  1. Select the Headers tab and type Token in the key column.
  2. Paste the Token you copied earlier into the value column.
  3. In Postman, from the dropdown beside the URL bar, select POST as the request method.
  4. Copy the endpoint URL from your API Designer (this should be the API endpoint generated).
​​​​​​​
 
  1. Paste the URL into Postman's request URL field.
  2. Go to the Body tab in Postman.
  3. Choose raw and then select JSON as the format.
  4. Copy the field structure from your API script.
  5. Click the Send button in Postman.
​​​​​​​
 

The retrieved contact information will be visible after running the GET operation.

Related articles
Automation - Workflow Action - Webhook Rest API Manual Configuration - Usage Details May 2021 July 2021
Home Privacy Policy Terms of Service Security Center Policy & Legal Center Contact Us
© Copyright 2025 Vtiger. All rights reserved.
Powered by Vtiger
Facebook Twitter Linkedin Youtube