Agent


Command: CREATE

Command creates a new agent. Command takes the parameters as JSON formatted string in HTTP request’s BODY. Below is the structure of the agent’s data.
Command creates a new agent. Command takes the parameters as JSON formatted string in HTTP request’s BODY. Below is the structure of the agent’s data. JSON Base level:

Name Type Description
account Object Agent’s account information
contact_information Object Agent’s contact information
employment Object Agent’s employment information.
custom_fields Object Contains all agent’s custom field information in json format {“name1″:”value1″,”name2″:”value2”}. Default (empty)

Account Object:

Name Type Description Default value
level string Account level of the created user. NOT SUPPORTED Currently only agent accounts can be created. agent
username string Username of the new agent. Length must be between 2 and 64 characters. mandatory
password string Password of the new agent. By default length must be between 6 and 64 characters. NOTE! Admin can set the minimum number of characters higher with extended security feature. mandatory
inbound_number string Agent’s inbound number. (empty)
lang integer LeadDesk language ID of the agent’s language. Default English. See LeadDesk language IDs under general information. 1
time_zone string Time zone of the Agent. Enter time zone as zone name from the tz database. Example: Europe/Helsinki. tz database timezones (empty)
voip_username string Name of the agent’s voip-account. If client has automatic voip-account designation enabled this parameter will be ignored and the voip-account will be assigned automatically. (empty)
external_id string Agent’s external identifier. (empty)
force_ipaddr boolean (true/false) Force the agent’s ip-address. Requires the extended security feature. false

Contact information Object:

Name Type Description Default value
name string Full name of the new agent. Length must be between 1 and 40 characters. mandatory
address string Agent’s street address. (empty)
postal string Agent’s postal code. (empty)
city string Agent’s city. (empty)
country string Agent’s country. (empty)
email string Agent’s email address. (empty)
workphone string Agent’s work phone. (empty)
phone string Agent’s phone number. (empty)
e_contacts string Agent’s emergency contact. (empty)

Employment Object:

Name Type Description Default value
office string Name of the office in which the new agent will be added to. (empty)
agent_group_id integer ID of the agent group in which the new agent will be added to. (empty)
workshift string Name of the work shift. (empty)
description string Agent’s description. (empty)
employment_start string Date when agent’s employment started YYYY-MM-DD. (empty) if value is not defined in parameter array. Current datetime if empty string is sent
employment enum (active/inactive) Set agent’s employment status. active
bank_acc string Agent’s bank account number. (empty)
ssn string Agent’s social security number. (empty)

Possible errors:

Error Description
ERR_ARGUMENT_MISSING Mandatory parameter was missing (name,username,password)
ERR_NOT_FOUND Something was not found from the database(office, agent_group, language, voip_username, custom_field_name)
ERR_INVALID_FORMAT Some of the given parameters were wrongly formatted
ERR_DB There was an error saving the data (please contact customer support)

Success: On success will return a JSON string containing the id of created agent in the format of: The activity module can be used to manage LeadDesk agents’ activities.

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

Example: Create new agent by POSTing JSON data into following URI http://api.leaddesk.com?auth=X&mod=agent&cmd=create

{
   "account": {
       "level": "agent",
       "username": "user123",
       "password": "pass123",
       "inbound_number": "0123456789",
       "lang": 4,
       "time_zone": "Europe/Helsinki",
       "voip_username": "voip_account_1",
       "external_id": "456789",
       "force_ipaddr": "true"
   },
   "contact_information": {
       "name": "First Last",
       "address": "Street 123",
       "postal": "12345",
       "city": "Helsinki",
       "country": "Finland",
       "email": "user@mail.com",
       "workphone": "123456789",
       "phone": "123456789",
       "e_contacts": "123456789"
   },
   "employment": {
       "office": "Office name",
       "agent_group_id": 123456,
       "workshift": "Day shift",
       "description": "desc",
       "employment_start": "2014-08-01",
       "employment": "active",
       "bank_acc": "123456789123",
       "ssn": "12346-0546"
   },
   "custom_fields": {
       "field1": "value1",
       "field2": "value2"
   }  
}

