Company

With company module user can add and delete companies. More features are added on need basis.

---

Command: ADD

With add command you can add a new single company to leaddesk database.

Parameters:

Name	Type	Mandatory	Description	Example
name	string	yes	Company’s name	SellMore Ltd
vatin	integer or string	no	Company’s VAT identification number	12345780, 12345678-0
www	string	no	Company’s home page	www.sellmore.biz
address	string	no	Company’s street address	Lotsaselling Rd. 4
postcode	string	no	Company’s postal code	65789
city	string	no	Company’s city	Sellington
country	string	no	Company’s country	England

Possible errors:

Error	Description
ERR_INVALID_ARGUMENT	Company name is invalid
ERR_ARGUMENT_MISSING	Mandatory parameter was missing

Success:
By default returns JSON encoded object with http status 200: {“companyid”:1234,”success”:true}

Examples:
Create company with name “Disney Ltd” and vatin “12345678-0”:
http://api.leaddesk.com?auth=X&mod=company&cmd=add&name=Disney%20Ltd&vatin=12345678-0

Create company with name “Disney Ltd” and vatin “12345678-0” and comment “Call ASAP”:
http://api.leaddesk.com?auth=X&mod=company&cmd=add&name=Disney%20Ltd&vatin=12345678-0&comment=Call%20ASAP

Command: DELETE

With delete command one can delete company information from LeadDesk by given company ID.

Parameters:

Name	Type	Mandatory	Description	Example
companyid	integer	yes	Company ID that needs to match LeadDesk company id.	77429

Possible errors:

Error	Description
ERR_NO_COMPANY_FOUND	No company found from LeadDesk with given company id.
ERR_ARGUMENT_MISSING	Mandatory parameter (companyid) was missing

Success:
On success will return JSON string:

  {"success":true}

Examples:
Delete company named “Disney Ltd” with id 1234:
http://api.leaddesk.com?auth=X&mod=company&cmd=delete&companyid=1234

Number_activity

---

Clients can make activity lookup for single phone number. Response is sent to client in separate HTTP call in asynchronous way.

NOTICE: Every request will be invoiced separately.

Command: GET

Only get command is available for module number_activity.

Parameters:

Name	Type	Mandatory	Description	Example
phone_number	string	yes	Phone number (string). Country code needed.	358456789012
response_url	string	yes	URL where lookup results will be sent.	http://client.com/server.php

Response:
When API call is made for phone number response for that call is reference id that can be used to identify actual results of the activity lookup. Actual number activity result is sent to URL given in response_url parameter. Response holds following information as HTTP POST variables:

  original_number: 358452345678
  number: 358452345678
  lookup_reference: 74910-1369126487422
  operator_name: DNA Ltd
  country: Finland
  home_country: Finland
  presence_data: online (cdb-0)
  campaign:
  is_online: yes

Examples:

http://api.leaddesk.com/?mod=number_activity&cmd=get&auth={AUTH}&phone_number=358452345678&response_url=http://client.com/server.php

Activity

The activity module can be used to manage LeadDesk agents’ activities.

---

Command: GET

Returns one activity based on ID Parameters

Name	Type	Description	Mandatory
id	int	Activity id	yes

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ARGUMENT_INVALID	Parameter was invalid
ERR_NOT_FOUND	Activity was not found

Success: On success will return a JSON string in the format of:

 {"id":"<activity_id>","name":"<activity_name>",
"billable":"<0 or 1>","payable":"<0 or 1>","selectable":"<0 or 1>","internal":"<0 or 1>"}

Example: Get the activity with ID 123 http://api.leaddesk.com?auth=X&mod=activity&cmd=get&id=123

Command: FIND

Returns activities based on search criteria. If no search criterion is given, all activities are returned. Parameters

Name	Type	Description	Mandatory
name	string	Activity name	no
billable	boolean (0/1)	Is the activity billable?	no
payable	boolean (0/1)	Is the activity payable?	no
selectable	boolean (0/1)	Is the activity selectable?	no

Possible errors:

Error	Description
ERR_ARGUMENT_INVALID	Parameter was invalid

Success: On success will return a JSON string in the format of:

  [{"id":"<activity_id>","name":"<activity_name>","billable":"<0 or 1>",
"payable":"<0 or 1>","selectable":"<0 or 1>","internal":"<0 or 1>"}, {...}, {...}, ...]

Example: Search for a billable activity with the name “Foo”. http://api.leaddesk.com?auth=X&mod=activity&cmd=find&name=Foo&billable=1

Command: UPDATE

Updates an activity. Internal activities cannot be updated. Parameters

Name	Type	Description	Mandatory
id	int	Activity ID	yes
name	string	Activity name	no
billable	boolean (0/1)	Is the activity billable?	no
payable	boolean (0/1)	Is the activity payable?	no
selectable	boolean (0/1)	Is the activity selectable?	no

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	No updateable parameters were given
ERR_ARGUMENT_EMPTY	A parameter value was empty
ERR_ARGUMENT_INVALID	Parameter was invalid

Success: On success will return the number of changed rows Example: Update activity with ID 123, set name to “Foo” and “billable” to “1”. <ahref=”http: api.leaddesk.com=”” ?auth=”X&mod=activity&cmd=update&id=123&name=Foo&billable=1″” rel=”nofollow”>http://api.leaddesk.com?auth=X&mod=activity&cmd=update&id=123&name=Foo&billable=1

Command: ADD

Adds a new activity. Parameters

Name	Type	Description	Mandatory
name	string	Activity name	yes
billable	boolean (0/1)	Is the activity billable?	no
payable	boolean (0/1)	Is the activity payable?	no
selectable	boolean (0/1)	Is the activity selectable?	no

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ARGUMENT_EMPTY	Parameter was empty

Success: On success will return the ID of the inserted activity Example: Add a new billable activity with the name “Foo” http://api.leaddesk.com?auth=X&mod=activity&cmd=add&name=Foo&billable=1

Command: DELETE

Deletes an activity base on ID. Internal activities cannot be deleted. Parameters

Name	Type	Description	Mandatory
id	int	Activity ID	yes

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ARGUMENT_INVALID	Parameter was invalid
ERR_NOT_FOUND	Activity was not found

Success: On success will return the number of deleted rows Example: Delete activity with ID 123 http://api.leaddesk.com?auth=X&mod=activity&cmd=delete&id=123

Command: AGENT_WORKTIME

Returns agent total work time (in seconds) and also campaign specific activity durations (in seconds) for this agent. Limited to time interval of 1 month. Parameters

Name	Type	Description	Mandatory
agent_id	int	Agent id	yes
date_from	string	Time interval start point	yes
date_to	string	Time interval end point. Overrides date_interval if defined. Note: Maximum time interval is 31 days (one month).	no
date_interval	int	Time interval in days. Is ‘1’ by default. Note: Maximum value is 31 (one month).	no

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ARGUMENT_INVALID	Parameter was invalid, or one month limit of maximum time interval was exceeded.

Success: On success will return a JSON array with following structure: ‘total_duration’

  <campaign id #1> => 'name'
                          => 'activities'
                             <activity id #1> => 'name'
                                              => 'duration'
                                              => 'billable'
                                              => 'payable'
                             <activity id #2> => 'name'
                                              ...
         <campaign id #2> => 'name'
                          ...

Example in JSON: {“total_duration”:3600,”campaigns”:{“1”:{“name”:”Worktime campaign”,”activities”:{“24”:{“name”:”worktime1″,”duration”:”3600″,”billable”:”1″,”payable”:”1″}}}}} Example: Get worktime of agent 123 for March 1st 2015: http://api.leaddesk.com?auth=X&mod=activity&cmd=agent_worktime&agent_id=123&date_from=2015-03-01 Get worktime of agent 123 for March 2015: http://api.leaddesk.com?auth=X&mod=activity&cmd=agent_worktime&agent_id=123&date_from=2015-03-01&date_to=2015-03-31 Get worktime of agent 123 for one week starting from Monday 4.5.2015: http://api.leaddesk.com?auth=X&mod=activity&cmd=agent_worktime&agent_id=123&date_from=2015-05-04&date_interval=7

 

 

Contact

the contact module in intended for adding, deleting or modifying contacts.

---

Command: ADD

With add command you can add a new single contact into existing calling list. Also creates a new calling list, if existing list cannot be found and list parameter is a string. Parameters:

Name	Type	Mandatory	Description	Example
phone	string	yes	Phonenumbers for the contact. Numbers are separated by comma. Phone number needs to be at least 3 characters long. Only 4 valid numbers will be added to contact. If more than 4 numbers were given, they will be ignored.	0401234567,+358501234567
list	integer or string	yes	Contact list ID (integer) or name (string). Created contact is added to this list (by id or name). Or new list is created if list with given name is not found. Or exception if this parameter is integer and list cannot be found.	5486
return_value	boolean (0,1)		With this parameter user can select if created contact id should be retuned as result from query. Result is in JSON format: {“contact_id”:8837541,”success”:true}	0
fname	string		Contact’s first name	John
lname	string		Contact’s last name	Smith
email	string		Contact’s email address	john.smith@somedomain.com
www	string		Contact’s home page	www.johnsmith.net
address	string		Contact’s street address	Oakstreet 5
postcode	string		Contact’s postal code	65789
city	string		Contact’s city	London
country	string		Contact’s country	England
ssc	string		Contact’s social security code	121276-3451
birthyear	string		Contact’s year of birth	1976
gender	string		Contact’s gender	male
companyid	integer		Contact’s company id	1234
company	string		Contact’s company name (ignored if company ID is set)	Company Plc
vatin	string		Contact’s company VAT identification number (ignored if company ID is set)	123456780
title	string		Contact’s title	Salesworker
comment	string		Contact’s comment	Notes and additional info
otherX (X = 1…35)	string		Contact’s other info	Sells various magazines
other_labelX (X = 1…35)	string		Contact’s other info label	Job description
order	string or integer		Contact’s running number in the contact list. Values can be: “first” / “last” / 0-100% / {number}. Default value is “last”. Explanations: first: Contact will be set first in the calling list last: Contact will be set last in the calling list 0-100%: Contact will be set by percent from the start. 0% means first, 50% means middle and 100% means last {number}: Contact will be set by order number (integer) in the calling list	first
assign_to_agent	string		Agent id or username.	Assigns contact to an agent

Possible errors:

Error	Description
ERR_NO_NUMBERS	All of the phone numbers were too short.
ERR_NO_LIST	Given calling list does not exist and list parameter is integer.
ERR_NO_COMPANY_FOUND	No company found from LeadDesk with given company id.

Success: By default returns nothing, just an empty HTTP response with status 200. If return_value parameter is set to true, then JSON returned:

  {"contact_id":8837541,"success":true}

Examples: Create Ville Virtanen with number 040111222 and add to contact list 5789: http://api.leaddesk.com?auth=X&mod=contact&cmd=add&fname=Ville&lname=Virtanen&phone=040111222&list=5789 Create Ville Virtanen with 2 numbers and some additional data and add to contact list 5789: http://api.leaddesk.com?auth=X&mod=contact&cmd=add&fname=Ville&lname=Virtanen&phone=040111222,050333444&list=5789&birthyear=1967&gender=male Create Ville Virtanen with number 040111222 and add to contact list “Virtaset” if list by that name exists or create a new one if not: http://api.leaddesk.com?auth=X&mod=contact&cmd=add&fname=Ville&lname=Virtanen&phone=040111222&list=Virtaset

Command: MODIFY

With modify command, user can change single or multiple contacts’ info, like name and address. User needs to know LeadDesk id of the contact(s) in order to modify. With this command it’s possible to add phonenumber for contact(s). If given phonenumber is not found from contact, it will be added as new phonenumber row. If parameter is sent with empty value (lname=Smith&fname=&) then equivalent contact information is set to empty too. If parameter is not defined (not sent at all) then equivalent contact information is left as is. NOTE! You can set “list” parameter to zero (0) to completely remove the contact(s) from its current calling list. NOTE! You can set “companyid” parameter to zero (0) to completely remove company info from contact(s) NOTE! Phone number is not affected by blacklist. Limitations

• The Request Method is POST
  • Contact IDs should be sent in the request body (x-www-form-urlencoded).
  • If you only have few contacts to modify then parameters can be sent as a query parameters in the URL, but bigger amount of contacts will be better to sent in body.
• Maximum amount of contact_ids allowed for processing is currently set to 1000

Parameters:

Name	Type	Mandatory	Description	Example
contact_id	string	yes	Contact IDs that need to match LeadDesk contact ids.	77429,77428,77427,77426
phone	string		Phonenumbers for the contact. Numbers are separated by comma. Phone number needs to be at least 3 characters long.	0401234567,+358501234567
fname	string		Contact’s first name	John
lname	string		Contact’s last name	Smith
email	string		Contact’s email address	john.smith@somedomain.com
www	string		Contact’s home page	www.johnsmith.net
address	string		Contact’s street address	Oakstreet 5
postcode	string		Contact’s postal code	65789
city	string		Contact’s city	London
country	string		Contact’s country	England
ssc	string		Contact’s social security code	121276-3451
birthyear	string		Contact’s year of birth	1976
gender	string		Contact’s gender	male
companyid	integer		Contact’s company id. Set this to zero (0) to completely remove company info from contact.	1234
company	string		Contact’s company name (ignored if company ID is set)	Company Plc
vatin	string		Contact’s company VAT identification number (ignored if company ID is set)	123456780
title	string		Contact’s title	Salesworker
comment	string		Contact’s comment	Notes and additional info
otherX (X = 1…35)	string		Contact’s other info	Sells various magazines
other_labelX (X = 1…35)	string		Contact’s other info label	Job description
list	integer or string		Contact list ID (integer) or name (string). Contact is added to this list (by id or name). Or new list is created if list with given name is not found. You can set this parameter to zero (0) to completely remove the contact from its current calling list.	5486
order	string or integer		Contact’s running number in the contact list.Values can be: “first” / “last” / 0-100% / {number}. Default value is “last”. Explanations: first: Contact will be set first in the calling list last: Contact will be set last in the calling list 0-100%: Contact will be set by percent from the start. 0% means first, 50% means middle and 100% means last {number}: Contact will be set by order number (integer) in the calling list	first
assign_to_agent	string		Agent id or username. With parameter zero (0) contact will be released from any agent.	Assigns contact to an agent

Possible errors:

Error	Description
ERR_NOT_FOUND	No contact found from LeadDesk with given contact id.
ERR_NO_COMPANY_FOUND	No company found from LeadDesk with given company id.
ERR_ARGUMENT_LENGTH	The number of given contact_ids exceeded the maximum limit.

Success: On success will return JSON string:

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

Examples:

  Modify Ville Virtanen with id 7438675:
  <a class="external free" href="http://api.leaddesk.com/?auth=X&mod=contact&cmd=modify&contact_id=7438675&fname=Ville&lname=Virtanen&phone=040111222,050333444&birthyear=1956&gender=male" rel="nofollow">http://api.leaddesk.com?auth=X&mod=contact&cmd=modify&contact_id=7438675&fname=Ville&lname=Virtanen&phone=040111222,050333444&birthyear=1956&gender=male</a>

