Rest API for Vtiger CRM

25 جولای, 20200 کامنت راهنما و مستندات آموزشی مرکز تلفن ویپ 3CX

REST friendly API for integrating 3rd party apps with Vtiger CRM Cloud edition.

Content

Rest API Manual

Limits per Edition
Essentials

Endpoint

Authentication
Response
Error
Record Id

APIs

Me
ListTypes
Describe
Create
Retrieve
Decrypt
Update
Revise
Delete
Query
Sync
Convert Lead
Related Types
Retrieve Related
Query Related
Add Related
Delete Related
Reopen
Tags Add
Tags Retrieve
Tags Delete
Files Retrieve
Lookup
Get Account Hierarchy
Search for Phone or Email address

Quick Reference

CRM Modules
Module ID

Limitation


Rest API Manual

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

Limits per Edition

You can trigger a certain number of API call per day/per users 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 preformed via HTTP Basic Auth.

Accesskey information is random token generated for each user and made available under My Preferences on the Web UI.

Response
HTTP response code 200 indicates 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. Error message is also stated along the header line.
Other HTTP response code like 500 etc.. should be considered as failure to serve the request.

Record Id
Restapi uses composite key to represent record id, which is 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 of 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 user through this API.

GET endpoint/listtypes?fieldTypeList=null

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 single entity record. You are expected to send all the mandatory field value along with optional field 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 record expect Assigned To (assigne_user_id) field value be set. This value can be set to user_record_id obtained through Me API.


Retrieve

You can pull a 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

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

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

Response

{
success: true,
result: field_value
}


Update
When your intent is to update specific fields of existing record you can use this or Revise API.

NOTE: This API expects all the mandatory fields 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 record through this API.

POST endpoint/delete

id=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 conditions
order by field_list limit m, n;

Here

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

{
success: true,
result: array_of_matching_records
}

NOTE:

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


Sync
When you are in need of fetching records that changed their state from 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 are expecting state changes of records, it should be in unix time stamp. For example 1561718898
sync_type

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 other 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 relation between 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 existing relationship between two record 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."
}
}


Tags Add

Add tags to 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 content of linked image (Contacts, Products) that are not embedded as part of 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 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 Account 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 lokking 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 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.

 

Description Name
The Calendar module is used to Manage To Dos , Events and Meetings. Calendar
The Leads module is used to track Sales leads. Leads
The Accounts module is used to Manage individual or organizations involved in your business. Accounts
The Contacts module is used to Manage individuals, who may be associated with an Account. Contacts
The Potential module is used to Manage Sales Opportunity. Potentials
The Products module is used to Manage the product that your organization sales. Products
The Documents module is used to Manage the uploaded Documents and Notes. Documents
The Emails module is an email client used to manage your emails. Emails
The HelpDesk module is used to track customer issues such as feedback, problems etc. HelpDesk
The FAQ module is used to manage the frequently asked question by your customer. Faq
The Vendors Module is used for managing Manufacturers. Vendors
The PriceBook Module is used for managing the pricing of products. PriceBooks
The Quotes Module is used for managing the Quotes for products. Quotes
The PurchaseOrder module is used for managing the PurchaseOrders. PurchaseOrder
The SalesOrder module is used for managing the SalesOrders. SalesOrder
The Invoice module is used for creating invoice reports. Invoice
The Campaigns module is used for managing Marketing Campaigns. Campaigns
The Events module is used for Managing Activities such as Calls and Meetings. Events
The Users module is used for managing the CRM users. Users
Users groups on the vtiger CRM. Groups
Currency module lets the administrator to 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. Currency
The DocumentFolders module is used to Groups Documents. DocumentFolders

 


Module ID

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

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


Limitation

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

 

 

لطفا امتیاز دهید.
0 از 0

نوشته مرتبط