Third Party App Integration (REST APIs)

REST APIs (Webservices)

Take advantage of REST APIs exposed over HTTP(s) to push or pull data from Vtiger and integrate with 3rd party applications. You are certainly free to choose the library of your choice to work with these APIs. vtwsclib provides support to work with REST APIs through various programming languages.

Section below covers more details on the APIs:

Request Format

HTTP - GET / POST

application/x-www-form-urlencoded

Response Format

Success

{
        success: true,
        result: {
                // ...
        }
}

Failure

{
        success: false,
        error: {
                message: String,
                code:    String
        }
}

Login Operation

Its a two-step process that involves getting the challenge token and exchanging the credentials (username and accessKey). You can find accessKey information under “My Preferences” in the CRM Web UI.

Challenge

GET /webservice.php?operation=getchallenge&username=<USERNAME> HTTP/1.1

Challenge Response

{
        success: true,
        result: {
                token: TOKENSTRING,    // Challenge token to be used for login.
                serverTime: TIMESTAMP, // Current Server time
                expireTime: TIMESTAMP  // Time when token expires
        }
}

Login

POST /webservice.php HTTP/1.1

operation=login
username=<USERNAME>
accessKey=md5(TOKENSTRING + <ACCESSKEY>) // Note: accessKey= K here is capitalized.

Response

{
        success: true,
        result: {
                sessionName:    String, // Unique Identifier for the session (sessionId)
                userId:         String, // User ID in CRM
                version:        String, // Webservice API version
                vtigerVersion:  String  // Version of CRM
        }
}

Logout Operation

POST /webservice.php HTTP/1.1

operation=logout
sessionName=sessionId // Obtained through Login Operation

List Types Operation

GET /webservice.php?operation=listtypes&sessionName=sessionId HTTP/1.1

Describe Operation

GET /webservice.php?operation=describe&sessionName=sessionId&elementType=<TYPE> HTTP/1.1

Create Operation

POST /webservice.php HTTP/1.1

operation=create
sessionName=sessionId        // Obtained through Login Operation
element=URLENCODED(JSONDATA) // JSONDATA - JSON Map of (fieldname=fieldvalue)
elementType=<TYPE>           // TYPE - Module Name

Retrieve Operation

GET /webservice.php?operation=retrieve&sessionName=sessionId&id=<WEBSERVICE_ID> HTTP/1.1

Update Operation

POST /webservice.php HTTP/1.1

operation=update
sessionName=sessionId    // Obtained through Login Operation
element=URLENCODED(DATA) // DATA - Map of (fieldname=fieldvalue)

Delete Operation

POST /webservice.php HTTP/1.1

operation=delete
sessionName=sessionId    // Obtained through Login Operation
id=<WEBSERVICE_ID>

Query Operation

GET /webservice.php?operation=query&sessionName=sessionId&query=<QUERY> HTTP/1.1

<QUERY>

FORMAT:

SELECT * | <column_list> | <count(*)>
FROM <object>
[WHERE <conditionals>]
[ORDER BY <column_list>]
[LIMIT [<m>, ] <n>]

<column_list>	Comma separated list of field names.
<object>	Type or Module Name.
<conditionals>	<condition_operations> or <in_clauses> or <like_clauses> separated by ‘and’ or ‘or’ operators these are processed from left to right. The are no grouping that is bracket operators.
<condition_operations>	<, >, <=, >=, =, !=
<in_clauses>	in ()
<like_clauses>	like ‘sqlregex’
<value_list>	a comma separated list of values.
m, n	integer values to specify the offset and limit respectively.

LIMITATIONS

• Queries are currently limited to a single object.

• Joins are not supported.

• Query always limits its output to 100 records, Client application can use limit operator to get different records.

Sync Operation

GET /webservice.php?operation=sync&sessionName=sessionId&modifiedTime=<TIMESTAMP>&elementType=<TYPE> HTTP/1.1

Extend Session Operation

GET /webservice.php?operation=extendsession HTTP/1.1