Command: MODIFY_PHONE

Changes a single phone number based on contact ID and phone number or customer ID. Parameters:

Name	Type	Mandatory	Description	Example
contact_id	integer	yes	Contact ID that needs to match LeadDesk contact id.	77429
customer_id	integer	no	Customer ID that needs to match LeadDesk customer id.	77430
old_phone	string	no	Current phone number	0501234567
new_phone	string	yes	New phone number	0501234568

Possible errors:

Error	Description
ERR_NOT_FOUND:contact_id	No contact found with given contact_id
ERR_NOT_FOUND:old_phone	No phone number found with given old_phone
ERR_NOT_FOUND:customer_id	No phone number found with given customer_id
ERR_UNEXPECTED_PARAMETERS:old_phone	When both customer_id and old_phone are given
ERR_INVALID_FORMAT:new_phone	new_phone is empty, too short, or has invalid format

Success: If the phone number was changed, the following JSON string is returned:

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

If the request is otherwise successful but new_phone already exists for the contact, the following JSON string is returned:

  {"message":"","success":false}

Examples: Change number ‘0501234567’ of contact 77429 to ‘0507654321’: http://api.leaddesk.com?auth=X&mod=contact&cmd=modify_phone&contact_id=77429&old_phone=0501234567&new_phone=0507654321 Change customer 77430 of contact 77429 to ‘0507654321’: http://api.leaddesk.com?auth=X&mod=contact&cmd=modify_phone&contact_id=77429&customer_id=77430&new_phone=0507654321

Command: GET

With get command one can fetch contact information with LeadDesk ID. Parameters:

Name	Type	Mandatory	Description	Example
contact_id	integer	yes	Contact ID that needs to match LeadDesk contact id.	77429

Possible errors:

Error	Description
ERR_NOT_FOUND	No contact found from LeadDesk with given contact id.

Success: On success will return JSON string:

{
"contact_id":102257,
       "data":{
           "id":"102257",
           "fname":"Teuvo",
           "lname":"Testaaja",
           "office":"R&D",
           "vatin":"07863101",
           "email":"teuvo.testaaja@email.com",
           "title":"Title",
           "ssc":"100000-111S",
           "year_of_birth":"1995",
           "gender":"Male",
           "address":"Main Street 15",
           "postal":"55555",
           "country":"Finland",
           "city":"Lappeenranta",
           "other_info_ft":"OI1_6",
           "other_info_sec":"OI2_6",
           "other_info_thir":"OI3_6",
           "other_info_4":"OI4_6",
           "other_info_5":"OI5_6",
           "other_info_6":"OI6_6",
           "comment":"Comment_6",
           "client_id":"1437",
           "created_at":"2016-11-02 12:44:46",
           "updated_at":"",
           "batch_name":"",
           "phone":"DEPRECATED, DO NOT USE. Instead use field "phonenumbers"",
           "sec_phone":"DEPRECATED, DO NOT USE. Instead use field "phonenumbers"",
           "thr_phone":"DEPRECATED, DO NOT USE. Instead use field "phonenumbers"",
           "fourth_phone":"DEPRECATED, DO NOT USE. Instead use field "phonenumbers"",
           "fax":"",
           "www":"www.homepage.com",
           "other_i_name_1":"Other info 1",
           "other_i_name_2":"Other info 2",
           "other_i_name_3":"Other info 3",
           "other_i_name_4":"Other info 4",
           "other_i_name_5":"Other info 5",
           "other_i_name_6":"Other info 6",
           "other_info_7":"OI7_6",
           "other_i_name_7":"Other info 7",
           "other_info_8":"OI8_6",
           "other_i_name_8":"Other info 8",
           "other_info_9":"OI9_6",
           "other_i_name_9":"Other info 9",
           "other_info_10":"OI10_6",
           "other_i_name_10":"Other info 10",
           "other_info_11":"OI11_6",
           "other_i_name_11":"Other info 11",
           "other_info_12":"OI12_6",
           "other_i_name_12":"Other info 12",
           "other_info_13":"OI13_6",
           "other_i_name_13":"Other info 13",
           "other_info_14":"OI14_6",
           "other_i_name_14":"Other info 14",
           "other_info_15":"OI15_6",
           "other_i_name_15":"Other info 15",
           "other_info_16":"OI16_6",
           "other_i_name_16":"Other info 16",
           "other_info_17":"OI17_6",
           "other_i_name_17":"Other info 17",
           "other_info_18":"OI18_6",
           "other_i_name_18":"Other info 18",
           "other_info_19":"OI19_6",
           "other_i_name_19":"Other info 19",
           "other_info_20":"OI20_6",
           "other_i_name_20":"Other info 20",
           "other_info_21":"OI21_6",
           "other_i_name_21":"Other info 21",
           "other_info_22":"OI22_6",
           "other_i_name_22":"Other info 22",
           "other_info_23":"OI23_6",
           "other_i_name_23":"Other info 23",
           "other_info_24":"OI24_6",
           "other_i_name_24":"Other info 24",
           "other_info_25":"OI25_6",
           "other_i_name_25":"Other info 25",
           "other_info_26":"OI26_6",
           "other_i_name_26":"Other info 26",
           "other_info_27":"OI27_6",
           "other_i_name_27":"Other info 27",
           "other_info_28":"OI28_6",
           "other_i_name_28":"Other info 28",
           "other_info_29":"OI29_6",
           "other_i_name_29":"Other info 29",
           "other_info_30":"OI30_6",
           "other_i_name_30":"Other info 30",
           "other_info_31":"OI31_6",
           "other_i_name_31":"Other info 31",
           "other_info_32":"OI32_6",
           "other_i_name_32":"Other info 32",
           "other_info_33":"OI33_6",
           "other_i_name_33":"Other info 33",
           "other_info_34":"OI34_6",
           "other_i_name_34":"Other info 34",
           "other_info_35":"OI35_6",
           "other_i_name_35":"Other info 35",
           "assigned_agent_id":"",
           "company_id":"11795",
           "last_reason":"",
           "calling_list_id":"3378",
           "last_call_id":"",
           "phonenumbers":["0123456789"]
       },
       "success":true
   }

Examples:

  Get information about Ville Virtanen with id 7438675:
  http://api.leaddesk.com?auth=X&mod=contact&cmd=get&contact_id=7438675

 

Command: DELETE

With delete command user can delete contact information from LeadDesk by given ID. Delete command will remove also contacts phonenumbers. This can have affect to call history information if numbers already called. Parameters:

Name	Type	Mandatory	Description	Example
contact_id	integer	yes	Contact ID that needs to match LeadDesk contact id.	77429

Possible errors:

Error	Description
ERR_NOT_FOUND	No contact found from LeadDesk with given contact id.

Success: On success will return JSON string:

  {"success":true}

Examples: Delete contact named Ville Virtanen with id 7438675: http://api.leaddesk.com?auth=X&mod=contact&cmd=delete&contact_id=7438675

Command: FIND

Find command can be used to find a contact with certain search criteria and return the contact ID which can then be used as a parameter for the other commands of the contact module. NOTE! This command only returns 200 contact ID numbers at most. The “total_count” return parameter tells the actual amount of matched contacts in the database (can be over 200), but “contact_ids” array will only contain at most 200 entries. Parameters:

Name	Type	Mandatory	Description	Example
phone	string		Phone number of the contact.	0401234567
fname	string		Contact’s first name	John
lname	string		Contact’s last name	Smith
contact_list_id	int		Contact list id	1234

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	No parameters defined.

Success: On success will return a JSON string (one match):

{"success":true,"total_count":1,"contact_ids":[8837541]}

On success will return a JSON string (multiple matches):

  {"success":true,"total_count":2,"contact_ids":[8837541,8837542]}

On success will return a JSON string (no match):

  {"success":true,"total_count":0,"contact_ids":[]}

Examples: Find contacts with name Ville Virtanen and phone number 040111222: http://api.leaddesk.com?auth=X&mod=contact&cmd=find&fname=Ville&lname=Virtanen&phone=040111222 Find contacts with phone number 040111222: http://api.leaddesk.com?auth=X&mod=contact&cmd=find&phone=040111222

Command: EXISTS

Exists command can be used to check if a contact exists with certain search criteria. NOTE: Only contacts still on calling list are included. NOTE2: This is best guess only. We cannot quarantee if the contact exists or does not exist. This is because fairly often customers have typos and misplaced information in their contacts. Parameters:

Name	Type	Mandatory	Description	Example
phone	string	(1*)	Phone number of the contact.	0401234567
fname	string	(2*)	Contact’s first name	John
lname	string	(2*)	Contact’s last name	Smith
contact_list_id	int		Contact list id	1234

1*, 2* Either first and last name or phone number are required Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	No parameters defined. Either first and last or phone number are required.

Success: On success will return a JSON string (match):

  {"success":true,"match":true}

On success will return a JSON string (no match):

  {"success":true,"match":false}

Examples: Find if a contact with name Ville Virtanen and phone number 040111222 exists: http://api.leaddesk.com?auth=X&mod=contact&cmd=exists&fname=Ville&lname=Virtanen&phone=040111222 Find if a contacts with phone number 040111222 exists: http://api.leaddesk.com?auth=X&mod=contact&cmd=exists&phone=040111222

Command: REMOVE_FROM_LIST

Remove_from_list command can be used to remove a contact from contact list meaning that the contact will not be called by the progressive calling modes (automatic/semi-automatic calling) or the predictive dialer any more. Parameters:

Name	Type	Mandatory	Description	Example
contact_id	integer	yes	Id number of the contact.	12345

To update multiple contacts at once, you can also POST the parameters as a JSON formatted string in the HTTP request’s BODY. In this case you must leave the contact_id parameter out of the URI or it will override the parameter defined in the JSON. Below is the structure of the parameter data. JSON body:

Name	Type	Description
contact_ids	Array	Ids of the contacts to update. Array length is limited to 100 000.

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	No parameters defined.
ERR_ARGUMENT_INVALID	Invalid format for parameter value.
ERR_NOT_FOUND	No contact found from LeadDesk with given contact id.
ERR_ARGUMENT_LENGTH	Submitted argument is too short or too long

Success: On success will return a JSON string:

  {"success":true}

Example (one contact): Remove contact with id 12345 from list: http://api.leaddesk.com?auth=X&mod=contact&cmd=remove_from_list&contact_id=12345 Example (multiple contacts): Remove multiple contacts from list at once by POSTing JSON data into the following URI http://api.leaddesk.com?auth=X&mod=contact&cmd=remove_from_list

  {
   "contact_ids": [
       12345,
       23456
   ]
   }

 

Command: RESTORE_TO_LIST

Restore_to_list command can be used to restore a contact to contact list meaning that the contact will be called by the progressive calling modes (automatic/semi-automatic calling) or the predictive dialer if it still has call attempts left. Restored contact holds the original position in the contact list. Parameters:

Name	Type	Mandatory	Description	Example
contact_id	integer	yes	Id number of the contact.	12345

To update multiple contacts at once, you can also POST the parameters as a JSON formatted string in the HTTP request’s BODY. In this case you must leave the contact_id parameter out of the URI or it will override the parameter defined in the JSON. Below is the structure of the parameter data. JSON body:

Name	Type	Description
contact_ids	Array	Ids of the contacts to update. Array length is limited to 100 000.

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	No parameters defined.
ERR_ARGUMENT_INVALID	Invalid format for parameter value.
ERR_NOT_FOUND	No contact found from LeadDesk with given contact id.
ERR_ARGUMENT_LENGTH	Submitted argument is too short or too long

Success: On success will return a JSON string:

  {"success":true}

Example (one contact): Restore contact with id 12345 to list: http://api.leaddesk.com?auth=X&mod=contact&cmd=restore_to_list&contact_id=12345 Example (multiple contacts): Restore multiple contacts to list at once by POSTing JSON data into the following URI http://api.leaddesk.com?auth=X&mod=contact&cmd=remove_from_list

   {
   "contact_ids": [
       12345,
       23456
   ]
   }

Command: SET_CALL_ATTEMPTS

Set or add call attempts for contacts JSON body:

Name	Type	Mandatory	Description
operation	string	yes	Set or add.
value	Integer	yes	The value which is set to the call attempts or the value which is added to the call attempts. This depends on the operation.
contact_ids	Array	yes	Ids of the contacts to update. Array length is limited to 100 000.

Possible errors: TODO AFTER CODE REVIEW

Error	Description
ERR_NOT_FOUND:contact_id	At least one of the given contact ids is not found.
ERR_ARGUMENT_MISSING	Mandatory argument missing
ERR_ARGUMENT_INVALID:value	If value is not numeric. If operation “set” is used then the value is not between 0 and 32767. And if the operation is “add” the value is not between 1 and 32767.
ERR_ARGUMENT_INVALID:operation	If operation is not “add” or “set”.
ERR_ARGUMENT_LENGTH	If array is empty

Success: If the command is executed without errors, the following JSON string is returned:

  {"success":true}

Example (add call attempts): Adds 3 call attempts for the contacts 12345 and 23456: http://api.leaddesk.com?auth=X&mod=contact&cmd=set_call_attempts

  { "operation":"add", "value":3, "contact_ids":[ 12345, 23456 ] }

 

Command: RESERVE_TO_AGENT

Reserves contacts to an agent. This will prevent other agents from calling the contacts. Feature flags that affect this command: B2B – If a contact has a company, all contacts belonging to that company will reserved to an agent. Parameters JSON body:

Name	Type	Description
contact_ids	Array	Ids of the contacts. Array length is limited to 100 000.
agent	String or integer	Agent id or username. With parameter zero (0) contact will be released.

Possible errors: No agent found with given agent id or username Mandatory argument missing

Error	Description
ERR_NOT_FOUND:agent	Mandatory argument missing
ERR_ARGUMENT_INVALID	Invalid format for parameter

Success: If the command is executed without errors, the following JSON string is returned:

  {"success":true}

Example: Reserve contact ids 3, 4 and 6 for agent id 47 by POSTing JSON data into the following URI http://api.leaddesk.com?auth=X&mod=contact&cmd=reserve_to_agent

 {
   "contact_ids": [
       3,
       4,
       6,
   ],
   "agent_id": 47
   }

 

Command: MOVE_CONTACTS_TO_ANOTHER_LIST

Move multiple contacts to another list Parameters

Name	Type	Mandatory	Description	Example
calling_list_id	String or integer	yes	Id number of the target calling list	1001

JSON body

Name	Type	Mandatory	Description
contact_ids	Array	yes	Ids of the contacts to be transferred. Array length is limited to 100 000 (Note: does not give any error with invalid ids!)

Possible errors:

Error	Description
ERR_NOT_FOUND	Target calling list was not found from the database
ERR_ARGUMENT_MISSING	At least one mandatory parameter was missing
ERR_ARGUMENT_INVALID	Invalid format for parameter
ERR_ARGUMENT_LENGTH	Submitted argument is too short or too long

Success: If the command is executed without errors, the following JSON string is returned:

  {"success":true}