Command: MODIFY

Command modifies existing agent information. Only parameters given in the request will be updated. Command takes the parameters as JSON formatted string in HTTP request’s BODY. Below is the structure of the agent’s data. JSON Base level:

Name Type Mandatory Description
id int yes Agent’s id number
disable bool   Disable agent account (true/false)
account Object   Agent’s account information
contact_information Object   Agent’s contact information
employment Object   Agent’s employment information.
custom_fields Object   Contains all agent’s custom field information in json format {“name1″:”value1″,”name2″:”value2”}. Default (empty)

Account Object:

Name Type Description
level string Account level of the modified user. NOT SUPPORTED Currently only agent accounts can be modified.
username string Username of the agent. Length must be between 2 and 64 characters.
password string Password of the agent. By default length must be between 6 and 64 characters. NOTE! Admin can set the minimum number of characters higher with extended security feature.
inbound_number string Agent’s inbound number.
lang integer LeadDesk language ID of the agent’s language. See LeadDesk language IDs under general information.
time_zone string Time zone of the Agent. Enter time zone as zone name from the tz database. Example: Europe/Helsinki. tz database timezones
voip_username string Name of the agent’s voip-account. If client has automatic voip-account designation enabled this parameter will be ignored and the voip-account will be assigned automatically.
external_id string Agent’s external identifier.
force_ipaddr boolean (true/false) Force the agent’s ip-address. Requires the extended security feature.

Contact information Object:

Name Type Description
name string Full name of the new agent. Length must be between 1 and 40 characters.
address string Agent’s street address.
postal string Agent’s postal code.
city string Agent’s city.
country string Agent’s country.
email string Agent’s email address.
workphone string Agent’s work phone.
phone string Agent’s phone number.
e_contacts string Agent’s emergency contact.

Employment Object:

Name Type Description
office string Name of the office in which the new agent will be added to.
agent_group_id integer ID of the agent group in which the new agent will be added to.
workshift string Name of the work shift.
description string Agent’s description.
employment_start string Date when agent’s employment started YYYY-MM-DD.
employment enum (active/inactive) Set agent’s employment status.
bank_acc string Agent’s bank account number.
ssn string Agent’s social security number.

Possible errors:

Error Description
ERR_ARGUMENT_MISSING Mandatory parameter was missing (id)
ERR_NOT_FOUND Something was not found from the database(office, agent_group, language, voip_username, custom_field_name)
ERR_INVALID_FORMAT Some of the given parameters were wrongly formatted
ERR_DB There was an error saving the data (please contact customer support)
ERR_USERNAME_TAKEN Agent’s username was already taken.
ERR_NOT_SUPPORTED Function or argument is not supported

Success: On success will return a JSON string:

 {"success":true}

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

{
   "id": 123456,
   "account": {
       "level": "agent",
       "username": "user123",
       "password": "pass123",
       "inbound_number": "0123456789",
       "lang": 4,
       "time_zone": "Europe/Helsinki",
       "voip_username": "voip_account_1",
       "external_id": "456789",
       "force_ipaddr": "true"
   },
   "contact_information": {
       "name": "First Last",
       "address": "Street 123",
       "postal": "12345",
       "city": "Helsinki",
       "country": "Finland",
       "email": "user@mail.com",
       "workphone": "123456789",
       "phone": "123456789",
       "e_contacts": "123456789"
   },
   "employment": {
       "office": "Office name",
       "agent_group_id": 123456,
       "workshift": "Day shift",
       "description": "desc",
       "employment_start": "2014-08-01",
       "employment": "active",
       "bank_acc": "123456789123",
       "ssn": "12346-0546"
   },
   "custom_fields": {
       "field1": "value1",
       "field2": "value2"
   }  
}

