Introduction

Vtiger Cloud offers REST-friendly API for integration with 3rd-party-applications. API accepts form-encoded request bodies with basic authentication as a header for security.

Limits per Edition

You can trigger a certain number of API calls per day/per user based on the Edition. For more details, click here.

Essentials

Endpoint

The base URL or endpoint of API will be specific to your CRM instance.  Example: https://your_instance.odx.vtiger.com/restapi/v1/vtiger/default

Authentication

Restapi expects your (username and accesskey) details. Authentication to the API is performed via HTTP Basic Auth. 
Accesskey information is a random token generated for each user and made available under My Preferences on the Web UI.

Response

HTTP response code 200 indicates the successful execution of the API. The response body will be in JSON format.

{    success: true,    result: json_result}

Error

HTTP response code 400 indicates execution failure of the API. An error message is also stated along the header line.
Other HTTP response codes like 500 etc.. should be considered a failure to serve the request.

Record Id

Restapi uses a composite key to represent record id, a combination of (module-type-id and module-record-id) separated by (x).

APIs

Me

Authentication can be confirmed using this API before using any other operation. Response to this API can come in handy when user-reference-id is required.

GET endpoint/me

Response

{    success: true,    result: {        id: user_record_id,        user_name: string,        first_name: string,        last_name: string,        email1: string    }}

ListTypes

You can get details about the module accessible to users through this API.

GET endpoint/listtypes?fieldTypeList=nullParameters

fieldTypeList - filter modules by field type available in the that modules. If you want to see all then pass null.For example you want to see which modules has "grid" type of fields then you can pass like belowendpoint/listtypes?fieldTypeList[]=grid

Response

{    success: true,    result: {        types: [            module_name        ],        information: {            module_name: {                isEntity: boolean,                label: string,                singular: string            }        }    }}

Describe

Metadata of module provides information about record-permissions, blocks, field configuration for performing operation further.

GET endpoint/describe?elementType=moduleName

Response

{    success: true,    result: {        label: string,        name: string,        createable: boolean,        updateable: boolean,        deleteable: boolean,        retrieveable: boolean,        fields: [            name: string,            label: string,            mandatory: boolean,            quickcreate: boolean,            summaryfield: boolean,            headerfield: boolean,            default: value,            type: {                name: string,                length: size,                refersTo: reference_modulename_array,                picklistValues: value_label_array,                defaultValue: picklist_default_value            }            isunique: boolean,            nullable: boolean,            editable: boolean,            data: extended_info        ],        inactivefields: field_information_array,        idPrefix: module_id_string,        isEntity: boolean,        allowDuplicates: boolean,        labelFields: string_or_array        ...    }}

Create

This API enables you to create a single entity record. You are expected to send all the mandatory field values along with the optional fields for successful record creation. (Use Describe API to know more about the field mandatory configuration).

POST endpoint/createelementType=moduleNameelement=convert_into_json_string ({field1: value1, field2=value2})

Response

{    success: true,    result: {        id: record_id,        label: string,        field1: value1        field2: value2        ...    }}

NOTE:

• Most entity records expect the Assigned To (assigne_user_id) field value to be set. This value can be set to user_record_id obtained through Me API.

Retrieve

You can pull a piece of specific record information using this API.

GET endpoint/retrieve?id=record_id

Response

{    success: true,    result: {        id: record_id,        label: string,        field1: value1,        field2: value2,        ...    }}

Decrypt

Use this API when you want to extract the value of a sensitive field of a record.

GET endpoint/decrypt?id=record_id&fieldname=field_name

Response

{    success: true,    result: field_value}

Update

When you intend to update specific fields of existing records, you can use this or Revise API.

Note: This API expects all the mandatory fields to be re-stated as part of the element parameter.

POST endpoint/updateelement=convert_into_json_string({id:record_id, field1:revalue1, field2:value2})

Response

{    success: true,    result: {        id: record_id,        label: string,        field1: revalue1,        field2: value2,        ...    }}

Revise

This is similar to Update API but relaxes the constraint of re-stating the mandatory fields but expects target fields that need to be updated.

POST endpoint/reviseelement=convert_into_json_string({id:record_id, field2:revalue2})

Response

 {    success: true,    result: {        id: record_id,        label: string,        field1: value1,        field2: revalue2,        ...    }}

Delete

Delete existing records through this API.

POST endpoint/deleteid=record_id

Response

{    success: true,    result: {        status: "successful"    }}

Query

Retrieve one or more records matching filtering field conditions.

GET endpoint/query?query=query_string

query_string

select * | field_list | count(*) from module where conditionsorder by field_list limit m, n;

Here

• field_list: should be comma-separated list of fieldname.
• conditions can have expression having
  • operators: <, >, <#, >#, #, !#
  • clauses: in ( ), like ‘sql_regex’
• limit m, n: m representing offset, n representing count.

Response

{    success: true,    result: array_of_matching_records}

Note: 

• Queries will be enforced with an implicit maximum limit of 100 per fetch.
• Joins are not supported across different modules.

Sync

When you need to fetch records that changed their state from the last-known time, you can use this API.

GET endpoint/sync?modifiedTime=timestamp&elementType=moduleName&syncType=sync_type

modifiedtime

• Last known modified time from where you expect state changes of records should be in UNIX timestamp. For example 1561718898