Example: Move contact ids 3, 4 and 6 to target calling list 1001 by POSTing JSON data into the following URI http://api.leaddesk.com?auth=X&mod=contact&calling_list_id=1001&cmd=move_contacts_to_another_list

 {{  
  "contact_ids":[  
     3,
     4,
     6
  ]}

 

Command: SET_WAITING_PERIOD

Set a waiting period for the phone numbers of a contact. Parameters:

Name	Type	Mandatory	Description	Example
contact_id	integer	yes	Contact ID that needs to match LeadDesk contact id.	77429
end_time	timestamp	yes	MySQL timestamp of the waiting period end time. Uses the client’s default timezone.	2016-11-17 18:39:19

To update multiple contacts at once, you can also POST the parameters as a JSON formatted string in the HTTP request’s BODY. In this case you must leave the contact_id and end_time parameters out of the URI or they will override the parameters defined in the JSON. Below is the structure of the parameter data. JSON body:

Name	Type	Description
contact_ids	Array	Ids of the contacts to update. Array length is limited to 100 000.
end_time	String	MySQL timestamp of the waiting period end time. Uses the client’s default timezone.

Possible errors:

Error	Description
ERR_NOT_FOUND:contact_id	No contact found with given contact_id
ERR_ARGUMENT_MISSING	Mandatory argument missing
ERR_ARGUMENT_INVALID	Invalid format for parameter
ERR_INVALID_FORMAT:end_time	The end_time was wrongly formatted. Use the MySQL timestamp format.
ERR_ARGUMENT_LENGTH	Submitted argument is too short or too long

Success: If the command is executed without errors, the following JSON string is returned:

  {"success":true}

Example (one contact): Set waiting period end time for the phone numbers of contact 77429 to ‘2016-11-17 18:39:19’: http://api.leaddesk.com?auth=X&mod=contact&cmd=set_waiting_period&contact_id=77429&end_time=2016-11-17%2018%3A39%3A19 Example (multiple contacts): Set waiting period end time for the phone numbers of multiple contacts at once by POSTing JSON data into the following URI http://api.leaddesk.com?auth=X&mod=contact&cmd=set_waiting_period

   {
   "contact_ids": [
       12345,
       23456
   ],
   "end_time": "2016-11-17 18:39:19"
   }

 

 

Order

---

Order module contains the order management functionality.

Command: CREATE

Create command allows the creation of new orders into LeadDesk database.

Known issues:

• If a client has more than one product with a same name, the API just pick one of the products, causing the API to behave in a non-deterministic way. Step 1: improve error messaging: Step 2: figure out a way how to solve the problem itself.
• Contact information (at least invoice data) has to be set manually. Those do not come automatically from call details.

Parameters:

Create command takes the parameters as JSON formatted string in HTTP request’s BODY. Below is the structure of the order data.

JSON Base level:

Name	Type	Description
properties	Object	Order’s common properties
settings	Object	Order creation settings (affects functionality of this command)
invoice	Object	Invoicing contact details
delivery	Object	Delivery contact details
content	Array	Order’s content (holds 0…N Product Objects)

Properties Object:

Name	Type	Description	Default value
agent	String	Existing agent’s username or external identifier. Order is attached to this agent or admin. If agent does not exists, then order creation will fail (ERR_NOT_FOUND).	mandatory
datetime	Timestamp	Date and time in format ‘YYYY-MM-DD HH:MM:SS’.	Current date and time
campaign	String	Which campaign the order is attached (searches for campaign name). See list of available campaigns from “Admin > Campaigns” page. If campaign name is given and it doesn’t exist already then order creation will fail (ERR_NOT_FOUND).	(no campaign)
campaign_id	Integer	Which campaign the order is attached. This is an alternative to campaign parameter. If campaign id is given and it doesn’t exist already then order creation will fail (ERR_NOT_FOUND).	(no campaign)
state	String	Which state is assigned to order (searched by name). See list of available order states from “Admin > Campaigns > Order States” page. If state is given, then it has to exist or order creation will fail (ERR_NOT_FOUND).	(no state)
state_comment	String	Comment that is assigned to the given state.	(no comment)
call_id	Integer	Id number of the call that the order is attached to.	(no call)
record_file	String	Voice receipt file name. If file name does not start with http, the file name will stored as an URL for LeadDesk recording server.	(no record file)

Settings Object:

Name	Type	Description	Default value
product_id	Enumeration(code,name)	Which product fields is used for searching products. Other field is ignored unless product is created. See list of available products and their product codes in “Admin > Objectives > Product list” page.	name
product_create	Enumeration(yes,no)	Should we create the product if it doesn’t exist already. Created product can be modified from “Admin > Products” page afterwards. If product creation is not allowed and product is not found then order creation will fail (ERR_NOT_FOUND).	no
return_order_id	Enumeration(yes,no)	Should we return the order id after creation. Selecting “yes” will cause the return value to be in JSON format: {“success”:true,”order_id”:123456}.	no

Invoice Object:

Name	Type	Description	Default value
phone	String	Customer’s phone number	(empty)
firstname	String	Customer’s first name	(empty)
lastname	String	Customer’s last name	(empty)
company	String	Customer’s company	(empty)
vatin	String	Company’s VAT identification number	(empty)
title	String	Customers title in company	(empty)
streetaddress	String	Customer’s street address	(empty)
postalcode	String	Customer’s postal code	(empty)
city	String	Customer’s city	(empty)
country	String	Customer’s country	(empty)
ssc	String	Customer’s social security code	(empty)
email	String	Customer’s email address	(empty)
www	String	Customer’s www address	(empty)
gender	String	Customer’s gender	(empty)
year_of_birth	String	Customer’s year of birth	(empty)
otherX (X = 1…6)	String	Customer’s other info	(empty)

Delivery Object:

Name	Type	Description	Default value
phone	String	Customer’s phone number	(empty)
firstname	String	Customer’s first name	(empty)
lastname	String	Customer’s last name	(empty)
company	String	Customer’s company	(empty)
title	String	Customer’s title in company	(empty)
streetaddress	String	Customer’s street address	(empty)
postalcode	String	Customer’s postal code	(empty)
city	String	Customer’s city	(empty)
country	String	Customer’s country	(empty)
ssc	String	Customer’s social security code	(empty)
email	String	Customer’s email address	(empty)

Product Object:

Name	Type	Description	Default value
name	String	Product’s name	(empty)
code	String	Product’s code	(empty)
quantity	Integer	How many units was sold	1
price	Float	Sales price of one unit. Use dot as decimal separator.	0
commission	Float	Commission of one unit. Use dot as decimal separator.	0
fields	JSON object	Product fields as a JSON object. Format: {“field_name1″:”field_value1”, “field_name2″:”field_value2”}	(empty)

Success:

By default the command will return an HTTP response with status 200 and the text “OK” like so:

   OK

If “return_order_id” parameter is set to “yes” then the command will return a JSON response:

  {"success":true,"order_id":123456}

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	At least one mandatory parameter was missing
ERR_NOT_FOUND	Something was not found from DB (e.g. agent, product or campaign).
ERR_INVALID_FORMAT	Some of the given parameters were wrongly formatted
ERR_DB	There was an error saving the data (please contact customer support)

Example:

  Create new order by POSTing JSON data into following URI
  <a class="external free" href="http://api.leaddesk.com/?auth=X&mod=order&cmd=create" rel="nofollow">http://api.leaddesk.com?auth=X&mod=order&cmd=create</a>

   {
   "properties": {
       "agent": "agent1",
       "datetime": "2012-12-30 20:02:03",
       "campaign": "campaign1",
       "state": "closed"
   },
   "settings": {
       "product_id": "name",
       "product_create": "no"
   },
   "invoice": {
       "phone": "1234567",
       "firstname": "sami",
       "lastname": "luostarinen",
       "company": "leaddesk oy",
       "vatin": "1234567-8",
       "title": "manager",
       "streetaddress": "laserkatu 6",
       "postalcode": "53850",
       "city": "lappeenranta",
       "country": "finland",
       "ssc": "12345678-1234",
       "email": "sami.luostarinen@leaddesk.com",
       "www": "www.leaddesk.com",
       "other1": "example data 1",
       "other2": "",
       "other3": "",
       "other4": "",
       "other5": "",
       "other6": ""
   },
   "delivery": {
       "phone": "",
       "firstname": "",
       "lastname": "",
       "company": "",
       "title": "",
       "streetaddress": "",
       "postalcode": "",
       "city": "",
       "country": "",
       "ssc": "",
       "email": ""
   },
   "content": [
       {
           "name": "product1",
           "code": "12345-ABC",
           "quantity": "1",
           "price": "99.99",
           "commission": "9.90"
       },
       {
           "name": "product2",
           "code": "ABCD-123",
           "quantity": "2",
           "price": "12.90",
           "commission": "1.00"
       }
   ]
   }

 

Command: DELETE

With delete command user can delete order information from LeadDesk by given Order ID.

Parameters:

Name	Type	Mandatory	Description	Example
order_id	integer	yes	Order ID that needs to match LeadDesk order id.	12345

Possible errors:

Error	Description
ERR_NOT_FOUND	No order found from LeadDesk with given order id.

Success:
On success will return JSON string:

  {"success":true}

Examples:
Delete order with id 12345:
http://api.leaddesk.com?auth=X&mod=order&cmd=delete&order_id=12345

Command: MODIFY

Modify command allows the modification of orders in LeadDesk database. If a parameter is sent with an empty value then the equivalent order information is set to empty too. If a parameter is not defined at all then the equivalent order information is left as is.

This command can also be used to add, edit and remove products from the order. A product will be added to the order if it is not found from the order already. A product can be removed from the order by setting its quantity to zero or empty.

Parameters:

Modify command takes the parameters as JSON formatted string in HTTP request’s BODY. Below is the structure of the order data.

JSON Base level:

Name	Type	Description
properties	Object	Order’s common properties
settings	Object	Order creation settings (affects functionality of this command)
invoice	Object	Invoicing contact details
delivery	Object	Delivery contact details
content	Array	Order’s content (holds 0…N Product Objects)

Properties Object:

Name	Type	Description	Default value
order_id	Integer	Existing order’s ID. If the order does not exist, then order modification will fail (ERR_NOT_FOUND).	mandatory
agent	String	Existing agent’s username or external identifier. Order is attached to this agent or admin. If the agent does not exist, then order creation will fail (ERR_NOT_FOUND).	(empty)
datetime	Timestamp	Date and time in format ‘YYYY-MM-DD HH:MM:SS’.	(empty)
campaign	String	Which campaign the order is attached (searches for campaign name). See list of available campaigns from “Admin > Campaigns” page. If campaign name is given and it doesn’t exist already then order cretion will fail (ERR_NOT_FOUND).	(empty)
state	String	Which state is assigned to order (searched by name). See list of available order states from “Admin > Campaigns > Order States” page. If state is given, then it has to exist or order creation will fail (ERR_NOT_FOUND).	(empty)
state_comment	String	Comment that is assigned to the given state.	(empty)
call_id	Integer	Id number of the call that the order is attached to.	(empty)
record_file	String	Voice receipt file name. If file name does not start with http, the file name will stored as an URL for LeadDesk recording server.	(no record file)

Settings Object:

Name	Type	Description	Default value
product_id	Enumeration(code,name)	Which product field is used for searching products. Other field is ignored unless product is created. See list of available products and their product codes in “Admin > Products” page.	name
product_create	Enumeration(yes,no)	Should we create the product if it doesn’t exist already. Created product can be modified from “Admin > Products” page afterwards. If product creation is not allowed and product is not found then order creation will fail (ERR_NOT_FOUND).	no

Invoice Object:

Name	Type	Description	Default value
phone	String	Customer’s phone number	(empty)
firstname	String	Customer’s first name	(empty)
lastname	String	Customer’s last name	(empty)
company	String	Customer’s company	(empty)
vatin	String	Company’s VAT identification number	(empty)
title	String	Customers title in company	(empty)
streetaddress	String	Customer’s street address	(empty)
postalcode	String	Customer’s postal code	(empty)
city	String	Customer’s city	(empty)
country	String	Customer’s country	(empty)
ssc	String	Customer’s social security code	(empty)
email	String	Customer’s email address	(empty)
www	String	Customer’s www address	(empty)
gender	String	Customer’s gender	(empty)
year_of_birth	String	Customer’s year of birth	(empty)
otherX (X = 1…6)	String	Customer’s other info	(empty)

Delivery Object:

Name	Type	Description	Default value
phone	String	Customer’s phone number	(empty)
firstname	String	Customer’s first name	(empty)
lastname	String	Customer’s last name	(empty)
company	String	Customer’s company	(empty)
title	String	Customer’s title in company	(empty)
streetaddress	String	Customer’s street address	(empty)
postalcode	String	Customer’s postal code	(empty)
city	String	Customer’s city	(empty)
country	String	Customer’s country	(empty)
ssc	String	Customer’s social security code	(empty)
email	String	Customer’s email address	(empty)

Product Object:

Name	Type	Description	Default value
name	String	Product’s name	(empty)
code	String	Product’s code	(empty)
quantity	Integer	How many units were sold. Set quantity to zero or empty to remove a product from the order.	1 (this applies only when adding a new product to order)
price	Float	Price of one unit. Use dot as decimal separator.	0
commission	Float	Commission of one unit. Use dot as decimal separator.	0
fields	JSON object	Product fields as a JSON object. Format: {“field_name1″:”field_value1”, “field_name2″:”field_value2”}	(empty)

Success: On success will return HTTP response with status 200 and text OK.

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	At least one mandatory parameter was missing
ERR_NOT_FOUND	Something was not found from DB (e.g. agent, product or campaign).
ERR_INVALID_FORMAT	Some of the given parameters were wrongly formatted
ERR_DB	There was an error saving the data (please contact customer support)

Example:
Modify an order by POSTing JSON data into following URI
http://api.leaddesk.com?auth=X&mod=order&cmd=modify

   {
   "properties": {
       "order_id": "12345",
       "campaign": "campaign2"
   },
   "settings": {
       "product_id": "name",
       "product_create": "no"
   },
   "invoice": {
       "phone": "12345678",
       "title": "r&d manager",
       "other2": "example data 2",
       "other3": "example data 3"
   },
   "content": [
       {
           "name": "product1",
           "quantity": "0"
       },
       {
           "name": "product2",
           "quantity": "5",
           "price": "16.90",
           "commission": "3.00"
       }
   ]
   }

Command: UPLOAD_VOICE_RECEIPT

With this command the user can upload a voice receipt file to an order.

NOTE: You must use “http://api-rec.leaddesk.com” when using this command!

Parameters:

Name	Type	Mandatory	Description	Example
order_id	integer	yes	Order ID that needs to match LeadDesk order id.	12345
file	POST file upload	yes	The file data to be uploaded as a POST parameter.
overwrite	enumeration(yes,no)	yes	Whether the upload can overwrite a file with a similar name than the uploaded file.	no

Possible errors:

Error	Description
ERR_NOT_FOUND	No order found from LeadDesk with given order id.
ERR_ARGUMENT_MISSING	At least one mandatory parameter was missing.
ERR_ARGUMENT_INVALID	Argument is wrongly formatted.

Success:
On success will return JSON string:

  {"success":true, "file":"name_of_uploaded_file"}

Examples:
Upload a voice receipt file for order with id 12345 (note that POST method must be used for “file” argument):
http://api-rec.leaddesk.com?auth=X&mod=order&cmd=upload_voice_receipt&order_id=12345&overwrite=no

Command: GET

Get command allows the retrieval of order info based on order id.

Parameters:

Name	Type	Mandatory	Description	Example
order_id	integer	yes	Order ID that needs to match LeadDesk order id.	12345

Possible errors:

Error	Description
ERR_NOT_FOUND	No order found from LeadDesk with given order id.

Success:
On success the command will return a JSON formatted string. Below is the structure of the order data and an example. The structure is similar to the one used in create and modify commands. If a certain piece of information is missing from the order then it will have an empty value in the JSON object.

JSON Base level:

Name	Type	Description
success	Boolean	Response status
properties	Object	Order’s common properties
invoice	Object	Invoicing contact details
delivery	Object	Delivery contact details
content	Array	Order’s content (holds 0…N Product Objects)

Properties Object:

Name	Type	Description	Notes
agent	String	Username of the agent that created the order.	NOT IMPLEMENTED
datetime	Timestamp	Date and time of order creation in format ‘YYYY-MM-DD HH:MM:SS’.	NOT IMPLEMENTED
campaign	String	Campaign in which the order was made.	NOT IMPLEMENTED
state	String	State of the order.
state_comment	String	Comment for the state of the order.
call_id	Integer	Id number of the call that the order is attached to.	NOT IMPLEMENTED

Invoice Object:

Name	Type	Description	Notes
phone	String	Customer’s phone number	NOT IMPLEMENTED
firstname	String	Customer’s first name	NOT IMPLEMENTED
lastname	String	Customer’s last name	NOT IMPLEMENTED
company	String	Customer’s company	NOT IMPLEMENTED
vatin	String	Company’s VAT identification number	NOT IMPLEMENTED
title	String	Customers title in company	NOT IMPLEMENTED
streetaddress	String	Customer’s street address	NOT IMPLEMENTED
postalcode	String	Customer’s postal code	NOT IMPLEMENTED
city	String	Customer’s city	NOT IMPLEMENTED
country	String	Customer’s country	NOT IMPLEMENTED
ssc	String	Customer’s social security code	NOT IMPLEMENTED
email	String	Customer’s email address	NOT IMPLEMENTED
www	String	Customer’s www address	NOT IMPLEMENTED
otherX (X = 1…6)	String	Customer’s other info	NOT IMPLEMENTED

Delivery Object:

Name	Type	Description	Notes
phone	String	Customer’s phone number	NOT IMPLEMENTED
firstname	String	Customer’s first name	NOT IMPLEMENTED
lastname	String	Customer’s last name	NOT IMPLEMENTED
company	String	Customer’s company	NOT IMPLEMENTED
title	String	Customer’s title in company	NOT IMPLEMENTED
streetaddress	String	Customer’s street address	NOT IMPLEMENTED
postalcode	String	Customer’s postal code	NOT IMPLEMENTED
city	String	Customer’s city	NOT IMPLEMENTED
country	String	Customer’s country	NOT IMPLEMENTED
ssc	String	Customer’s social security code	NOT IMPLEMENTED
email	String	Customer’s email address	NOT IMPLEMENTED

Product Object:

Name	Type	Description	Notes
name	String	Product’s name	NOT IMPLEMENTED
code	String	Product’s code	NOT IMPLEMENTED
quantity	Integer	How many units was sold	NOT IMPLEMENTED
price	Float	Sales price of one unit. Use dot as decimal separator.	NOT IMPLEMENTED
commission	Float	Commission of one unit. Use dot as decimal separator.	NOT IMPLEMENTED
fields	JSON object	Product fields as a JSON object. Format: {“field_name1″:”field_value1”, “field_name2″:”field_value2”}	NOT IMPLEMENTED

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	At least one mandatory parameter was missing
ERR_NOT_FOUND	Something was not found from DB (e.g. agent, product or campaign).
ERR_INVALID_FORMAT	Some of the given parameters were wrongly formatted
ERR_DB	There was an error saving the data (please contact customer support)

Example call:
Get order information from order with id 12345:
http://api.leaddesk.com?auth=X&mod=order&cmd=get&order_id=12345

Example response:

   {
   "success": true,
   "properties": {
       "state": "Closed",
       "state_comment": "This deal is closed."
   }
   }

Command: SET_STATE

SET STATE command allows the user to change the state of the order. Setting the state has very few restrictions considering the parameters. Given order, state and agent needs to exist in database but that’s the only limitation. E.g. you can even use deleted user and deleted state.

Parameters:

Name	Type	Default	Description	Example
order_id	integer	mandatory	Order ID that is modified	12345
state_id	integer	mandatory	New state for order. Use 0 if you want to set the “(not selected)” state.	234
agent_id	integer	mandatory	Agent who made the change. This is logged in the state history. Even if the order is locked you can use any level agent here. Normally level 1 agents wouldn’t be able to modify locked states, but API user is considered to be admin level user and that’s why the operation is accepted.	345
comment	string	(empty)	Comment for the state change	Approved
forceupdate	enum(yes,no)	no	This option will decide what happens when the order already has the same state that was given. If yes then will write the same state to order again, which basically just adds history entry. If no, then ignores the request completely and nothing is added to state history.	yes

Possible errors:

Error	Description
ERR_NOT_FOUND	No order, agent or state was found from LeadDesk with given id.
ERR_ARGUMENT_MISSING	Mandatory argument is missing
ERR_INVALID_FORMAT	Some of the given parameters were wrongly formatted

Success:

On success will return JSON string:

  {"success":true}

Example:

Set new state to order with id 12345:
http://api.leaddesk.com?auth=X&mod=order&cmd=set_state&order_id=12345&state_id=23&agent_id=34&comment=approved&forceupdate=no

Command: CREATE_ORDER_STATE

CREATE_ORDER_STATE command allows the user to create a new order state.

Parameters:

Name	Type	Description	Default value
name	string	Order state name	mandatory
lock_order	boolean (0,1)	If order is given this a state with lock enabled, agent cannot modify the order anymore.	0
hide_from_agents	boolean (0,1)	Order state is not visible for agents.	0

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory argument is missing

Success:

On success will return JSON string:

  {"id":123}

Example:

  Create a new order state having name "teststate":
  <a class="external free" href="http://api.leaddesk.com/?auth=X&mod=order&cmd=create_order_state&name=teststate" rel="nofollow">http://api.leaddesk.com?auth=X&mod=order&cmd=create_order_state&name=teststate</a>

Command: GET_ORDER_STATES

GET_ORDER_STATES command allows the user to fetch order states for example by id or name. Names are not unique, so it can return many order states.

Parameters:

Name	Type	Description	Default value
id	integer	Order state id	mandatory [1]
name	string	Order state name	mandatory [1]

[1] Either id or name has to be defined, but not both.

Possible errors:

Error	Description
ERR_ARGUMENT_INVALID	Either id or name argument is missing, or you are using both at the same time.
ERR_NOT_FOUND	No order state was found.

Success:

On success will return JSON string:

  [{"id":123,"name":"teststate","lock_order":true,"hide_from_agents":false},{"id":....}]

Example:

  Get order states having name "teststate":
  <a class="external free" href="http://api.leaddesk.com/?auth=X&mod=order&cmd=get_order_states&name=teststate" rel="nofollow">http://api.leaddesk.com?auth=X&mod=order&cmd=get_order_states&name=teststate</a>

Blacklist

---

Command: ADD

Command adds numbers to blacklists. Blacklists can be specified to “no sponsor / own usage” and to certain sponsors. Limitations

• Usage requires feature “blacklist”.
• Maximum amount of numbers allowed for processing is currently set to 10000
• Sponsor name can’t include a comma (,)

 

Name	Type	Description
numbers	string	String containing phone numbers separated with a comma (,)	mandatory
sponsors	string	String containing sponsor names or ids separated with a comma (,). Sponsor id zero (0) equals “no sponsor / own”	mandatory

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ARGUMENT_INVALID	Mandatory parameter was invalid
ERR_NOT_FOUND	No such sponsor was found. Check the names / ids
ERR_FEATURE_NOT_ENABLED	Feature “blacklist” is required with this command
ERR_REQUEST_METHOD	Command parameters (numbers and sponsors) must be passed via POST

Success: On success will return a JSON string in the format of:

  {"success":true}

Example: Add the following numbers to sponsor ‘Test Sponsor’ blacklists by POSTing the parameters into the following URI http://api.leaddesk.com?auth=X&mod=blacklist&cmd=add

{
   "numbers": "100,110,120,130",
   "sponsors": "Test Sponsor"
}

Command: DELETE

Command removes certain numbers from all blacklists. Deleting a number from a blacklist does not bring the number back to a calling list from which it was originally blacklisted. Limitations

• Usage requires feature “blacklist”.
• Maximum amount of numbers allowed for processing is currently set to 10000
• Sponsor name can’t include a comma (,)

 

Name	Type	Description
numbers	string	String containing phone numbers separated with commas (,) or an asterisk (*) to remove all numbers	mandatory
sponsors	string	String containing sponsor names or ids separated with commas (,) or an asterisk (*) to remove from all sponsors. Sponsor id zero (0) equals “no sponsor / own”	mandatory

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ARGUMENT_INVALID	Mandatory parameter was invalid
ERR_NOT_FOUND	No such sponsor was found. Check the names / ids
ERR_FEATURE_NOT_ENABLED	Feature “blacklist” is required with this command
ERR_REQUEST_METHOD	Command parameters (numbers and sponsors) must be passed via POST

Success: On success will return a JSON string in the format of:

  {"success":true}

Example: Delete the following numbers from “no sponsor / own” and sponsor ‘Test Sponsor’ blacklists by POSTing parameters into the following URI http://api.leaddesk.com?auth=X&mod=blacklist&cmd=delete

{
   "numbers": "100,110,120,130",
   "sponsors": "0, Test Sponsor"
}

Command: CHECK

 

Command checks numbers from blacklists. Blacklists can be specified to “no sponsor / own usage” and to certain sponsors.

Limitations

• Usage requires feature “blacklist”. See feature page:
• The Request Method is POST
  • Numbers should be sent in the request body (x-www-form-urlencoded)
  • If you only have few numbers to check then parameters can be sent as a query parameters in the URL (=GET), but bigger amount of numbers will easily exceed the maximum allowed URL length.
• Maximum amount of numbers allowed for processing is currently set to 10000
• Sponsor name can’t include a comma (,)
• If phone number contains (+) encode that with (%2B). Encode (*) with (%2A) for including all sponsors.

Name	Type	Description
numbers	string	String containing phone numbers separated with a comma (,)	mandatory
sponsors	string	String containing sponsor names or ids separated with a comma (,) or an asterisk (*) to find all blacklisted numbers. Sponsor id zero (0) equals “no sponsor / global sponsor”	mandatory

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ARGUMENT_INVALID	Mandatory parameter was invalid
ERR_NOT_FOUND	No such sponsor was found. Check the names / ids
ERR_ARGUMENT_EMPTY	Mandatory parameter was empty
ERR_FEATURE_NOT_ENABLED	Feature “blacklist” is required with this command
ERR_REQUEST_METHOD	Command parameters (numbers and sponsors) must be passed via POST

Success:

On success will return a JSON string in the format of:

  ["100","130"]

Example:

# Check the following numbers to sponsor 'Sponsor' blacklists by POSTing the parameters into the following URI
curl -X POST -d "numbers=100,110,120,130&sponsors=Sponsor" "https://api.leaddesk.com?auth=X&mod=blacklist&cmd=check"

Custom_fields

Custom fields module allows the management of custom fields aka. tags within different resources.

---

Resources

Resources that support custom fields and that can be used with the custom_field modules’s commands

Resource name	Description	Tag support
agent	Refers to agents’s custom fields	yes
campaign	Refers to campaigns’s custom fields	yes
callinglist	Refers to calling list’s custom fields	yes
product	Refers to products’s custom fields	no

Command: ADD_TAG

Adds new custom field value (=tag) into resource. Custom field needs to be defined into the resource before calling this method. If resource does not support tags (e.g. products), then adding a new value will replace the old value. If custom field has been marked as required, the new tag will also be marked as required. Required tags can be used for managing access to campaigns and calling lists. If campaign has required tags, agent must have the same tags to access the campaign. Parameters

Name	Type	Description
resource_name	string	(see resources)	mandatory
resource_id	int	resource’s unique id, for example agent’s id	mandatory
field	string	Custom field’s name	mandatory
value	string	New value to be added	mandatory

Possible errors: Only common errors Success: On success will return an empty JSON response Example:Add agent 123 into custom team ‘A-team’ http://api.leaddesk.com?auth=X&mod=custom_fields&cmd=add_tag&resource_name=agent&resource_id=123&field=team&value=A-team

Command: REMOVE_TAG

Removes a tag(s) from resource’s custom field. Command does nothing is no such tag is found, but it’s not considered as an error either. Parameters

Name	Type	Description
resource_name	string	(see resources)	mandatory
resource_id	int	resource’s unique id, for example agent’s id	mandatory
field	string	Custom field’s name	mandatory
value	string	Single tag to be removed. If value is omitted, then whole field will be cleared.	optional

Possible errors: Only common errors Success: On success will return an empty JSON response Example: Remove agent 123 from the custom team ‘A-team’ http://api.leaddesk.com?auth=X&mod=custom_fields&cmd=remove_tag&resource_name=agent&resource_id=123&field=team&value=A-team Remove agent 123 from every custom team http://api.leaddesk.com?auth=X&mod=custom_fields&cmd=remove_tag&resource_name=agent&resource_id=123&field=team

Command: GET

Gets resource’s all custom fields and their values. Will return all the defined custom fields even if they don’t have any values (=tags). NOTE! At the moment the command does not return custom fields that have no values (=tags)! This will be implemented at a later date! Parameters

Name	Type	Description
resource_name	string	(see resources)	mandatory
resource_id	int	resource’s unique id, for example agent’s id	mandatory

Possible errors: Only common errors Success: On success will JSON response with all the fields and values as such:

  {
  <field1 name>:[<field1 values>],
  <field2 name>:[<field2 values>],
  <field3 name>:[<field3 values>],
  <etc>
  }

  

Example: Get agent’s 123 custom fields http://api.leaddesk.com?auth=X&mod=custom_fields&cmd=get&resource_name=agent&resource_id=123

  {
    "team":["A-team","B-team"],
    "role":["Supervisor"],
    "empty":[]
  }

Command: SET_REQUIRED

Sets a custom field to campaign or contact list as required for agent. Can be used for limiting agent access to campaigns and contact lists (more info: Feature_filter_agent_selectable_campaigns_by_custom_fields and Feature_filter_calling_lists_by_custom_fields_for_agents). Requirements – At least one of these features must be enabled: Feature_filter_agent_selectable_campaigns_by_custom_fields if campaign custom fields are to be set as required or Feature_filter_calling_lists_by_custom_fields_for_agents if contact list custom fields are to be set as required. Parameters

Name	Type	Description
required	boolean (0,1)	1 for required, 0 for non-required	mandatory
resource_name	string	(supports only campaign and callinglist, see resources)	mandatory
resource_id	int	resource’s unique id, for example campaign id	mandatory
field	string	Custom field’s name	mandatory

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_NOT_SUPPORTED	Resource name was invalid. Only campaign and callinglist are supported.
ERR_NOT_FOUND	Resource (for example campaign) does not exist, or custom field does not exist. Also given if custom field has no tags -> custom field cannot be declared as required.
ERR_FEATURE_NOT_ENABLED	Setting campaign custom fields as required when feature filter_agent_selectable_campaigns_by_custom_fields is not enabled OR setting contact list custom fields as required when feature filter_calling_lists_by_custom_fields_for_agents is not enabled.

Success: On success will return empty JSON string. Example: Set custom field team as required for campaign id 123 http://api.leaddesk.com?auth=X&mod=custom_fields&cmd=set_required&required=1&resource_name=campaign&resource_id=123&field=team

Product

Product module allows the management of products and product fields.

Command: ADD

Adds a new product.

---

Parameters: Add command takes the parameters as a JSON formatted string in the body of the HTTP request. Below is the structure of the base level JSON object that holds the product data. JSON base level parameters:

Name	Type	Description	Mandatory
name	string	Name of the product	yes
sponsor	string	Sponsor of the product	yes
description	string	Description for the product	no
product_code	string	Product code of the product	no
price	float	Sales price of the product	no
commission	float	Commission of the product	no
office	string	Office of the product	no
points	float	Sales points of the product	no
commission_percent	float	Commission percent of the product	no
free_price	boolean (true/false)	Is the agent allowed to freely set the price for the product? (default: false)	no
sponsor_product_code	string	Sponsor product code of the product	no

Possible errors: Only common errors Success: On success will return a JSON string in the format of:

 {"id":"<product id>"}

Example URL: Add a product with the name “product1”: http://api.leaddesk.com?auth=X&mod=product&cmd=add Example JSON body:

 {
   "name": "Test product",
   "description": "Test description",
   "product_code": "test-product-code",
   "office": "Test office",
   "free_price": false,
   "sponsor_product_code": null,
   "price": "15.000",
   "commission": "10.000",
   "sponsor": "Test Sponsor",
   "points": null,
   "commission_percent": "5.000"
}

Command: MODIFY

Modifies an existing product based on id. Parameters: Modify command takes the product id as a GET parameter. Other parameters should be passed as a JSON formatted string in the body of the HTTP request. Below is the structure of the base level JSON object that holds the product data. GET parameters:

Name	Type	Description	Mandatory
id	integer	Id of the product to modify	yes

JSON base level parameters:

Name	Type	Description	Mandatory
name	string	Name of the product	no
description	string	Description for the product	no
product_code	string	Product code of the product	no
price	float	Sales price of the product	no
commission	float	Commission of the product	no
sponsor	string	Sponsor of the product	no
office	string	Office of the product	no
points	float	Sales points of the product	no
commission_percent	float	Commission percent of the product	no
free_price	boolean (true/false)	Is the agent allowed to freely set the price for the product? (default: false)	no
sponsor_product_code	string	Sponsor product code of the product	no

Possible errors: Only common errors Success: On success will return an empty JSON response:

 []

Example URL: Modify the product with the id “1”: http://api.leaddesk.com?auth=X&mod=product&cmd=modify&id=1 Example JSON body:

 {
   "name": "Test product modified",
   "office": "Another office",
   "free_price": true,
   "price": "25.000"
}

Command: GET

Gets product information based on id. Includes an array of product field ids and names. GET parameters:

Name	Type	Description	Mandatory
id	integer	Id of the product to get	yes

Possible errors: Only common errors Success: On success will return a JSON string in the format of:

 {
   "id": "<product id>",
   "name": "<product name>",
   "description": "<product description>",
   "product_code": "<product code>",
   "office": "<product office>",
   "free_price": false,
   "sponsor_product_code": "<sponsor product office>",
   "price": "15.000",
   "commission": "10.000",
   "sponsor": "<product sponsor>",
   "points": "5.000",
   "commission_percent": "0.000",
   "fields": [
       {
           "id": "<product field 1 id>",
           "name": "<product field 1 name>"
       },
       {
           "id": "<product field 2 id>",
           "name": "<product field 2 name>"
       }
   ]
}

Example: Get the product with the id “1”: http://api.leaddesk.com?auth=X&mod=product&cmd=get&id=1

Command: DELETE

Deletes a product based on id. This command actually performs a soft delete so that the product information will still be available in the database, but the product cannot be attached to campaigns or edited in the admin view. Also all relations that the product has will be removed (meaning that it will be detached from all campaigns etc.). GET parameters:

Name	Type	Description	Mandatory
id	integer	Id of the product to delete	yes

Possible errors: Only common errors Success: On success will return an empty JSON response:

 []

Example: Delete the product with the id “1”: http://api.leaddesk.com?auth=X&mod=product&cmd=delete&id=1

Command: ADD_FIELD

Adds a new product field. Parameters: Add field command takes the parameters as a JSON formatted string in the body of the HTTP request. Below is the structure of the base level JSON object that holds the product field data. JSON base level parameters:

Name	Type	Description	Mandatory
product_id	integer	Id of the product to attach the field to	yes
name	string	Name of the product field	yes
type	string	Type of the product field. Possible values: “datetime”, “dropdown”, “text”, “multiselect”, “textarea”, “static_text”	yes
options	array of option objects	Selectable options for a dropdown menu or a multiselect list. Each option contains “name”, “commission” and “visible” fields (definition below). This parameter only works with the types “dropdown” and “multiselect”.	no
default_value	string	Default value of the product field. When using the “textarea” type, separate multiple lines with the pipe character “|”. This parameter only works with the types “datetime”, “text”, “textarea”, “static_text”.	no
position	string/integer	The position of the field among the other fields of the product. Use a positive integer value (0 – XX) to set a certain position (zero being first). If the selected position is already taken, then the field previously occupying that position and each one after that is moved one position back. Use “first” or “last” to set a relative position. The default value is “last”.	no
visible	boolean (true/false)	Is this field visible to agents? Default value: true	no

Option object:

Name	Type	Description	Mandatory
name	string	Name of the option	yes
commission	float	Commission of the option	yes
visible	boolean (true/false)	Is this option visible to agents?	yes

Possible errors: Only common errors Success: On success will return a JSON string in the format of:

{"id":"<product field id>"}

Example URL: Add a product field with the name “Product field 1” to the product that has the id of “1”: http://api.leaddesk.com?auth=X&mod=product&cmd=add_field Example JSON body:

 {
   "product_id": "1",
   "name": "Product field 1",
   "visible": true,
   "type": "text",
   "position": "0",
   "default_value": null
}

Command: MODIFY_FIELD

Modifies a product field. Parameters: Modify field command takes the product field id as a GET parameter. Other parameters should be passed as a JSON formatted string in the body of the HTTP request. Below is the structure of the base level JSON object that holds the product field data. GET parameters:

Name	Type	Description	Mandatory
id	integer	Id of the product field to modify	yes

JSON base level parameters:

Name	Type	Description	Mandatory
product_id	integer	Id of the product to attach the field to	no
name	string	Name of the product field	no
type	string	Type of the product field. Possible values: “datetime”, “dropdown”, “text”, “multiselect”, “textarea”, “static_text”	no
options	array of option objects	Selectable options for a dropdown menu or a multiselect list. Each option contains “name”, “commission” and “visible” fields (definition below). This parameter only works with the types “dropdown” and “multiselect”.	no
default_value	string	Default value of the product field. When using the “textarea” type, separate multiple lines with the pipe character “|”. This parameter only works with the types “datetime”, “text”, “textarea”, “static_text”.	no
position	string/integer	The position of the field among the other fields of the product. Use a positive integer value (0 – XX) to set a certain position (zero being first). If the selected position is already taken, then the field previously occupying that position and each one after that is moved one position back. Use “first” or “last” to set a relative position. The default value is “last”.	no
visible	boolean (true/false)	Is this field visible to agents? Default value: true	no

Option object:

Name	Type	Description	Mandatory
name	string	Name of the option	yes
commission	float	Commission of the option	yes
visible	boolean (true/false)	Is this option visible to agents?	yes

Possible errors: Only common errors Success: On success will return an empty JSON response:

 []

Example URL: Modify a product field with the id “1” and set the name to “Product field 1 modified” and change type to dropdown: http://api.leaddesk.com?auth=X&mod=product&cmd=modify_field&id=1 Example JSON body:

 {
   "name": "Product field 1 modified",
   "type": "dropdown",
   "options": [
       {
           "name": "Option one",
           "commission": 0,
           "visible": true
       },
       {
           "name": "Option two",
           "commission": 0,
           "visible": true
       }
   ]
}

Command: GET_FIELD

Gets product field information based on id. GET parameters:

Name	Type	Description	Mandatory
id	integer	Id of the product field to get	yes

Possible errors: Only common errors Success: On success will return a JSON string in the format of:

 {
   "id": "1",
   "product_id": "1",
   "name": "Dropdown field",
   "visible": true,
   "type": "dropdown",
   "position": "0",
   "options": [
       {
           "name": "Option one",
           "commission": 0,
           "visible": true
       },
       {
           "name": "Option two",
           "commission": 0,
           "visible": true
       }
   ]
}

Example: Get the product with the id “1”: http://api.leaddesk.com?auth=X&mod=product&cmd=get_field&id=1

Command: DELETE_FIELD

Deletes a product field based on id. This command actually performs a soft delete so that the product field information will still be available in the database, but the product field cannot be seen or edited in the admin view. GET parameters:

Name	Type	Description	Mandatory
id	integer	Id of the product field to delete	yes

Possible errors: Only common errors Success: On success will return an empty JSON response:

 []

Example: Delete the product field with the id “1”: http://api.leaddesk.com?auth=X&mod=product&cmd=delete_field&id=1

 

 

Call

Call module contains call management functionality and it’s also useful for CRM’s which want to receive call information by call reference id or phone number.

---

Command: CREATE

With create command you can create a new call.

Limitations:

• Sending of sms/email messages defined in call ending reason is not supported.

Parameters:

Create command takes the parameters as a JSON formatted string in HTTP request’s BODY. Below is the structure of the call data.

JSON Base level:

Name	Type	Description
properties	Object	Call’s common properties

Properties Object:

Name	Type	Description	Default value
phone	string	Phone number for the call. Phone number needs to be at least 3 characters long.	mandatory
agent	string	Agent’s username. Agent must exist already, otherwise ERR_NOT_FOUND error is returned.	mandatory
status	enumeration(answered,unanswered)	Call status (possible values: “answered”, “unanswered”)	answered
direction	enumeration(in,out)	Direction of the call (possible values: “in”, “out”)	out
call_start	string	Start time of the call (calling started) in the format: “YYYY-MM-DD HH:MM:SS”	current timestamp
talk_start	string	Answering time of the call (talking started) in the format: “YYYY-MM-DD HH:MM:SS”	(empty)
talk_end	string	Disconnecting time of the call (talking ended) in the format: “YYYY-MM-DD HH:MM:SS”	(empty)
handling_stop	string	Ending time of call handling (call window closed) in the format: “YYYY-MM-DD HH:MM:SS”	(empty)
duration	integer	Duration of the call in seconds	talk_end – talk_start (if both defined)
comment	string	Call comment	(empty)
result	string or integer	Call result (call ending reason name or id number)*	(empty)
campaign	string or integer	Campaign of the call (name or id number). Campaign must exist already, otherwise ERR_NOT_FOUND error is returned.	(empty)
contact_list	string or integer	Contact list of the call (name or id number). Contact list must exist already, otherwise ERR_NOT_FOUND error is returned.	(empty)
contact	integer	Contact of the call (id number). Contact must exist already, otherwise ERR_NOT_FOUND error is returned.	(empty)
contact_update_mode	enumeration(none,number,contact)	Whether the given phone number or all numbers of a contact are updated according to given call result (marking as used, waiting periods, blacklisting, moving to another contact list). Note that following parameters must be defined and exist in db when this is used: phone, campaign and result.	(empty)

* Global call results must be referred to by using their id number or the English result name. These are: 0 = “Not selected”, 1 = “Deal” and 3 = “Callback”.

Success: On success will return HTTP response with status 200 and a JSON encoded object in the format:

  {"success":true,"call_id":12345}

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	At least one mandatory parameter was missing
ERR_NOT_FOUND	Something was not found from DB (e.g. agent, agent group or campaign).
ERR_INVALID_FORMAT	Some of the given parameters were wrongly formatted
ERR_DB	There was an error saving the data (please contact customer support)

Example:

Create new call request by POSTing JSON data into following URI:

http://api.leaddesk.com?auth=X&mod=call&cmd=create

   {
   "properties": {
       "phone": "0401234567",
       "agent": "Example Agent Username",
       "status": "answered",
       "direction": "out",
       "call_start": "2013-10-10 19:00:00",
       "talk_start": "2013-10-10 19:05:00",
       "talk_end": "2013-10-10 19:10:00",
       "handling_stop": "2013-10-10 19:15:00",
       "duration": "300",
       "comment": "Contact returns from vacation today.",
       "result": "Example Call Result",
       "campaign": "Example Campaign",
       "contact_list": "Example Contact List",
       "contact": "12345",
       "contact_update_mode": "number"
   }
   }

Command: GET

With Get command you can get information of a call with reference id or phone number.

Parameters:

Name	Type	Mandatory	Description	Example
phone	string	depends	Phone number (string). Call information is received by given phone number. The call with latest talk start time is selected.	0456789012
call_ref_id	integer	depends	Call reference ID (integer). Call information is received by given reference ID.	5824

Possible errors:

Error	Description
ERR_NO_NUMBER	Phone number was too short.
ERR_NOT_FOUND	Given call reference id or phone number was not found from database.

Success:

On success will return JSON encoded database query as HTTP response with status 200.

Return values:

Name	Type	Description	Example
id	integer	Call reference ID	5363
agent_id	integer	Agent ID	53
agent_username	string	Agent’s username	“testagent”
talk_time	integer	Call’s talk time in seconds	28
talk_start	string	Call start time in mysql formatted time ‘YYYY-MM-DD HH:MM:SS’	“2012-12-28 13:11:49”
talk_end	string	Call end time in mysql formatted time ‘YYYY-MM-DD HH:MM:SS’	“2012-12-28 13:12:17”
number	string	Phone number	“0501234567”
campaign	integer	Campaign ID	25
campaign_name	string	Campaign’s name	“Donald Duck campaign”
record_file	string	URL to record file	“http://cmpro3.comdashboard.com/media_records/2/2-CALL-testagent-0501234567-20121228-131152.wav.mp3“
created_at	string	Call creation time in mysql formatted time ‘YYYY-MM-DD HH:MM:SS’	“2012-12-28 13:11:52”
customer_id	integer	Customer ID	6558
comment	string	Agent’s comment regarding the call	“Quick sale”
agent_group_id	integer	Agent group ID	15
agent_group_name	string	Name of the agent group	“Donald duck team”
call_ending_reason	integer	Call ending reason ID	8
call_ending_reason_name	string	Name of the call ending reason	“Busy”
handling_stop	string	Call handling stop in mysql formatted time ‘YYYY-MM-DD HH:MM:SS’	“2012-12-28 13:12:18”
direction	string	Direction of the call (in/out)	“out”
call_type	integer	Call type as an integer	1 (equals semiautomatic call)
contact_id	integer	Contact id	123
call_type_name	string	Call type as a string	“semi”
order_ids	array	Array containing order ids related to this call	[1, 3]

Examples:

Get call information with phone number 0456789012:

http://api.leaddesk.com?auth=X&mod=call&cmd=get&phone=0456789012

Get call information with call reference id 4999:

http://api.leaddesk.com?auth=X&mod=call&cmd=get&call_ref_id=4999

Example response:

{
       "id":"4999",
       "agent_id":"11",
       "agent_username":"teuvotest",
       "talk_time":"45",
       "talk_start":"2016-01-01 12:13:14",
       "talk_end":"2016-02-02 14:12:10",
       "number":"+358123123",
       "campaign":"14",
       "campaign_name":"test campaign",
       "record_file":"test_recording.wav.mp3",
       "created_at":"2016-01-01 12:13:10",
       "customer_id":"21",
       "comment":"test comment",
       "agent_group_id":"13",
       "agent_group_name":"test group",
       "call_ending_reason":"15",
       "call_ending_reason_name":"test reason",
       "handling_stop":"2016-02-02 14:20:30",
       "direction":"out",
       "call_type":"1",
       "contact_id":"1",
       "call_type_name":"semi",
       "order_ids:[1, 3]
   }

Command: CREATE_CALLBACK

With create_callback command you can create a new callback and a contact for it.

Parameters:

Create_callback command takes the parameters as JSON formatted string in HTTP request’s BODY. Below is the structure of the callback data.

JSON Base level:

Name	Type	Description
properties	Object	Callback’s common properties
contact	Object	Contact details for the contact related to the callback
return_callback_id	Boolean	Return callback ID on success as JSON. Defaults to FALSE.

Properties Object:

Name	Type	Description	Default value
phone	string	Phone number for the callback. Phone number needs to be at least 3 characters long.	mandatory
type	string	Callback type (possible values: “private”, “public”)	mandatory
campaign	string	Campaign name	mandatory
agent	string	Agent’s username	mandatory
timestamp	string	Time for the callback in the format: “YYYY-MM-DD HH:MM:SS”	mandatory
comment	string	Callback comment	(empty)
agent_group	string	Agent group name	(empty)

Contact Object:

Name	Type	Description	Default value
contactid	integer	Contact ID (Leaddesk) (If set, other given contact values will be ignored)	(empty)
fname	string	Contact’s first name	(empty)
lname	string	Contact’s last name	(empty)
address	string	Contact’s street address	(empty)
postcode	string	Contact’s postal code	(empty)
city	string	Contact’s city	(empty)
country	string	Contact’s country	(empty)
contact_list	string	Contact list name to which the contact will be connected. If the contact list name is given and the list doesn’t exist then the callback creation will fail (ERR_NOT_FOUND).	(empty)
companyid	integer	Company ID which is linked to contact. If the company by given company ID doesn’t exist then the callback creation will fail (ERR_NO_COMPANY_FOUND). Can be empty.	(empty)
otherX (X = 1…35)	string	Contact’s other info	(empty)

Success: On success will return HTTP response with status 200 and text OK. Otherwise if ‘return_callback_id’ is set to true, then returns JSON encoded object with http status 200: {“callback_id”:1234,”success”:true}

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	At least one mandatory parameter was missing
ERR_NOT_FOUND	Something was not found from DB (e.g. agent, agent group or campaign).
ERR_NO_COMPANY_FOUND	Company was not found from DB with given Company ID.
ERR_INVALID_FORMAT	Some of the given parameters were wrongly formatted
ERR_DB	There was an error saving the data (please contact customer support)

Example:

Create new callback request by POSTing JSON data into following URI

http://api.leaddesk.com?auth=X&mod=call&cmd=create_callback

   {
   "properties": {
       "phone": "0401234567",
       "type": "private",
       "campaign": "Example Campaign",
       "agent_group": "Example Agent Group",
       "agent": "Example Agent Username",
       "timestamp": "2013-10-10 19:00:00",
       "comment": "Contact returns from vacation today."
   },
   "contact": {
       "fname": "John",
       "lname": "Smith",
       "address": "Oakstreet 5",
       "postcode": "65789",
       "city": "London",
       "country": "England",
       "contact_list": "Example Contact List",
       "other1": "Example data 1",
       "other2": "Example data 2",
       "other35": "Example data 35"
   }
   }

Another example with contactid:

   {
   "properties": {
       "phone": "0401234567",
       "type": "private",
       "campaign": "Example Campaign",
       "agent_group": "Example Agent Group",
       "agent": "Example Agent Username",
       "timestamp": "2013-10-10 19:00:00",
       "comment": "Contact returns from vacation today."
   },
   "contact": {
       "contactid": "12345"
   }
   }

And an example with contactid and return_callback_id:

   {
   "properties": {
       "phone": "0401234567",
       "type": "private",
       "campaign": "Example Campaign",
       "agent_group": "Example Agent Group",
       "agent": "Example Agent Username",
       "timestamp": "2013-10-10 19:00:00",
       "comment": "Contact returns from vacation today."
   },
   "contact": {
       "contactid": "12345"
   },
   "return_callback_id": true
   }

Command: UPLOAD_CALL_RECORDING

With this command the user can upload a call recording file to a call.

NOTE: You must use “http://api-rec.leaddesk.com” when using this command!

Parameters:

Name	Type	Mandatory	Description	Example
call_id	integer	yes	Call ID that needs to match LeadDesk call id.	12345
file	POST file upload	yes	The file data to be uploaded as a POST parameter.
overwrite	enumeration(yes,no)	yes	Whether the upload can overwrite a file with a similar name than the uploaded file.	no

Possible errors:

Error	Description
ERR_NOT_FOUND	No call found from LeadDesk with given call id.
ERR_ARGUMENT_MISSING	At least one mandatory parameter was missing.
ERR_ARGUMENT_INVALID	Argument is wrongly formatted.

Success:

On success will return JSON string:

  {"success":true, "file":"name_of_uploaded_file"}

Examples:

Upload a call recording file for call with id 12345 (note that POST method must be used for “file” argument):

http://api-rec.leaddesk.com?auth=X&mod=call&cmd=upload_call_recording&call_id=12345&overwrite=no

Messaging

---

Command: SEND_AGENT

With send_agent command you can send an LeadDesk private messages to an agent. Sent message will overwrite existing unread message. Parameters:

Name	Type	Mandatory	Description
id	int	yes	Receiver agent’s id
message	string	no	Message to be sent. If you want to delete previous message, then leave this parameter empty.
mode	string	no	Accepted values: append,prepend. Defines how the message will be written. By default the given message will overwrite the existing message.A whitespace will be automatically added after the prepended message or before the appended message if existing message is not empty.

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing (id)
ERR_NOT_FOUND	No such agent was found. Check the id

Success: On success will return a JSON string in the format of:

 {"success":true}

Examples: http://api.leaddesk.com?auth=X&mod=messaging&cmd=send_agent&id=123456&message=Hello%20World&mode=append

Command: SEND_SMS

With the send_sms command you can send SMS messages. Parameters:

Name	Type	Mandatory	Description
sender	string (1 – 24 characters)	yes	Sender. Can be a name or a phone number.
receiver	string (3 – 16 characters)	yes	Receiver’s phone number. Should include the country calling code prefix (eg. +358). If the prefix is not included, the client’s default country code is used.
message	string	yes	SMS message

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ARGUMENT_EMPTY	Mandatory parameter value is empty
ERR_ARGUMENT_LENGTH	Parameter value is too short or too long
ERR_INVALID_FORMAT	Receiver is not a valid phone number
ERR_SMS_FAILED	SMS message could not be sent. Possible the sender is an unauthorized phone number.
ERR_NO_SMS_PROVIDER	No SMS provider is selected for the client

Success: On success will return a JSON string in the format of:

  {"success":true}

Examples: http://api.leaddesk.com?auth=X&mod=messaging&cmd=send_sms&sender=1234&receiver=5678&message=Hello%20World

Report_template

The report template module can be used to manage customer’s report templates.

---

Command: LIST

List report templates from shared and client-specific database. If report template is found from both databases only the one from client-specific is returned. Parameters No parameters Possible errors: Listing should not produce errors. Success: On success will return a JSON array with following structure:

  [
     <Localized name of report template #1>: {
        "id":"12",
        "name":"Manuscript results",
        "localization_key":"report_manuscript_results",
        "query":"http:\/\/login.leaddesk.com\/manuscript_results_report_new.php",
        "type":"visual",
        "lang_id":null,
        "required_features":"manuscript",
        "supports":"1",
        "category":"statistics",
        "visibility":"54",
        "common_db":0
     },
     <Localized name of report template #2>: {
        ...
     },
     ...
  ]

