Sign In
  • Logout
    Home  >   Articles   >  Rest API Manual
    Articles in this section
    Access CRM data offline via Vtiger 360 Accessing your Vtiger CRM data via OData feed Kanban View of Deals Calendar View Capturing Emotional Journeys Closed States Customer Touchpoints Customizer Desktop Notification overview Exporting Data from Vtiger CRM Feature Limits Glossary How do I scan a Business Card in Vtiger 360 mobile App IP Based Restriction Introduction to Kanban View Make the leap from Spreadsheets Merging Duplicates in Summary View Migration Timeframe and Process One View: Introduction Overview of Permission Usecases Performing Global Search Top Salespersons Understand the Billing Process in Vtiger Using Comments and @mentions Vtiger 360 for Field Sales Vtiger 360 Mobile App What are Contact Roles What are Record-Level Analytics What are Sticky Notes What is List View Whitelisting Vtiger on Google to use Gmail Sync What is Quick Create Summary View Built-in Phone Dialer in the CRM with Plivo and Twilio Embedding a Video URL Course Completion Certificates Customizing a Course Category Internal Chat Vtiger SAML application in Azure AD Applicable Taxes for Vtiger Billing Using Grid Edit in Vtiger CRM Auto Forward Emails from Individual & Group Mail Boxes Understanding Email Bounces and Error Codes

    Rest API Manual

    B
    Bindu Rekha Babu
    13 Dec, 2022 - Updated 1 month ago
    Table of Contents

    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 below
    endpoint/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/create?elementType=moduleName&element=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/update?element=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/revise?element=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/convertlead?element=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_related?sourceRecordId=record_id&relatedRecordId=target_record_id&relationIdLabel=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_related?sourceRecordId=record_id&relatedRecordId=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."
    }
    }


    PicklistDependency

    You can get dependency between two picklist fields.
     
    GET endpoint/picklist_dependency?module=moduleName&&sourcefield=sourceFieldName&targetfield=targetFieldName


    Response
    {
    success: true,
    result: {
    sourcefield: string,
    targetfield: string,
    valuemapping : [
    {
    sourcevalue : string,
    targetvalues: [
    string,
    string,
    ...
    ]
    },
    {
    sourcevalue : string,
    targetvalues: [
    string,
    string,
    ...
    ]
    },
    ...
    ]
    }
    }


    Tags Add

    Add tags to the target record.
     
    POST endpoint/tags_add?id=record_id&tags=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_delete?id=record_id&tags=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
    type - either phone or email
    value - search value (we are looking for exact string)
    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.
     
    Name Description
    Calendar The Calendar module is used to manage To Dos, Events, and Meetings.
    Leads The Leads module is used to track sales leads.
    Accounts The Accounts module is used to manage individuals or organizations involved in your business.
    Contacts The Contacts module is used to manage individuals associated with an Account.
    Potentials The Potential module is used to manage sales opportunities.
    Products The Products module is used to manage the product that your organization sells.
    Documents The Documents module is used to manage the uploaded documents and notes.
    Emails The Emails module is an email client used to manage your emails.
    HelpDesk The HelpDesk module is used to track customer issues such as feedback, problems, etc.
    Faq The FAQ module is used to manage the frequently asked question by your customer.
    Vendors The Vendors module is used for managing manufacturers.
    PriceBooks The PriceBook module is used for managing the pricing of products.
    Quotes The Quotes module is used for managing the Quotes for products.
    PurchaseOrder The Purchase Order module is used for managing the Purchase Orders.
    SalesOrder The SalesOrder module is used for managing the SalesOrders.
    Invoice The Invoice module is used for creating invoice reports.
    Campaigns The Campaigns module is used for managing Marketing Campaigns.
    Events The Events module is used for managing activities such as Calls and Meetings.
    Users The Users module is used for managing the CRM users.
    Groups Users groups on the vtiger CRM.
    Currency The Currency module lets the administrator define different currencies and set the expected conversion rate with respect to the base currency. These currencies can be used in Inventory modules to support multi-currency.
    DocumentFolders The DocumentFolders module is used to Groups Documents.
     

    Module ID

    Standard module ID uses “listtypes” to get a more accurate value on your account.
     
    Module Name ID number
    Accounts 3
    Assets 27
    Calendar 1
    Campaigns 17
    Cases 39
    CampanyDetails 26
    Contacts 4
    Currency 21
    DocumentFolders 22
    Documents 7
    EmailCampaigns 37
    Emails 8
    Events 18
    Faq 10
    Groups 20
    HelpDesk 9
    Invoice 16
    Leads 2
    LineItem 33
    ModComments 28
    Olark 40
    PBXManager 24
    Potentials 5
    PriceBooks 12
    PrintTemplates 41
    Products 6
    ProductTaxes 35
    Project 31
    ProjectMilestone 29
    ProjectTask 30
    PurchaseOrder 14
    Quotes 13
    SalesOrder 15
    ServiceContracts 23
    Services 25
    SLA 38
    Tax 34
    Users 19
    Vendors 11
     

    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.

    Enhancement

    • You can now enable APIs to create multiple records with a single REST API. This helps in creating multiple module records at the same time. ​​​​​​
    Was this article helpful?
    9  out of  21  found this helpful.
    Comments 0
    Be the first to comment
    Home
    Privacy Policy
    Terms of Service
    Security Center
    Policy & Legal Center
    Contact Us
    © Copyright 2022 Vtiger. All rights reserved.
    Powered by Vtiger