syncType

• user: fetch records restricted to assigned owner of record.
• userandgroup: fetch records restricted to assigned owner of own’s group.
• application: fetch records without restriction on assigned owner.

elementType

• Target module name that you are interested state.

Response

{    success: true,    result: {        updated: record_id_array,        deleted: record_id_array,        more: boolean,        lastModifiedTime: timestamp    }}

NOTE: Maximum of 200 records are returned within the array.

Convert Lead

Use this API to achieve lead conversion.

POST endpoint/convertleadelement=convert_into_json_string({    leadId: [record_id],     entities:{        Contacts: {create: true, name: "Contacts"},        Accounts: {create: true, name: "Accounts"}        Potentials:{create: true, name: "Potentials", "closingdate":"YYYY-MM-DD"}    }})

Response

{    success: true,    result: {        "Accounts": account_id,        "Contacts": contact_id,        "Potentials": potential_id    }}

NOTE: You cannot link the lead to an existing Opportunity.

Related Types

What relationship a module has with others can be obtained through this API.

GET endpoint/relatedtypes?elementType=moduleName

Response

{    success: true,    result: {        types: module_name_array,        information: {            module_name: {                name: string,                label: string,                translated_label: string,                isEntity: boolean,                relation_id: integer,                actions: string            }        }    }}

Retrieve Related

When you need related records of a target, record this API to go with.

GET endpoint/retrieve_related?id=record_id&relatedLabel=target_relationship_label&relatedType=target_moduleName

Response

{    success: true,    result: related_record_array}

Query Related

Fetch related records matching a search criteria using this API.

GET endpoint/query_related?query=query_string&id=record_id&relatedLabel=target_moduleName

Response

{    success: true,    result: matching_related_record_array}

Add Related

Establish a relationship between the two records.

POST endpoint/add_relatedsourceRecordId=record_idrelatedRecordId=target_record_idrelationIdLabel=target_relation_label

Response

{    success: true,    result: {        message: "successful"    }}

Delete Related

When you are looking to break the existing relationship between two records, you can use this API.

POST endpoint/delete_relatedsourceRecordId=record_idrelatedRecordId=target_record_id

Response

{    success: true,    result: {        status: "successful"    }}

Reopen

Reopen closed record if permitted.

POST endpoint/reopen?id=record_id

Response

{    success: true,    result: {        message: "Record reopened successfully."    }}

Tags Add

Add tags to the target record.

POST endpoint/tags_addid=record_idtags=convert_into_json_string(["tag1", "tag2"])

Response

{    success: true,    result: {        message: "tags added"    }}

Tags Retrieve

Fetch tags applied on target record.

GET endpoint/tags_retrieve?id=record_id

Response

{    success: true,    result: {        tags: tag_name_array    }}

Tags Delete

Drop tag(s) applied on the target record or across all records.

POST endpoint/tag_deleteid=record_idtags=convert_into_json_string(["tag"])delete_all=boolean

Response

{    success: true,    result: {        message: "tags deleted"    }}

Files Retrieve

This special API lets you pull the content of the linked image (Contacts, Products) that are not embedded as part of the record.

GET endpoint/files_retrieve?id=resource_id

resource_id

• You obtain this value through record retrieve (example: imageattachmentids field value of Contacts module record).

Response

{    success: true,    result: {        fileid: file_record_id,        filename: string,        filetype: mime_type,        filezie: approx_size,        filecontents: base64_encoded_string    }}

Lookup

This API enables you to search records with a phone or email id in different modules and fields.

Rest API:
GET endpoint/lookup?type=phone&value=2861166887&searchIn={“Contacts”:[“mobile”,”phone”]}

type : phone / email
value : search value
searchIn : Module and fieldname to search

Webservices:

/webservice.php?operation=lookup&type=phone&value=343459844566&sessionName={session_name}&searchIn={“module_name”:[“field_names”]}

Get Account Hierarchy

Accounts can be linked to parent Accounts and hence form a hierarchy. Information about this hierarchy can be retrieved through this API.

GET endpoint/get_account_hierarchy?id=record_id

Response

{    success: true,    result: [        {            id: target_record_id,            name: record_label,            label: Org | Parent Org            level: depth            current: boolean        }    ]}

Search for Phone or Email address

You can look up for Phone or email address in the CRM.

GET endpoint/lookup?type=phone&value=xxx&searchIn={"Contacts":["mobile","phone"]}

Parameters

1. type - either phone or email
2. value - search value (we are looking for exact string)
3. searchIn - optional Json string with one or more module names and optional fields to search the value. You can also just pass module name like {“Contacts”} and it will search in all the fields of Contacts.

Response

{    success: true,    result: [        {            firstname:xxxxx,                            lastname:zzzzzz,                            email:xx@ccc.com                            phone:1234567890                            .....         }    ]}

NOTE: You can use a webservice endpoint that supports session-based operation, which works better for repeated operation.

Quick Reference

CRM Modules

List of default CRM modules exposed by the API. Alternatively, you can use “listtypes” API to get all the standard and custom modules available in your account.

Module ID

Standard module ID uses “listtypes” to get a more accurate value on your account.

Limitation

• Sync does not work on the user’s module And non Entity modules like Currency, Groups, etc.

• The query does not work on non Entity modules like Currency, Groups, etc.