Example: Get listing of report templates: http://api.leaddesk.com?auth=X&mod=report_template&cmd=list

Command: GET

Returns one report template based on name and desired database. Parameters

Name	Type	Description	Mandatory
name	string	report template’s name	yes
common_db	boolean (0/1)	switch to fetch data from common database, default is 0	no

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_NOT_FOUND	Report template was not found

Success: On success will return a JSON string in the format of:

  {
     "id":"12",
     "name":"Manuscript results",
     "localization_key":"report_manuscript_results",
     "query":"http:\/\/login.leaddesk.com\/manuscript_results_report_new.php",
     "type":"visual",
     "lang_id":null,
     "required_features":"manuscript",
     "supports":"1",
     "category":"statistics",
     "visibility":"54",
     "common_db":0
  }

Example: Get “Manuscript results” report template’s information from client-specific database: http://api.leaddesk.com?auth=X&mod=report_template&cmd=get&name=Manuscript+results Get “Manuscript results” report template’s information from common database: http://api.leaddesk.com?auth=X&mod=report_template&cmd=get&name=Manuscript+results&common_db=1

Command: DELETE

Deletes one report template based on name from client-specific database. Parameters

Name	Type	Description	Mandatory
name	string	report template’s name	yes

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_NOT_FOUND	Report template was not found

