Create Lead API

Document Information
Created by:

Ben Lazarev

Creation date:

13-Nov-2013

File name:

create Lead API

Document type:

API documentation

Confidentiality:

Confidential

Document Status

Version

Status

Set by

Date

1.0.0

1st
draft

Ben Lazarev

13-Nov-2013

1.01

Update fields

Gilad tabachnik

2-Apr-2015

Contents
Introduction
Overview
Scope & Audience
Terms, Acronyms & Abbreviations
Applicable Documents
General
Response Object
Error Object
General Flow
Authentication
Get Challenge
GetChallengeResult
Login
Create New Lead Entity
Create Lead example
Parameters List

1.

Introduction

1.1. Overview
Currently Lead can be created in two ways, using Webform and from the CRM list view . Panda will
provide API to create Lead from external server.

1.2. Scope & Audience

The document provides a detailed description and examples of using provided by Panda API for CRM
Lead Entity creation.
The audience of this document is the customers technical team and Pandas management team.

1.3. Terms, Acronyms & Abbreviations

REST
- API is REST based, so all the communication b/w client and server can happen over
HTTP as GET or POST requests.
JSON
- JSON is used to encode response and request.
Requests And Responses
- Your client application prepares and submits a service request to
the API, the API processes the request and returns a response, and the client application
handles the response.

1.4. Applicable Documents

N/A

2. General
2.1. Response Object
All responses will have the following format. If the request is processed successfully:
<code>Response{
success:Boolean=true
result:Object//TheOperationResultobject
}
</code>

If there is a failure while processing the request,

<code>Reponse{
success:Boolean=false
error:ErrorObject
}
</code>

2.2. Error Object

<code>ErrorObject{
errorCode:String//Stringrepresentationoftheerrortype
errorMessage:String//Errormessagefromtheapi.
}
</code>

errorCode is a string representation of the error type.

3. General Flow
In order to create a new CRM Lead entity, there are several preconditions to be met and several steps
to perform:

3.1. Authentication
The API does not use the password to log in. Instead, Vtiger provides a unique access key for each
user. To get the user key for a user, login to CRM and navigate to My Preferences pane of that user
using which you logged in . You will find an Access Key field with value to be used.
Login starts a client session with server, authenticates the user and returns a sessionId which will be
used for all the subsequent communication with the server.
Logging in is a two-step process, In the first step client obtains the challenge token from the server,
which is used along with the user's access key to log in.

3.1.1. Get Challenge

So, the first step is obtaining a challenge string to be used in the authentication process.
<-CRM Link->/webservice.php?operation=getchallenge&username=user
Example :
http://123.123.21.54/webservice.php?operation=ge
tchallenge&username=user
GetChallengeResult
An object representing the response result of a getchallenge operation,
<code>GetChallengeResult{
token:String//Challengetokenfromtheserver.
serverTime:TimeStamp//Thecurrentservertime.
expireTime:TimeStamp//Thetimewhenthetokenexpires.
}
</code>

Now that we have the challenge token we can go ahead with the login. The access key field in the
login operation is the md5 checksum of the concatenation of the challenge token and the users own
access key.

3.1.2. Login
Logintotheserverusingthechallengetokenobtainedingetchallengeoperation

The login operation, as opposed to getchallenge, is a post request.

<-CRM_Link->/
webservice.php?operation=login&username=[username]&accessKey=[access
Key]

Example:

http://123.123.21.54/webservice.php?operation=login&username=panda&accessKey=KntFVnh7FvXy
aloP

ForaccessKeycreateamd5stringafterconcatenatinguseraccesskeyfrommypreferencepageandthe
challengetokenobtainedfromgetchallengeresult.

$generatedKey = md5($challengeToken.$userAccessKey);
Login example:
<code>//e.g.
//accesskeyoftheuser,foundonmypreferencespage.
$userAccessKey=
QsRvAuzZYAt6yp1h

//createmd5stringconcatenatinguseraccesskeyfrommypreferencepage
//andthechallengetokenobtainedfromgetchallengeresult.
$generatedKey=md5($challengeToken.$userAccessKey)
//loginrequestmustbePOSTrequest.
$httpc>post("$endpointUrl",
array('operation'=>'login','username'=>$userName,
'accessKey'=>$generatedKey),true)
$response=$httpc>currentResponse()
//decodethejsonencoderesponsefromtheserver.
$jsonResponse=Zend_JSON::decode($response['body'])

//operationwassuccessfulgetthetokenfromthereponse.
if($jsonResponse['success']==false)
//handlethefailurecase.
die('loginfailed:'.$jsonResponse['error']['errorMsg'])

//loginsuccessfulextractsessionIdanduserIdfromLoginResulttoitcanused
forfurthercalls.
$sessionId=$jsonResponse['result']['sessionName']
$userId=$jsonResponse['result']['userId']


</code>

Login Result
Anobjectrepresentingtheresponseresultofaloginoperation,

<code>LoginResult{
sessionId:String//UniqueIdentifierforthesession
userId:String//Thevtigeridfortheloggedinuser
version:String//Theversionofthewebservicesapi
vtigerVersion:String//Theversionofthevtigercrm.
}
</code>

3.2. Create New Lead Entity

In order to create a new Lead all mandatory fields needs to be filled and the following webservice
needs to be invoked:
http://123.123.21.54/webservice.php?operation=create&sessionName=$sessionID&element=[NewLead
DATA]&elementType=Leads

3.2.1. Create Lead example

$endpointUrl ="http://123.123.21.54/webservice.php";
$userName="User";
$response = curl_post("$endpointUrl?operation=getchallenge&username=$userName");
$jsonResponse = json_decode($response, true);
if($jsonResponse['success'] == false)
die('getchallenge failed:'.$jsonResponse['error']['errorMsg']);
$challengeToken = $jsonResponse['result']['token'];
$userAccessKey = 'YourAccessKey';
$generatedKey = md5($challengeToken.$userAccessKey);
$response = curl_post("$endpointUrl",
array('operation'=>'login'
, 'username'=>$userName
, 'accessKey'=>$generatedKey)

);
$jsonResponse = json_decode($response,true);
if($jsonResponse['success']==false)
die('login failed:'.$jsonResponse['success']['error']['message']);
$sessionId = $jsonResponse['result']['sessionName'];
$userId = $jsonResponse['result']['userId'];
$sessionId = $jsonResponse['result']['sessionName'];
$element = array(
email=>test@tes.oom
,assigned_user_id=>19x1
,lastname=>mosh
,firstname=>eli
,mobile=>0568452654
,leadsource=>--None--
);
$objectJson = json_encode($element);
$params = array("sessionName"=>$sessionId
, "operation"=>'create'
, "element"=>$objectJson
, "elementType"=>Leads
);
$response = curl_post($endpointUrl,$params);
$arr_response = json_decode($response,true);

3.3. Parameters List

Mandatory fields:
API parameter

Orginal field /description

email

Lead Email Address

assigned_user_id

The user Id that recived from login request - can

be change to diffrent user :
For example : user id 134 the value will be
19x134

lastname

Lead Last name

firstname

Lead first name

Optional fields :
phone

phone number

mobile

mobile number

fax

fax number

leadstatus

Lead Status

leadsource

source name

lane

Street

code

Postal Code

city

City

country

Country

state

State

pobox

Po Box

description

Description

affiliate

Affiliate