Command: SET_CAMPAIGN

With set_campaign command you can attach an agent to a campaign or remove an agent from a campaign. Set “campaign_id” parameter to zero (0) to remove an agent from a campaign. Parameters:

Name Type Mandatory Description
agent_id int yes Agent’s id number
campaign_id int yes Campaign’s id number. Set this parameter to zero (0) if you just want to remove the agent from the current campaign.

Possible errors:

Error Description
ERR_ARGUMENT_MISSING Mandatory parameter was missing
ERR_NOT_FOUND No such agent/campaign was found. Check the ids

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

  {"success":true}

Examples: http://api.leaddesk.com?auth=X&mod=agent&cmd=set_campaign&agent_id=123456&campaign_id=123456

Command: MODIFY_CAMPAIGN_ACCESS

With modify_campaign_access command you can modify the agent’s campaign access rights. Set “campaign_id” parameter to zero (0) to modify the full access right instead of a certain campaign. Full access right does not grant access to campaigns where option “The campaign is selectable by agents with full access rights” is not enabled.

  • Removing access from such campaign is not possible when agent has full access rights.
  • Removing access from a campaign which is agent selectable removes full access right and adds selection right to all campaigns (which are agent selectable) except the one which is going to be removed.
  • When adding full access rights all the campaign specific access rights are revoked.

Parameters:

Name Type Mandatory Description
agent_id int yes Agent’s id number
campaign_id int yes Campaign’s id number. Set “campaign_id” parameter to zero (0) to modify the full access right instead of a certain campaign.
type enum (add, remove) yes Whether access right should be added or removed

Possible errors:

Error Description
ERR_ARGUMENT_MISSING Mandatory parameter was missing
ERR_NOT_FOUND No such agent/campaign was found. Check the ids
ERR_UNABLE_TO_MODIFY Current state is already the same as desired or modification is not possible

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

  {"success":true}

Examples: http://api.leaddesk.com?auth=X&mod=agent&cmd=modify_campaign_access&agent_id=123456&campaign_id=123456&type=add

Command: GET_FIRST_LOGIN_LAST_LOGOUT

Returns first login and last logout for a single day and agent. Parameters:

Name Type Mandatory Description
agent_id int yes Agent’s id number
date string yes Date to get login times for this agent, for example: 2015-01-15

Possible errors:

Error Description
ERR_ARGUMENT_MISSING Mandatory parameter was missing

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

 {"login":"2015-04-16 09:00:00","logout":"2015-04-16 16:00:00"}

Examples: http://api.leaddesk.com?auth=X&mod=agent&cmd=get_first_login_last_logout&agent_id=123456&date=2015-04-16

Command: FIND

Finds an agent with username. Returns id and full name. Parameters:

Name Type Mandatory Description
username string yes Agent’s username

Possible errors:

Error Description
ERR_ARGUMENT_MISSING Mandatory parameter was missing

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

 {"id":123,"name":"Teuvo Teräväinen"}

Examples: http://api.leaddesk.com?auth=X&mod=agent&cmd=find&username=teuvo_admin

Command: CHECK_CREDENTIALS

Checks if username and password match. Command takes the parameters as JSON formatted string in HTTP request’s BODY. Returns agent details as JSON. Parameters:

Name Type Mandatory Description
username string yes Agent’s username
password string yes Agent’s password

Possible errors:

Error Description
ERR_NOT_SUPPORTED Request was not secure (https)
ERR_INVALID_FORMAT Parameters were not JSON
ERR_ARGUMENT_MISSING Mandatory parameter was missing
ERR_NOT_FOUND Username not found or password does not match

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

  {"id":123,"username":""teuvote","name":"Teuvo Teräväinen","level":1,"office":"Lappeenranta"}

Examples: https://api.leaddesk.com?auth=X&mod=agent&cmd=check_credentials

{
    "username": "teuvote",
    "password": "teuword"
}

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

The modify command can be used to change a single contacts info, such as name and address. User needs to know LeadDesk id of the contact to be modified. With this command it’s possible to add phonenumber for contact. 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 from its current calling list. NOTE! You can set “companyid” parameter to zero (0) to completely remove company info from contact. Parameters:

Name Type Mandatory Description Example
contact_id integer yes Contact ID that needs to match LeadDesk contact id. 77429
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 (Notice: you have to give both first and last names for this value to have any effect) John
lname string   Contact’s last name (Notice: you have to give both first and last names for this value to have any effect) 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. This parameter is ignored if the “list” parameter is not set.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.

Success: On success will return JSON string:

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

Examples: Modify Ville Virtanen with id 7438675: http://api.leaddesk.com?auth=X&mod=contact&cmd=modify&contact_id=7438675&fname=Ville&lname=Virtanen&phone=040111222,050333444&birthyear=1956&gender=male

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 (data object can contain more fields):

  {"contact_id":8834511,"data":{"id":"8834511","phone":"0451234567","fname":"John",
"lname":"Smith2","phonenumbers":["0448568374","0453992867","0451234567"]},
"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_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.

Known issues:

  • If a client has more than one product with a same name, the API will pick one of the products, causing the API to behave in a non-deterministic way.

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 cretion 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
http://api.leaddesk.com?auth=X&mod=order&cmd=create


   {
   "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

POST Body (linechanges added for readability)

—————————–2366136306929
Content-Disposition: form-data; name=”auth”
xxxxx
—————————–2366136306929
Content-Disposition: form-data; name=”order_id”
1234567
—————————–2366136306929
Content-Disposition: form-data; name=”file”; filename=”audio-example.mp3″ Content-Type: audio/mpeg
ÿûÄ?????????????????Info???�???�??�ä?€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€€ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ???9LAME3.98r�Í????????�€$�\B??€??�äk˜~T????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????ÿûÄ?�Sðì?™þÂM¾�D�?Øð�ò??ücÿÿÿÿÿà?????»»»»×»b��!ÿ»ñÞã.É“&M9&LþÐM=0??AÏC.ïÄA2w¿ÝÞ?ýÝÜ�@„=±�{ýÒ™†þÿæìiô=G;��išg[›�� gÃȐãá8h�5[b� ‚sšh[Òþ-á«�ò^çL—À¼� *��Š½t$€�À�ƒ�< €�€&�ƲpŒSr�/üB�ÿÿÿÿÿÿæ�ÿÿÿþÇN1$´Ò(ïjªý”Ffq‰�#”Jª«Ñ”Zh(J/8Ô•U?Uß;Ny™ÿµy”‹UaóèÙ¯³ç¯^½zöŒIäê¶,$ñÌu3JÄÍw±dW+¡ŸÅ¸¹* «\[‰P¶‰© T·!ÈtrúAˆSIú=$µÀ¿�§C��Ð�@9�£tzKŒ3”¸ª[•��Zʏ%–Yd²Ë,–Yÿÿÿÿ,²¨` ‚���9e•�˲ÊË*²©&Péa�„D!����®�K•2•t™H”Ò�¥*™�’I¤�i�R%�‰I$Ñ�³Ðî;Nã´ø=Îÿû’Ä-ƒÔ¡¢l!¥þ???4€??�Ã}�˜H¢’)…Ú‘N¤^kjkl‡�� !Òúµqœî¯ž·5¶?¿ÕžÂml‡?[A„ÚÔÚ¥S’QH”Áîz�¤ô‘��d@HÀï��¬ÿ`LAME3.98.2UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU
—————————–2366136306929
Content-Disposition: form-data; name=”overwrite”
no
—————————–2366136306929–

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

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”. See feature page: [1]
  • 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”. See feature page: [2]
  • 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"
}

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 requiredRequired 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”

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

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. 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. and mobile numbers.
– 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

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”

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

 

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":"http://login.leaddesk.com",
     "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