Success: On success will return an empty JSON string (“[]”). Example:

  Delete "Manuscript results" report template from client-specific database:
  http://api.leaddesk.com?auth=X&mod=report_template&cmd=delete&name=Manuscript+results

Command: ADD

Adds a new report template to the client-specific database. Parameters

Name	Type	Description	Mandatory
name	string	report template’s name	yes
localization_key	string	key used to find the localized name for report template	no
query	string	determines what action will be made	no
type	enum	report template’s type: ‘chart’,’report’,’visual’,’plain’,’mini’,’custom’,’call_dialog_mini’	no
lang_id	int	language identifier	yes
required_features	string	report template’s required features	no
supports	int	bitmask: 1=admin view, 2=sponsor view	yes
category	string	report template’s category	no
visibility	int	Bitmask user level of the agent: 1=agent, 2=admin, 4=teamleader, 8=robot, 16=sponsor, 32=manager	yes

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ALREADY_EXISTS	Report template with same name already exists

Success: On success will return JSON containing the name of the added report template.

 { 
     "name":"Manuscript results"
  }

Example: Insert “Manuscript results” report template to client-specific database: http://api.leaddesk.com?auth=X&mod=report_template&cmd=add&name=Manuscript+results&localization_key=report_manuscript_results&query=http:\/\/login.leaddesk.com\/manuscript_results_report_new.php&type=visual&lang_id=&required_features=manuscript&supports=1&category=statistics&visibility=1

Command: MODIFY

Modifies a report template in the client-specific database. Parameters

Name	Type	Description	Mandatory
name	string	report template’s name	yes
localization_key	string	key used to find the localized name for report template	no
query	string	determines what action will be made	no
type	enum	report template’s type: ‘chart’,’report’,’visual’,’plain’,’mini’,’custom’,’call_dialog_mini’	yes
lang_id	int	language identifier	no
required_features	string	report template’s required features	no
supports	int	bitmask: 1=admin view, 2=sponsor view	yes
category	string	report template’s category	no
visibility	int	Bitmask user level of the agent: 1=agent, 2=admin, 4=teamleader, 8=robot, 16=sponsor, 32=manager	yes

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ALREADY_EXISTS	Report template with same name already exists
ERR_NOT_FOUND	Report template was not found

Success: On success will return an empty JSON string (“[]”). Example: Update “Manuscript results” report template to client-specific database: http://api.leaddesk.com?auth=X&mod=report_template&cmd=modify&name=Manuscript+results&localization_key=report_manuscript_results&query=http:\/\/login.leaddesk.com\/manuscript_results_report_new.php&type=visual&lang_id=&required_features=manuscript&supports=1&category=statistics&visibility=1

 

 

 

Calling_list

---

Command: IMPORT

Command imports a calling list file and creates a new contact list.

Limitations on usage:
– Acceptable file types: xls, xlsx or csv.
– Column headers must be named as they are with the LeadDesk template and be in exact same order. The template can be found from Admin > Contact lists page.
– Current file size limit for calling list import via API is 10 megabytes. Importing larger files return error “ERR_FILE_TOO_LARGE” and the current file size limit.
– Feature ‘Swedish mobile landline calling times’ is not supported at the moment. Feature enables to choose different calling times for only Swedish landline and mobile numbers.
– Importing calling lists through API does not trigger any LeadDesk Hooks.
– NOTICE!!! Content-Type = ‘multipart/form-data’.

Create new calling list parameters:

Name	Type	Description	Default value
create_or_add	enumeration (create, add)	Create new calling list or add contacts to an existing calling list.	create
file	file	The file data to be uploaded as a POST parameter.	mandatory
list_name	string	Name for the calling list.	date(Y-m-d Hi) – filename.extension
legend	string	Legend for the calling list.	(empty)
office	string	Office’s name that will be connected to the calling list. Value can be empty or an existing office’s name.	(empty)
sponsor	string	Sponsor’s name. Value can be empty or an existing sponsor’s name.	(empty)
callinglist_group	string	Name for the calling list group.	(empty)
call_attempts	integer	Max number of call attempts.	3
custom_expiry_date	string	Format: Y-m-d eg. “2014-09-03”.	(empty)
calling_starts	string	Allowed calling time starts. Format: H:i:s eg. “13:41:00”.	00:00:00
calling_ends	string	Allowed calling time ends. Format: H:i:s eg. “18:41:00”.	23:59:59
time_zone	string	Time zone for allowed calling times. Enter time zone as zone name from the tz database. Example: Europe/Helsinki. tz database timezones.	(empty)
skip_auto_format	boolean (0,1)	Disable automatic phone number formatting.	0
keep_list_order	boolean (0,1)	Keep list order (in the list to be uploaded).	0
create_campaign	boolean (0,1)	Create new campaign for the new list.	0
copy_campaign_settings_from	integer	Campaign id specifies the campaign that is used as the source for the campaign settings when creating new campaign with create_campaign parameter set as true. When left unspecified and create_campaign parameter is set as true a campaign will be created with default values.	none
custom_fields (Not implemented yet)	object	Calling list’s custom fields.	(empty)
duplicate_check_enabled	boolean (0,1)	Remove duplicate numbers.	0
add_contacts_without_numbers	boolean (0,1)	Add also contacts without a phone number.	0
b2b_grouping_priority_1	enumeration (none, company, vatin, city, otherinfo1, otherinfo2, otherinfo3, otherinfo4, otherinfo5, otherinfo6)	Used as the first B2B grouping priority. Requires B2B feature.	none
b2b_grouping_priority_2	enumeration (none, company, vatin, city, otherinfo1, otherinfo2, otherinfo3, otherinfo4, otherinfo5, otherinfo6)	Used as the second B2B grouping priority. Requires B2B feature.	none
b2b_global_comments	boolean (0,1)	Sets company’s comments global (NOTE! Only in effect when uploading callinglist! Affects all companies with same name or business ID and global comments are set in campaigns of these companies. If callinglist company’s comment is not set, then latest global comment is fetched from company that has same name or vatin).	0
actions	string	Actions that are permitted for the API and LeadDesk admin users. Comma-separated list of one or more of the following values: “export”, “delete”, “update”, “all”.	all
rights (Not implemented yet)	object	Access rights for selected Admins / Team Leaders. When empty access rights are not limited to certain users.	(empty)
blacklist_select (Not implemented yet)	object	Requires blacklist feature	(empty)

The following are additional parameters to be used when adding contacts to an existing calling list.

Add to calling list parameters (Not released yet):

Name	Type	Description	Default value
create_or_add	enumeration (create, add)	Use ‘add’ when adding to an existing calling list.	create
existing_calling_list_id	integer	Calling list id for which the contacts should be added.	mandatory
add_type	enumeration (before, after, mix)	How to add the new numbers to the existing calling list	after

Possible errors:

Error	Description
ERR_ARGUMENT_INVALID	Argument was invalid or does not exist in db (office, sponsor, custom_expiry_date, calling_starts, calling_ends, time_zone, b2b_grouping_priority_1, b2b_grouping_priority_2)
ERR_ARGUMENT_MISSING	Mandatory parameter was missing (file)
ERR_DETECT_COLUMNS	Unable to detect columns. Use the LeadDesk template
ERR_UNSUPPORTED_FILE	Imported file type is unsupported
ERR_READING_FILE	Error reading imported file
ERR_UNKNOWN	Calling list creation failed for unknown reason
ERR_FILE_TOO_LARGE	Calling list file is too large. Respond will also include the current file size limit.

Success:
On success will return a JSON string containing the id of the created calling list in the format of:

 {"success":true,"id":123456}

Example:
Import a new calling list by POSTing the parameters into the following URI
http://api.leaddesk.com?auth=X&mod=calling_list&cmd=import
curl example
curl -F ‘list_name=name of the list’ -F ‘file=@/path/to/calling_list_file’ ‘http://api.leaddesk.com?auth=X&mod=calling_list&cmd=import’

Raw example

content of raw HTTP request (request.http). Notice that authentication code is not valid and you need to recalculate Content-Length if you change the content.
POST https://api.leaddesk.com?mod=calling_list&cmd=import HTTP/1.1
Host: api.leaddesk.com
Content-Type: multipart/form-data; boundary=—————————13983134122183
Content-Length: 1219

—————————–13983134122183
Content-Disposition: form-data; name=”auth”

12345678901234567890123456789012
—————————–13983134122183
Content-Disposition: form-data; name=”list_name”

test-list-1
—————————–13983134122183
Content-Disposition: form-data; name=”file”; filename=”import-example.csv”
Content-Type: text/csv

Phone number;First name;Last name;E-mail;Company;VAT identification;Title;Address;Zip code;Country;City;Gender;Social security number;Year of birth;Web site;Phone number 2;Phone number 3;Phone number 4;Comment;Other info 1;Other info 2;Other info 3;Other info 4;Other info 5;Other info 6;Other info 7;Other info 8;Other info 9;Other info 10;Other info 11;Other info 12;Other info 13;Other info 14;Other info 15;Other info 16;Other info 17;Other info 18;Other info 19;Other info 20;Other info 21;Other info 22;Other info 23;Other info 24;Other info 25;Other info 26;Other info 27;Other info 28;Other info 29;Other info 30;Other info 31;Other info 32;Other info 33;Other info 34;Other info 35
12345678;sam;smith;sam.smith@somedomain.com;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

—————————–13983134122183–

Example usage from command line (linux nc command)
nc –ssl api.leaddesk.com 443 < request.http

Command: DELETE

Remove contact list from Leaddesk. Actually marks the contact list as deleted, but it will stays in DB. Contacts are not modified in any way. All relations to this calling list will be deleted or cleared.

Parameters:

Name	Type	Mandatory	Description	Example
id	int	yes	Contact list id number	123

Success:
On success will return a JSON string:

  {"success":true}

On failure will return a JSON string (Meaning there was something wrong with the deletion query. Most likely the contact list didn’t have the “delete” action permitted.):

  {"success":false}

Examples:
Delete calling list id 123:
http://api.leaddesk.com?auth=X&mod=calling_list&cmd=delete&id=123

Command: EXPORT

Export a contact list from Leaddesk in csv format.

Parameters:

Name	Type	Mandatory	Description	Example
id	int	yes	Contact list id number	123
extended	boolean (0,1)	no (default is 0)	If enabled the reply will contain an extended set of data like other info fields etc.	0

Possible errors:

Error	Description
ERR_FORBIDDEN	Export is forbidden for the contact list
ERR_NOT_FOUND	Contact list does not exist
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ARGUMENT_INVALID	Mandatory parameter was invalid

Success:
On success will return a csv string (Content-Type: text/csv; charset=utf-8):

  contact id;phone number;first name;last name;address;postal code;city;is finalized(*);contact updated at;phone number updated at;phone number last call date;last call result name;last call campaign name; last call agent name

* is finalized: 1 = number has been marked as used (not be called again), 0 = number is still on contact list

Note that each number of a contact will printed on separate rows:

  contact id;phone number 1;first name;last name;address;postal code;city;is finalized;contact updated at;phone number 1 updated at;phone number 1 last call date;last call result name;last call campaign name; last call agent name
  contact id;phone number 2;first name;last name;address;postal code;city;is finalized;contact updated at;phone number 2 updated at;phone number 2 last call date;last call result name;last call campaign name; last call agent name

Example row:

  123;+3581231234;John;Smith;"Smith street 1";55550;Lappeenranta;1;"2017-01-01 12:00:00";"2017-01-01 12:00:00";"2017-01-01 12:00:00";Deal;"My campaign";"Jane Doe"

The command returns extended data set with extended parameter. On success will return a csv string (Content-Type: text/csv; charset=utf-8):

  contact id;phone number;first name;last name;address;postal code;city;is finalized(*);contact updated at;phone number updated at;phone number last call date;last call result name;last call campaign name; last call agent name;www;country;social security code;year of birth;gender;title;contact comment;company name;company VAT number;<other info fields 1-35>;<other info field names 1-35>

Examples:

  Export calling list id 123:
  http://api.leaddesk.com?auth=X&mod=calling_list&cmd=export&id=123

Command: LIST

Lists non-deleted contact lists. Lists shown in id order. Only the first 5000 lists are shown.

Parameters:

Name	Type	Mandatory	Description	Example
created_at_from	string	no	Time interval start point for contact list creation date (inclusive)	2015-03-01

Possible errors:

Only common errors

Success:
On success will return a JSON string:

  [{"id":123,"name":"my_list","created_at":"2015-03-01"}, {"id":...}]

Examples:
List all contact lists created after date 2015-03-01
http://api.leaddesk.com?auth=X&mod=calling_list&cmd=list&created_at_from=2015-03-01

 

 

 

 

 

 

 

Meta

Meta is generic module designed to handle all kinds of metadata whether it is related to orders or call ending results etc. The idea is that user can store name/value pairs related to an entity, entity being for example a single call ending reason under a campaign.

---

Restrictions:

• entity id, name of metadata and leadapp name form a unique database key. There can be only one row per unique database key. Trying to add same unique key again will result in an error.

Supported meta types (see type parameter under commands):

order	Order related metadata
result	Call ending result related metadata

Command: GET

Get metadata matching given parameters Parameters

Name	Type	Description
type	string	Type of metadata, for example ‘order’ if the meta is order related.	mandatory
id	int	Entity id, for example order id	1)
name	string	Name of the metadata	1)
leadapp	string	Name of the leadpp	1)

1) At least one of these parameters must be defined Possible errors:

Error	Description
ERR_ARGUMENT_INVALID	Mandatory parameter was invalid
ERR_DB	There was an error saving the data

Success: On success will return a JSON string in the format of:

  {"success":true,"meta":<array of matching meta>}

In detail:

   "success":true,
   "meta":{
        {
          "id": "123",
          "name": "nameofthemeta",
          "value": "valueofthemeta",
          "comment": "commentofthemeta",
          "leadapp": "leadapp name",
        },
        {
          "id": "456",
          "name": "nameofthemeta",
          "value": "valueofthemeta",
          "comment": "commentofthemeta",
          "leadapp": "leadapp name",
        }
    }

Example: Get all metadata for call end result id 123, regardless of name and leadapp http://api.leaddesk.com?auth=X&mod=meta&cmd=get&type=result&id=123

Command: CREATE

Creates a meta row Parameters

Name	Type	Description
type	string	Type of metadata, for example ‘order’ if the meta is order related.	mandatory
id	int	Entity id, for example order id	mandatory
leadapp	string	Name of the leadpp.	mandatory
name	string	Name of the metadata	mandatory
value	string	Value of the leadpp
comment	string	Comment of the leadpp

Possible errors:

Error	Description
ERR_ARGUMENT_INVALID	Mandatory parameter was invalid
ERR_DB	There was an error saving the data

Success: On success will return a JSON string in the format of:

  {"success":true}

Example: Insert metadata for call end result id 123, leadapp being ‘testapp’. Name, value and comment are arbitrary. http://api.leaddesk.com?auth=X&mod=meta&cmd=create&type=result&id=123&leadapp=testapp&name=testname&value=testvalue&comment=testcomment

Command: UPDATE

Updates a meta row Parameters

Name	Type	Description
type	string	Type of metadata, for example ‘order’ if the meta is order related.	mandatory
id	int	Entity id, for example order id	mandatory
leadapp	string	Name of the leadpp.	mandatory
name	string	Name of the metadata	mandatory
value	string	New value of the leadpp
comment	string	New comment of the leadpp

Possible errors:

Error	Description
ERR_ARGUMENT_INVALID	Mandatory parameter was invalid
ERR_DB	There was an error saving the data

Success: On success will return a JSON string in the format of:

  {"success":true}

Failure: On failure, for example metadata was not found with given parameters, will return a JSON string in the format of:

  {"success":false}

Example: Update metadata for call end result id 123, leadapp being ‘testapp’. Name, value and comment are arbitrary. http://api.leaddesk.com?auth=X&mod=meta&cmd=update&type=result&id=123&leadapp=testapp&name=testname&value=testvalue&comment=testcomment

Command: DELETE

Deletes a meta row Parameters

Name	Type	Description
type	string	Type of metadata, for example ‘order’ if the meta is order related.	mandatory
id	int	Entity id, for example order id	mandatory
name	string	Name of the metadata	mandatory
leadapp	string	Name of the leadpp.	mandatory

Possible errors:

Error	Description
ERR_ARGUMENT_INVALID	Mandatory parameter was invalid
ERR_DB	There was an error saving the data

Success: On success will return a JSON string in the format of:

  {"success":true}

Example: Delete metadata for call end result id 123, leadapp being ‘testapp. http://api.leaddesk.com?auth=X&mod=meta&cmd=delete&type=result&leadapp=testapp&id=123&name=testname

Result

Command: ADD

---

Adds a call result (aka call ending reason) which can be global (visible in all campaigns) or a campaign specific reason. Returns json encoded array when successful. Restrictions

Global reason	Can’t be assigned to a group or ordered with ‘prepend’ parameter
Copy of global reason	Adding a copy of global reason is not supported. Use campaign specific reason instead

Assigning reason to a group

• If given group name does not exist it is automatically created
• When using ‘group_name’ and ‘prepend’ parameter as true then the reason is placed as the first reason in the given group
  • Using prepend with false value then the reason is appended as the last reason in the given group

Parameters

Name	Type	Description	Default value
name	string	Reason name	mandatory
global	boolean (0,1)	Set reason as global	false
campaign_id	int	Campaign to which reason should be connected. Zero (0) = no campaign connection	0
removes_contact_from_list	boolean (0,1)	When this reason is selected should the contact be removed from the contact list	false
connected_template_id	int	Connected email/sms template id	null
connected_template_sends_automatically	boolean (0,1)	Send the connected template automatically when this reason is selected	false
waiting_period	int	How many hours must pass before the contact can be called again	0
calling_starts	time	The earliest time of the day when the contact can be called. Invalid time value will be set as ’00:00:00′	00:00:00
calling_stops	time	The latest time of the day when the contact can be called. Invalid time value will be set as ’00:00:00′	23:59:59
move_to_list	int	Move contact to specified calling list (id). Zero (0) = does not move to any contact list	0
remove_company	boolean (0,1)	Removes the company (ie. all its contacts). Requires feature ‘B2B’	false
retain_agent	boolean (0,1)	Retain agent assignment when moving contact to other contact list	false
points	decimal (2)	Reason is associated with points. Use a period (.) as the decimal separator. Requires feature ‘points_for_reasons’	0.00
add_to_blacklist	boolean (0,1)	If true contact’s number will be added to blacklist. Requires feature ‘blacklist’	false
blacklist_sponsor_ids	string	Comma separated string of sponsor ids. Default is zero (0) – no sponsor. Requires feature ‘blacklist’	0
group_name	string	Assign reason to group	null
prepend	boolean (0,1)	Prepend reason (true) before or append after (false) existing reasons	false
secondary_waiting_period	int	Waiting period (in hours) for the contact’s other numbers	0
repeat_waiting_period	int	Waiting period (in hours) when the same reason is chosen twice in a row	0
info	string	Information about the reason
transfer_target	string	Transfer the active call to this number once reason is selected	null

Possible errors:

Error	Description
ERR_ARGUMENT_INVALID	Parameter was invalid
ERR_DB	There was an error saving the data

Success: On success will return a JSON string in the format of, id being the id number of the newly created result: {“id”:123, “success”:true} Example:

  Add reason 'global_1':
  http://api.leaddesk.com?auth=X&mod=result&cmd=add&name=global_1&global=1

Example:

  Add campaign specific reason and connect it to a campaign 
  http://api.leaddesk.com?auth=X&mod=result&cmd=add&name=reason&campaign_id=456

Command: COPY

Copies a call result (aka call ending reason), resulting in a new campaign specific call result. Old existing result is either deleted or preserved (parameter). Returns json encoded array when successful. Purpose This method was developed to allow storing history of call result related additional fields (result metadata). The idea was that when result metadata is changed, we create a new reason and mark the old one as deleted. Both results and related metadata will still exist in the database and thus we have history information we can use for reporting. Restrictions

Copying global result

Global results can be copied, but the copy will not be global. Instead it will be attached to a campaign. Global reasons cannot be deleted either.

Parameters

Name	Type	Description
id	int	Call result id	mandatory
campaign_id	int	Campaign id the newly created reason is to be attached to.	mandatory
delete_old	bool	Delete old existing reason if set as true. Default is false.

Possible errors:

Error	Description
ERR_ARGUMENT_INVALID	Mandatory parameter was invalid
ERR_NOT_FOUND	Result cannot be found
ERR_DB	There was an error saving the data

Success: On success will return a JSON string in the format of, id being the id number of the newly created result:

  {"id":123, "success":true}

Example: Copy result id 123 in campaign 456 and preserve old result: http://api.leaddesk.com?auth=X&mod=result&cmd=copy&id=123&campaign_id=456 Example: Copy result id 123 in campaign 456 and delete old result: http://api.leaddesk.com?auth=X&mod=result&cmd=copy&id=123&campaign_id=456&delete_old=true

 

 

Campaign

Campaign module contains campaign-related functionality.

---

Command: ATTACH_CONTACT_LIST

With this command you can attach an existing contact list to an existing campaign. Trying to use non-existing or deleted contact lists or campaigns will result in an error.

Parameters:

Name	Type	Mandatory	Description
campaign_id	integer	yes	Id number of the campaign
contact_list_id	integer	yes	Id number of the contact list
force_attach	boolean (0,1)	no	If 1, deletes previous connections the contact list has and attaches it to the given campaign.If 0 or not set, doesn’t break existing connections for the contact list. Attaches it to the given campaign only if there are no existing connections.

Possible errors:
Common errors

Error	Description
ERR_ALREADY_CONNECTED	Contact list is already connected to a campaign and the “force_attach” parameter was not set

Success:
On success will return an empty JSON string

Examples:
Attach contact list with the id 12345 to the campaign with the id 67890:
http://api.leaddesk.com?auth=X&mod=campaign&cmd=attach_contact_list&campaign_id=67890&contact_list_id=12345

Command: DUPLICATE_CAMPAIGN

With this command you can duplicate an existing campaign. Trying to use non-existing campaigns will result in an error.

Parameters:

Name	Type	Mandatory	Description
campaign_id	integer	yes	Id number of the campaign
new_name	string	yes	The new name of the copied campaign

Possible errors:
Common errors

Error	Description
ERR_ARGUMENT_MISSING	One or more of the parameters is not set
ERR_NOT_FOUND	The used id of campaign (campaign_id) does not exist

Success:
On success will return an JSON string:

   {
       "name": "copiedCampaign",
       "desc": "",
       "receipt_desc": "",
       "calling_order": null,
       "created_at": "2020-04-15 06:13:59",
       "client_id": "1234",
       "progressive_call": "on",
       "manual_call": "on",
       "preview_call": "on",
       "b2b_call": "on",
       "external_url": null,
       "campaign_url": "https://login-1-staging.leaddesk.com/beta/jwt-verify-report/?jwt={jwt}&ld_client_id={ld_client_id}",
       "campaign_url_2": "https://login-1-staging.leaddesk.com/beta/jwt-verify-report/?jwt={jwt}&ld_client_id={ld_client_id}",
       "calling_method": "3",
       "rights_type": "all",
       "voicereceipt_required": "off",
       "order_extURL": null,
       "deleted": "no",
       "external_phone": "on",
       "office": "R&D",
       "confirmation_template": null,
       "agentview_report_id": null,
       "call_dialog_report_id": null,
       "agentview_report_name": null,
       "agents_away_view_report_name": null,
       "call_dialog_report_name": null,
       "agent_sidebar_report_name": null,
       "automatic_report_sending": null,
       "show_call_history": "1",
       "sponsor_id": "Sponsor",
       "confirm_remove_from_list": "yes",
       "shuffle_calling_lists": "no",
       "manuscript_id": "1",
       "mandatory_fields": null,
       "mandatory_save": null,
       "hidden_fields": null,
       "cal_project_id": null,
       "contactmanager_id": null,
       "default_call_tab": "tab-order-1",
       "unanswered_waiting_period": "0",
       "use_skip_number_penalty": "yes",
       "ssc_validation": "0",
       "inbound_blending": "no",
       "b2b_global_comment": "0",
       "max_ringing_time": null,
       "start_recording_paused": "no",
       "calling_time_difference": "0",
       "outbound_caller_id": null,
       "global_waiting_period": "0",
       "default_call_dialog_tab": null,
       "message_public": "[Admin]: test message",
       "agent_selectable": "1",
       "manual_call_tab_ext_url": null,
       "calling_list_selectable": "0",
       "campaign_url_custom_name_1": null,
       "campaign_url_custom_name_2": null,
       "override_agent_caller_id": "0",
       "predictive_forced_auto_answer": "0",
       "contact_waiting_time_answering_machine": "0",
       "contact_waiting_time_busy_answer": "0",
       "margins": null,
       "disabled": "no",
       "agent_session_timeout": "0",
       "repeat_unanswered_waiting_period": "0",
       "predictive_dropped_contact_list_id": "0",
       "type": "outbound",
       "id": "1416"
   }

Examples:

  Duplicate the campaign with the id 1396:
  http://api.leaddesk.com?auth=X&mod=campaign&cmd=duplicate_campaign&campaign_id=1396&new_name=copiedCampaign

 

 

 

 

Multichannel

Multichannel module can be used for handling different types of inbound channels.

Channel types

Different channel types and commands they support.

Type	[post]	[create]	[remove]	Description
url	supported	supported	supported	Generic channel for external tasks that are sent in a form of URL. That URL is opened into a popup for the receiver agent.
imap	–	–	–	IMAP email channel. Received email messages are distributed to free agents.
call	–	–	–	Call queue for inbound calls

Command: LIST

List basic channel information with optional agent statistics Parameters

Name	Type	Description	Mandatory
type	enum(imap/url/call)	Channel type	yes
statistics	bool(1/0)	If enabled then agent statistics for channel’s campaign will be included in the response (total, free, busy)	no (default: 0)

Possible errors: Only common errors Success: On success will return a JSON array of [Channel] models. See Channel model below

Channel model (w/ statistics)

 {
       "id": <id of the channel>,
       "name": <name of the channel>,
       "source_name": <source name of the channel, non modifiable by the admin>,
       "campaign_id": <campaign id this channel is attached into>,
       "statistics": {
           "total": <total amount of agents in same campaign. can be logged out>,
           "free": <total amount of free agents in campaign --> waiting for messages>,
           "busy": <total amount of busy agents in campaign --> handling calls, messages, etc.>
       }
  }

Example: Get the channel information for email (=imap) type channels without statistics http://api.leaddesk.com?auth=X&mod=multichannel&cmd=list&type=imap

  [
      {
          "id": "1",
          "name": "development email queue",
          "source_name": "inbound.queue.123@leaddesk.com",
          "campaign_id": "2422"
      }
  ]

Command: POST

Post a new message into multichannel queue. At the moment only URL type channels will accept posted messages through web API. Parameters

Name	Type	Description	Mandatory
channel_id	int	Channel for the new message. Identified by source id.	yes (mutually exclusive with channel_source)
channel_source	string	Channel for the new message. Identified by source name.	yes (mutually exclusive with channel_id)
[HTTP BODY]	JSON	Message body which is different for each channel type. See below for detailed message models.	yes

Possible errors: Only common errors

URL message model

  {
     "url":<Mandatory: External URL to open for agent>,
     "sender":<Optional: Free text sender/source name e.g. email address, IP address etc>,
     "window":{
        "title":<Optional: Title of the popup agent sees in the UI>
        "type":<Optional: Type of the popup window on UI. Options: "internal" (default), "external">
        "height":<Optional: Height of the popup window's view-port in pixels>
        "width":<Optional: Width of the popup window's view-port in pixels>
     }
  }

Notices

• If you define popup dimensions, then both height and width needs to be defined. They won’t have effect on their own.
• If height or width is below 100, then they are both considered undefined. No error is reported thought.
• Title is not definable in “external” type. Window’s title will be defined by the opened web page.
• LeadDesk Application does not support defining external popup height or width, so they don’t work at the moment (ver 6.40)
• Default size for internal popup is 670×400 (this can change in the future). Default size for external popup is browser dependant. Usually it’s nearly the same as the original window.
• Internal popup means that URL is opened into modal dialog inside the agent UI (jQuery dialog + iframe). Internal messages can only be handled one at a time.
• External popups don’t track agent activity and they are marked as handled immediately when the are received by the agent. Agent will be set back into available state after opening the popup so agent can receive multiple messages or even calls. External messages don’t block the agent’s work flow in any way. He/she can even logout during the handling of external messages.

Success: On success will return a JSON string in the format of:

   {"message_id":<queued_message_id>}

Example: Post new message into URL type of channel http://api.leaddesk.com?auth=X&mod=multichannel&cmd=post&channel_id=1

  {
     "url":"<a class="external free" href="http://login.leaddesk.com/" rel="nofollow">http://login.leaddesk.com</a>",
     "window":{
        "title":"This is LeadDesk login screen"
     }
  }

Command: CREATE

Creates a new channel. Parameters

Name	Type	Description	Mandatory
name	string	Name of the channel. This can be later changed from the Admin panel.	yes
source	string	Source of the channel. No functional meaning, but Admin can’t change this value so it can be used as an reference to external service.	yes
type	string	Type of the channel. Not all types of channels are supported. See list of types.	yes
campaign_id	integer	Campaign id to attach this channel into. If omitted, then channel won’t belong to any campaign. Admin can change the campaign later on.	no

Possible errors: Only common errors Success: On success will return a JSON string in the format of:

  {
    "id":<newly created channels id>
  }

Example: Create a new URL type channel http://api.leaddesk.com?auth=X&mod=multichannel&cmd=create&type=url&name=test-channel&source=test-source

Command: REMOVE

Removes a channel from LeadDesk. Basically this will only hide and disable the channel from LeadDesk. Unhandled messages and messages still in queue will be marked as closed immediately. Will not delete messages received and handled earlier in this channel. Not all types of channels can be removed. See list of channel types. Parameters

Name	Type	Description	Mandatory
id	integer	id of the channel to be removed	yes

Possible errors: Only common errors Success: On success will return an empty JSON string Example: Remove channel by id 1 http://api.leaddesk.com?auth=X&mod=multichannel&cmd=remove&id=1

 

 

Widget

The widget module can be used to manage customer’s widgets.

---

Command: LIST

List common and client specific widgets. If there is a widget by the same name client specific widget details are returned.

Parameters

No parameters

Possible errors:

No command specific errors.

Success:

On success will return a JSON array with following structure:

 [
     <Localized name of widget #1>: {
        "name":"Sponsor Top 5 Sellers Today",
        "localization_key":"widget_top_sellers_today",
        "type":"chart",
        "data_url":"?page=widgets_ajax&cmd=data&id=spDealsMadeTop=today",
        "refresh_interval":"30000",
        "enabled":"yes",
        "supports":"4",
        "required_features":"sponsor_mode",
        "common_db":1
     },
     <Localized name of widget #2>: {
        ...
     },
     ...
  ]
  

Example:
Get listing of widgets:
http://api.leaddesk.com?auth=X&mod=widget&cmd=list

Command: GET

Returns one widget based on name.

Parameters

Name	Type	Description	Mandatory
name	string	widget’s name	yes
common_db	boolean (0/1)	Define if allow only results from shared widget database, default is 0	no

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_NOT_FOUND	Widget was not found

Success:

On success will return a JSON string in the format of:

 {
     "name":"Sponsor Top 5 Sellers Today",
     "localization_key":"widget_top_sellers_today",
     "type":"chart",
     "data_url":"?page=widgets_ajax&cmd=data&id=spDealsMadeTop=today",
     "refresh_interval":"30000",
     "enabled":"yes",
     "supports":"4",
     "required_features":"sponsor_mode",
     "common_db":1
  }

Example:
Get “Sponsor Top 5 Sellers Today” widget’s information from client-specific database:
http://api.leaddesk.com?auth=X&mod=widget&cmd=get&name=Sponsor+Top+5+Sellers+Today

Get “Sponsor Top 5 Sellers Today” widget’s information from common database:
http://api.leaddesk.com?auth=X&mod=widget&cmd=get&name=Sponsor+Top+5+Sellers+Today&common_db=1

Command: DELETE

Deletes one widget based on name from client-specific database.

Parameters

Name	Type	Description	Mandatory
name	string	widget’s name	yes

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_NOT_FOUND	Widget was not found

Success:

On success will return an empty JSON string (“[]”).

Example:
Delete “Sponsor Top 5 Sellers Today” widget from client-specific database:
http://api.leaddesk.com?auth=X&mod=widget&cmd=delete&name=Sponsor+Top+5+Sellers+Today

Command: ADD

Adds a new widget to the client-specific database.

Parameters

Name	Type	Description	Mandatory
name	string	widget’s name	yes
localization_key	string	key used to find the localized name for widget	no
type	string	widget’s type	no
refresh_interval	int	widget’s refreshing interval	yes
enabled	enum (yes/no)	controls widget’s enabled status, default ‘yes’	no
supports	int	bitmask: 1=admin view, 2=sponsor view	yes
required_features	string	widget’s required features	no

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ALREADY_EXISTS	Widget with same name already exists

Success:

On success will return JSON containing the name of the added widget.

  { 
     "name":"Sponsor Top 5 Sellers Today"
  }

Example:
Insert “Sponsor Top 5 Sellers Today” widget to client-specific database:
http://api.leaddesk.com?auth=X&mod=widget&cmd=add&name=Sponsor+Top+5+Sellers+Today&localization_key=widget_top_sellers_today&type=chart&data_url=spDealsMadeTop&refresh_interval=30000&enabled=yes&supports=4&required_features=sponsor_mode

Command: MODIFY

Modifies a widget in the client-specific database.

Parameters

Name	Type	Description	Mandatory
name	string	widget’s name	yes
localization_key	string	key used to find the localized name for widget	no
type	string	widget’s type	no
refresh_interval	int	widget’s refreshing interval	no
enabled	enum (yes/no)	controls widget’s enabled status	no
supports	int	bitmask: 1=admin view, 2=sponsor view	yes
required_features	string	widget’s required features	no

Possible errors:

Error	Description
ERR_ARGUMENT_MISSING	Mandatory parameter was missing
ERR_ALREADY_EXISTS	Widget with same name already exists
ERR_NOT_FOUND	Widget was not found

Success:

On success will return an empty JSON string (“[]”).

Example:
Update “Sponsor Top 5 Sellers Today” widget at client-specific database:
http://api.leaddesk.com?auth=X&mod=widget&cmd=modify&name=Sponsor+Top+5+Sellers+Today&localization_key=widget_top_sellers_today&type=chart&data_url=spDealsMadeTop&refresh_interval=30000&enabled=yes&supports=4&required_features=sponsor_mode