Komplett dokumentation över LiveAgent Rest API

Data fields formats
Return messages formats
Error messages formats
Api v.1
    Agents
        Retrieves agent info and auth token
    Application
        Return application installation date and latest version
    Conversations
        Transfer conversation to another department and/or agent
        Delete conversation
        Delete custom field value in conversation
        Add custom field value to conversation
        Retrieves all conversations by owner, department or subject
        Retrieves conversation info
        Retrieves all conversation messages
        Create new message in conversation
        Create new conversation
        Change status of the conversation
        Unassign a tag from a conversation
        Retrieve a list of tags assigned to a conversation
        Assign tag to a conversation
    Customers
        Delete custom field value in user contact
        Add custom field value to customer
        Retrieves all customers
        Retrieves customer info
        Remove customer from group
        Retrieve customer groups
        Add customer to group
        Register new customer
    Customers groups
        Delete customers group
        Retrieve customers group info
        Retrieve all groups of all customers
        Add customers group
        Change customers group
    Departments
        Retrieve all agents statuses in departmnet
        Retrieve list of departments
        Retrieve department info
    Knowledgebase
        Retrieve a list of all knowledgebase articles
        Knowledgebase search
    Online status
        Agents
        Departments
    Reports
        Agents report
        Channels report
        Departments report
        Performance report
        Tags report
        Tickets Agent availability report
        Tickets Load report
        Tickets SLA Compliance report
        Tickets SLA Log report
        Chats Agent availability report
        Chats availability report
        Chats Load report
        Chats SLA Compliance report
        Chats SLA log report
        Calls Agent availability report
        Calls availability report
        Calls Load report
        Calls SLA Compliance report
        Calls SLA log report
        Ranking agents report
    Suggestion categories
        Retrieves all suggestion categories
    Suggestions
        Create new suggestion
    Tags
        Remove tag
        Retrieve a list of all available tags
        Retrieve tag info
        Add tag
        Change tag
    Overview
        Chats
        Phone calls

Datafield formats

 
Type Description
datetime valid format: YYYY-MM-DD HH:MM:SS. Note: values are in "America/Los_Angeles" timezone by default.
text could be any string or empty
constlist could be only one instance of finite set. Possible values are named in specifice field description.
int integer value greater or equal to zero.
list list of entities. Every entity has its specific column definition.
opdatetime datetime with operator. This field has the same format as 'datetime' except you can use various operators with it.
Possible operators:
eq: equals, example 'eq:2009-11-12 05:02:01' or just '2009-11-12 05:02:01'
neq: NOT equals, example 'neq:2009-11-12 05:02:01'
gt: greater than, example 'gt:2009-11-12 05:02:01'
lt: lower than, example 'lt:2009-11-12 05:02:01'
gte: greater or equals than, example 'gte:2009-11-12 05:02:01'
lte: lower or equals than, example 'lte:2009-11-12 05:02:01'
btw: between of, example 'btw:2009-11-12 05:02:01,2010-10-11 04:01:59'
lk: like, example 'lk:2009-11-12 05:02:01' or you can use wildcard characters '%' (for any number of characters) or ? (for one character) 'lk:2009-01-%' or 'lk:2011-12-01 ??:59:59'
note: if you do not enter any operator, 'eq' will be used as default.


Return messages formats


Return messages are in JSON format by default. But you can change this to XML by adding .xml at the end of call URL.This will give response in JSON:
GET
  http://example.com/api/agents/john@agent.com

We add .xml to call URL and we have response in XML format
GET
  http://example.com/api/agents/john@agent.com.xml

Note: if y ou have PHP YAML extension enabled in your PHP, you could also use .yaml to get response in YAML format.

Error messages formats


400 - Bad request error
You can get this in case your athentification with API key failed because of problem with API key in application.

401 - Forbidden
You can get this in case of failed authentification with wrong key

404 - Not found error
You can get this in case "agnet with email agent@email.com not found"

500 - Common porcessing error
This is the most common error type. You can get this in case "parameter message is missing" or "unable to load conversation"

503 - Service Unavailable
You can get this in case application is unavaliable to process requests - in case of updating and/or installing.

Error response example
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>ERROR</status>
 <statuscode>500</statuscode>
 <errormessage>Example error message</errormessage>
 <debugmessage>debug info</debugmessage>
</response>

API version 1


Agents


Retrieves agent info and auth token

Avaliable from application version: 2.8.2.1
Avaliable examples: WordPress plugin example

Example call
  • General
  • PHP
GET
  http://example.com/api/agents/[agentidentifier]
 

Mandatory parameters

Name Type Description
[agentidentifier] text Agent identifier. Can be email or userid.
apikey text API key


Call response description
 

Return fields

Name Type Description
contactid text Id of agent contact.
userid text Id of agent, also known as userid.
email text Agent email.
firstname text Agent first name.
lastname text Agent last name.
systemname text Agent system name.
authtoken text Agent auth token.
browsercookiename text Agent browser cookie name.
gender constlist Agent gender. (Possible values: M - Male, F - Female)
role constlist Agent role. (Possible values: D - Administrator, A - Agent, O - Owner)

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <contactid>d44t87a5</contactid>
 <userid>uid1234</userid>
 <email>example@agent.com</email>
 <firstname>John</firstname>
 <lastname>Williams</lastname>
 <systemname>system001</systemname>
 <authtoken>5ceef21647f1db39a18cafc0bc2de015</authtoken>
 <browsercookiename>A_auth</browsercookiename>
 <gender>F</gender>
 <role>D</role>
</response>



Application


Return application installation date and latest version

Avaliable from application version: 2.8.12.1

Example call
  • General
  • PHP
GET
  http://example.com/api/application/status
 

Mandatory parameters

Name Type Description
apikey text API key


Call response description
 

Return fields

Name Type Description
liveagentversion text Latest application version
gpfversion text Latest framework version
dateinstalled datetime Date of Application installation
datelatestupdate datetime Date of latest update

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <liveagentversion>2.8.5.4</liveagentversion>
 <gpfversion>1.7.8.4</gpfversion>
 <dateinstalled>2012-04-05 11:22:31</dateinstalled>
 <datelatestupdate>2012-08-05 12:13:05</datelatestupdate>
</response>



Conversations


Transfer conversation to another department and/or agent

Avaliable from application version: 2.8.2.1

Example call
  • General
  • PHP
PUT
  http://example.com/api/conversations/[conversationid]/attendants
Note: You must send parameters for this call as PUT fields.
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
apikey text API key
 

Optional parameters

Name Type Description
agentidentifier text Agent identifier. Could be mail or userid.
useridentifier text User identifier (could be mail or userid) who will transfer the conversation. If undefined, user "System" will be used.
department text Id of the department.
messages text List of messages.


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Delete conversation

Avaliable from application version: 2.8.2.1

Example call
  • General
  • PHP
DELETE
  http://example.com/api/conversations/[conversationid]
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
apikey text API key
 

Optional parameters

Name Type Description
messages text List of messages
useridentifier text Agent identifier. Could be mail or userid. If not set, user "System" will be used.


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Delete custom field value in conversation

Avaliable from application version: 4.16.4.1

Example call
  • General
  • PHP
DELETE
  http://example.com/api/conversations/[conversationid]/fields
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
apikey text API key
 

Optional parameters

Name Type Description
code text Custom field name to be deleted from conversation. If not specified, all fields will be deleted from conversation.


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Add custom field value to conversation

Avaliable from application version: 4.16.4.1

Example call
  • General
  • PHP
POST
  http://example.com/api/conversations/[conversationid]/fields
Note: You must send parameters for this call as POST fields.
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
customfields json Add custom field values (Same field can be added multiple times, if you need to update existing field value, delete it first). Json encoded array of custom fields. Example value: [{"code":"varsymbol","value":"43894209"},{"code":"anotherfield","value":"test value"}]
apikey text API key


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Retrieves all conversations by owner, department or subject

Avaliable from application version: 2.8.2.1

Example call
  • General
  • PHP
GET
  http://example.com/api/conversations
 

Mandatory parameters

Name Type Description
apikey text API key
 

Optional parameters

Name Type Description
owneridentifier text Conversations owner identifier. Could be mail.
department text Department identifier
status text Load only conversations with given status. It can contain one specific status, or multiple statuses separated by comma. Example: status=R,T,C. This parameter is avaliable from version 2.8.12.1
datefrom datetime Load only conversations older than this date
dateto datetime Load only conversations younger than this date
datechanged opdatetime Date of last conversation change
subject text Load only conversations with specific subject - avail. from version 3.0.1.2


Note: You need to enter department or owneridentifier or both. If you forget to enter at least one of them call ends up with an exception.

Call response description
 

Return fields

Name Type Description
conversations list Conversations list
Field conversations has 12 columns:
conversationid text Id of conversation
code text Conversation code
datecreated datetime Date created
datechanged datetime Date of last change
departmentname text Department name
departmentid text Department id
status constlist Conversation status (Possible values: A - Answered, P - Calling, T - Chatting, X - Deleted, B - Spam, I - Init, C - Open, R - Resolved, N - New, W - Postponed)
ownername text Name of conversation owner
owneremail text Email of conversation owner
subject text Conversation subject
preview text Conversation preview
publicurlcode text Public URL code

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <conversations>
  <conversation>
   <conversationid>s4y7t5s7</conversationid>
   <code>AX4-B4T-FD8</code>
   <datecreated>2012-03-02 11:21:04</datecreated>
   <datechanged>2012-03-02 11:21:05</datechanged>
   <departmentname>Department 1</departmentname>
   <departmentid>a5j9t4d8</departmentid>
   <status>A</status>
   <ownername>John Owner</ownername>
   <owneremail>john@owner.com</owneremail>
   <subject>Test ticket</subject>
   <preview>this is test ticket</preview>
   <publicurlcode>bI5fR3oN40708G65</publicurlcode>
  </conversation>
  <conversation>
   <conversationid>5h7t58d9</conversationid>
   <code>D5S-55S-A9A</code>
   <datecreated>2012-03-02 12:21:04</datecreated>
   <datechanged>2012-03-02 12:21:05</datechanged>
   <departmentname>Department 1</departmentname>
   <departmentid>a5j9t4d8</departmentid>
   <status>A</status>
   <ownername>John Silver</ownername>
   <owneremail>john@silver.com</owneremail>
   <subject>My ticet</subject>
   <preview>this my ticket</preview>
   <publicurlcode>xU6fR3zN40708G65</publicurlcode>
  </conversation>
 </conversations>
</response>


Retrieves conversation info

Avaliable from application version: 2.8.2.1

Example call
  • General
  • PHP
GET
  http://example.com/api/conversations/[conversationid]
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
apikey text API key


Call response description
 

Return fields

Name Type Description
conversationid text Id of conversation
code text Conversation code
datecreated datetime Date created
datechanged datetime Date of last change
departmentname text Department name
departmentid text Department id
status constlist Conversation status (Possible values: A - Answered, P - Calling, T - Chatting, X - Deleted, B - Spam, I - Init, C - Open, R - Resolved, N - New, W - Postponed)
ownername text Name of conversation owner
owneremail text Email of conversation owner
subject text Conversation subject
ownernote text Conversation owner note - avail. from version 2.8.12.X+
preview text Conversation preview
publicurlcode text Public URL code
assignedto text Identifier of agent which is this conversation assigned to
customfields list Custom field values
Field customfields has 2 columns:
code text Custom field code.
value text Custom field value.

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <conversationid>cid00001</conversationid>
 <code>C01-D54-E45</code>
 <datecreated>2012-04-01 00:15:11</datecreated>
 <datechanged>2012-04-01 00:15:21</datechanged>
 <departmentname>Department 1</departmentname>
 <departmentid>dep1s5a4</departmentid>
 <status>R</status>
 <ownername>John Doe</ownername>
 <owneremail>owner@example.com</owneremail>
 <subject>My first ticket</subject>
 <ownernote>
 </ownernote>
  <preview>Hello, this is my first ticket...</preview>
  <publicurlcode>bI5fR3oN40708G65</publicurlcode>
  <assignedto>
  </assignedto>
   <customfields>
    <customfield>
     <code>varsymbol</code>
     <value>423874698</value>
    </customfield>
    <customfield>
     <code>other_var</code>
     <value>Example value of custom field</value>
    </customfield>
   </customfields>
  </response>


Retrieves all conversation messages

Avaliable from application version: 2.8.2.1

Example call
  • General
  • PHP
GET
  http://example.com/api/conversations/[conversationid]/messages
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
apikey text API key
 

Optional parameters

Name Type Description
datefrom datetime Load messages only older than this date.
dateto datetime Load messages only newer than this date.


Call response description
 

Return fields

Name Type Description
groups list Message groups list.
Field groups has 7 columns:
messagegroupid text Id of the group.
userid text Id of the user who created the group.
rtype constlist Type of the group. (Possible values: P - Type call, V - Type outgoing call, 1 - Type internal call, C - Type chat, X - Type delete, F - Type facebook, I - Type internal, Z - Type internal (collapsed by default), K - Type knowledgebase, A - Type knowledgebase start, M - Type offline, R - Type resolve, Y - Type retweet, S - Type startinfo, G - Type tag, T - Type transfer, W - Type twitter)
rstatus constlist Status of the group (Possible values: D - Status deleted, P - Status promoted, V - Status visible, S - Status splitted)
datecreated datetime Date of creation
datefinished datetime Date ofter latest message
messages list List of messages
Field messages has 5 columns:
messageid text Id of the message
userid text Id of the message user
rtype constlist Type of the message (Possible values: D - Type call, E - Type end, F - Type file, Z - Type formfield, H - Type header, I - Type internal, M - Type message, B - Type splitted, X - Type mixed message, N - Type note, L - Type note file, Q - Type quoted text, C - Type ranking comment, P - Type ranking rebuke, W - Type ranking reward, J - Type statis, S - Type system, G - Type tag, O - Type footer, A - Type header, T - Type title, R - Type transfer, U - Type useragent, V - Type voice)
datecreated datetime Date of message creation
message text Message body

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <groups>
  <group>
   <userid>uid12345</userid>
   <rtype>M</rtype>
   <rstatus>V</rstatus>
   <datecreated>2012-04-03 12:21:21</datecreated>
   <datefinished>2012-04-03 12:31:21</datefinished>
   <messages>
    <message>
     <messageid>mid00003</messageid>
     <userid>uid00001</userid>
     <rtype>M</rtype>
     <datecreated>2012-04-03 12:25:21</datecreated>
     <message>hello, this is example message</message>
    </message>
   </messages>
  </group>
  <group>
   <userid>uid12346</userid>
   <rtype>M</rtype>
   <rstatus>V</rstatus>
   <datecreated>2012-04-03 12:41:21</datecreated>
   <datefinished>2012-04-03 13:21:21</datefinished>
   <messages>
    <message>
     <messageid>mid00004</messageid>
     <userid>uid00001</userid>
     <rtype>M</rtype>
     <datecreated>2012-04-03 18:21:21</datecreated>
     <message>hello, this is example message</message>
    </message>
    <message>
     <messageid>mid00005</messageid>
     <userid>uid00001</userid>
     <rtype>M</rtype>
     <datecreated>2012-04-03 19:21:21</datecreated>
     <message>hello, this is example message</message>
    </message>
   </messages>
  </group>
 </groups>
</response>


Create new message in conversation

Avaliable from application version: 2.8.2.1

Example call
  • General
  • PHP
POST
  http://example.com/api/conversations/[conversationid]/messages
Note: You must send parameters for this call as POST fields.
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
message text Message body (must be UTF-8)
apikey text API key
 

Optional parameters

Name Type Description
useridentifier text Agent identifier. Could be mail or userid. If not set, user "System" will be used.
type constlist Message type. (Possible values: M - Message, N - Note)
mail_messsage_id text Mail message id. If specified, all reply emails which will have given mail message id in in-reply-to header will be assigned to this conversation.
do_not_send_mail constlist Disables sending mail to customer. Can be used when mail was already sent by an external system (Possible values: Y - Yes, N - No)
is_html_message constlist Set this to Y is the message text is formatted in html (Possible values: Y - Yes, N- No)


Note: When useridentifier is emtpy only notes are created - even when type="M"

Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Create new conversation

Avaliable from application version: 2.8.2.1

Example call
  • General
  • PHP
POST
  http://example.com/api/conversations
Note: You must send parameters for this call as POST fields.
 

Mandatory parameters

Name Type Description
message text Message body
useridentifier text Ticket creator identifier - can be userid or email of an existing agent or customer
department text Department identifier - id of the department (not its name)
subject text Message subject
recipient text Recipient email
apikey text API key
 

Optional parameters

Name Type Description
recipient_name text Recipient name in format "Firstname Lastname"
cc text Another recipients emails separated by comma.
status constlist Status of created conversation. If not set, conversation status will be "N" - new. (Possible values: A - Answered, P - Calling, T - Chatting, X - Deleted, B - Spam, I - Init, C - Open, R - Resolved, N - New, W - Postponed)
mail_messsage_id text Mail message id. If specified, all reply emails which will have given mail message id in in-reply-to header will be assigned to this conversation.
do_not_send_mail constlist Disables sending a mail to customer. Can be used when mail was already sent by an external system (Possible values: Y - Yes, N - No)
is_html_message constlist Set this to Y is the message text is formatted in html (Possible values: Y - Yes, N- No)
customfields json Set custom field values. Json encoded array of custom fields. Example value: [{"code":"varsymbol","value":"43894209"},{"code":"another_field","value":"test value"}]


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request
conversationid text Id of conversation
code text Code of conversation
publicurlcode text Public URL code of conversation

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
 <conversationid>cid00001</conversationid>
 <code>
 </code>
  <publicurlcode>
  </publicurlcode>
  </response>


Change status of the conversation

Avaliable from application version: 2.8.2.1

Example call
  • General
  • PHP
PUT
  http://example.com/api/conversations/[conversationid]/status
Note: You must send parameters for this call as PUT fields.
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
status constlist Conversation status. (Possible values: A - Answered, R - Resolved, C - Open)
apikey text API key
 

Optional parameters

Name Type Description
useridentifier text Agent identifier. Could be mail or userid. If not set, user "System" will be used.
note text Note


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Unassign a tag from a conversation

Avaliable from application version: 4.0.36.0

Example call
  • General
  • PHP
DELETE
  http://example.com/api/conversations/[conversationid]/tags
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
apikey text API key
 

Optional parameters

Name Type Description
id text Identifier of the tag. Either id or name must be specified.
name text Name of the tag. Either id or name must be specified.


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Retrieve a list of tags assigned to a conversation

Avaliable from application version: 4.0.30.6

Example call
  • General
  • PHP
GET
  http://example.com/api/conversations/[conversationid]/tags
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
apikey text API key


Call response description
 

Return fields

Name Type Description
tags list The list of tags assigned.
Field tags has 2 columns:
id text The identifier of the tag.
name text Name of the tag.

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <tags>
  <tag>
   <id>sh3j</id>
   <name>VIP</name>
  </tag>
  <tag>
   <id>8sd5</id>
   <name>Support</name>
  </tag>
 </tags>
</response>


Assign tag to a conversation

Avaliable from application version: 4.0.30.6

Example call
  • General
  • PHP
POST
  http://example.com/api/conversations/[conversationid]/tags
Note: You must send parameters for this call as POST fields.
 

Mandatory parameters

Name Type Description
[conversationid] text Conversation ID or code or public url code
apikey text API key
 

Optional parameters

Name Type Description
id text Identifier of the tag.
name text Name of the tag.


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>



Customers


Delete custom field value in user contact

Avaliable from application version: 4.16.4.1

Example call
  • General
  • PHP
DELETE
  http://example.com/api/customers/[customeridentifier]/fields
 

Mandatory parameters

Name Type Description
[customeridentifier] text Customer identifier (email or contactid)
apikey text API key
 

Optional parameters

Name Type Description
code text Custom field name to be deleted from contact. If not specified, all custom fields will be deleted from contact.


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Add custom field value to customer

Avaliable from application version: 4.16.4.1

Example call
  • General
  • PHP
POST
  http://example.com/api/customers/[customeridentifier]/fields
Note: You must send parameters for this call as POST fields.
 

Mandatory parameters

Name Type Description
[customeridentifier] text Customer identifier (email or contactid)
customfields json Add custom field values (Same field can be added multiple times, if you need to update existing field value, delete it first). Json encoded array of custom fields. Example value: [{"code":"varsymbol","value":"43894209"},{"code":"another_field","value":"test value"}]
apikey text API key


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Retrieves all customers

Avaliable from application version: 2.8.2.1

Example call
  • General
  • PHP
GET
  http://example.com/api/customers
 

Mandatory parameters

Name Type Description
apikey text API key
 

Optional parameters

Name Type Description
email text Match email address like *string*
firstname text Match first name like *string*
lastname text Match last name like *string*
datecreatedfrom datetime Load only customers created after this date
datecreatedto datetime Load only customers created before this date
limitcount text Max count of returned rows (Max allowed value is 1000, Default value is 100)
limitfrom text Start from specified row number


Call response description
 

Return fields

Name Type Description
customers list Customers list
Field customers has 9 columns:
contactid text Id of customer contact
email text Customer email
firstname text Customer first name
lastname text Customer last name
systemname text Customer system name
userid text Customer userid
datecreated datetime Date created
role constlist Customer role (Possible values: V - Visitor, R - Registered visitor)
gender constlist Customer gender (Possible values: M - Male, F - Female)

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <customers>
  <customer>
   <contactid>cid00001</contactid>
   <email>john@example.com</email>
   <firstname>John</firstname>
   <lastname>Doe</lastname>
   <systemname>system001</systemname>
   <userid>uid00001</userid>
   <datecreated>2012-03-02 11:21:04</datecreated>
   <gender>M</gender>
  </customer>
  <customer>
   <contactid>cid00002</contactid>
   <email>Janet@example.com</email>
   <firstname>Janet</firstname>
   <lastname>Doe</lastname>
   <systemname>system002</systemname>
   <userid>uid00002</userid>
   <datecreated>2013-05-02 10:23:02</datecreated>
   <gender>M</gender>
  </customer>
 </customers>
</response>


Retrieves customer info

Avaliable from application version: 2.9.5.0
Example call
  • General
  • PHP
GET
  http://example.com/api/customers/[customeridentifier]
 

Mandatory parameters

Name Type Description
[customeridentifier] text Customer identifier (email or contactid)
apikey text API key


Call response description
 

Return fields

Name Type Description
contactid text Id of customer contact
email text Customer email
firstname text Customer first name
lastname text Customer last name
systemname text Customer system name
authtoken text Customer browser cookie identification
browsercookiename constlist Customer browser cookie name (Possible values: V_auth - Registerd visitor cookie name, LaVisitorId - Not yet registered visitor cookie name)
role constlist Customer role. (Possible values: V - Visitor, R - Registered visitor)
gender constlist Customer gender (Possible values: M - Male, F - Female)
userid text Customer userid
datecreated datetime Date created
customfields list Custom field values
Field customfields has 2 columns:
code text Custom field code.
value text Custom field value.

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <contactid>cid00001</contactid>
 <email>john@example.com</email>
 <firstname>John</firstname>
 <lastname>Doe</lastname>
 <systemname>system001</systemname>
 <authtoken>4fsd5f4s6f4s56f4s56f4s56f4sd56</authtoken>
 <browsercookiename>V_auth</browsercookiename>
 <role>V</role>
 <gender>M</gender>
 <userid>uid00001</userid>
 <datecreated>2012-03-02 11:21:04</datecreated>
 <customfields>
  <customfield>
   <code>varsymbol</code>
   <value>423874698</value>
  </customfield>
  <customfield>
   <code>other_var</code>
   <value>Example value of custom field</value>
  </customfield>
 </customfields>
</response>


Remove customer from group

Avaliable from application version: 2.9.5.0

Example call
  • General
  • PHP
DELETE
  http://example.com/api/customers/[customeridentifier]/groups?name=[value]
 

Mandatory parameters

Name Type Description
[customeridentifier] text Customer identifier (email or contactid)
name text Customer group name
apikey text API key


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Retrieve customer groups

Avaliable from application version: 2.9.5.0

Example call
  • General
  • PHP
GET
  http://example.com/api/customers/[customeridentifier]/groups
 

Mandatory parameters

Name Type Description
[customeridentifier] text Customer identifier (email or contactid)
apikey text API key


Call response description
 

Return fields

Name Type Description
groups list List of all customer groups
Field groups has 2 columns:
groupid text Group id
groupname text Group name

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <groups>
  <group>
   <groupid>ag0h</groupid>
   <groupname>VIP</groupname>
  </group>
  <group>
   <groupid>2kt8</groupid>
   <groupname>Premium</groupname>
  </group>
 </groups>
</response>


Add customer to group

Avaliable from application version: 2.9.5.0

Example call
  • General
  • PHP
POST
  http://example.com/api/customers/[customeridentifier]/groups
Note: You must send parameters for this call as POST fields.
 

Mandatory parameters

Name Type Description
[customeridentifier] text Customer identifier (email or contactid)
name text Customer group name
apikey text API key


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Register new customer

Avaliable from application version: 2.9.5.0

Example call
  • General
  • PHP
POST
  http://example.com/api/customers
Note: You must send parameters for this call as POST fields.
 

Mandatory parameters

Name Type Description
apikey text API key
 

Optional parameters

Name Type Description
email text Customer email
name text Customer name in format "Firstname Lastname"
gender constlist Gender (Possible values: M - Male, F - Female)
role constlist Role (Possible values: V - Visitor, R - Registered visitor)
password text Sets password for registerred visitor only. If empty, standard email notification is send to visitor with request to set his password.
customfields json Set custom field values. Json encoded array of custom fields. Example value: [{"code":"varsymbol","value":"43894209"},{"code":"another_field","value":"test value"}]


Call response description
 

Return fields

Name Type Description
contactid text Id of customer contact
email text Customer email
firstname text Customer first name
lastname text Customer last name
systemname text Customer system name
authtoken text Customer browser cookie identification
browsercookiename constlist Customer browser cookie name (Possible values: V_auth - Registerd visitor cookie name, LaVisitorId - Not yet registered visitor cookie name)
role constlist Customer role. (Possible values: V - Visitor, R - Registered visitor)
gender constlist Customer gender (Possible values: M - Male, F - Female)
userid text Customer userid
datecreated datetime Date created
customfields list Custom field values
Field customfields has 2 columns:
code text Custom field code.
value text Custom field value.

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <contactid>cid00001</contactid>
 <email>john@example.com</email>
 <firstname>John</firstname>
 <lastname>Doe</lastname>
 <systemname>system001</systemname>
 <authtoken>4fsd5f4s6f4s56f4s56f4s56f4sd56</authtoken>
 <browsercookiename>V_auth</browsercookiename>
 <role>V</role>
 <gender>M</gender>
 <userid>uid00001</userid>
 <datecreated>2012-03-02 11:21:04</datecreated>
 <customfields>
  <customfield>
   <code>varsymbol</code>
   <value>423874698</value>
  </customfield>
  <customfield>
   <code>other_var</code>
   <value>Example value of custom field</value>
  </customfield>
 </customfields>
</response>



Customers groups


Delete customers group

Avaliable from application version: 4.17.1.3

Example call
  • General
  • PHP
DELETE
  http://example.com/api/customersgroups/[groupid]
 

Mandatory parameters

Name Type Description
[groupid] text Customers group ID
apikey text API key


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>


Retrieve customers group info

Avaliable from application version: 4.17.1.3

Example call
  • General
  • PHP
GET
  http://example.com/api/customersgroups/[groupid]
 

Mandatory parameters

Name Type Description
[groupid] text Customers group ID
apikey text API key


Call response description
 

Return fields

Name Type Description
id text Id of customers group
name text Name of the customers group
color text Color for title
bg_color text Color for background

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <id>sh3j</id>
 <name>VIP</name>
 <color>FFFFFF</color>
 <bg_color>0000FF</bg_color>
</response>


Retrieve all groups of all customers

Avaliable from application version: 4.0.19.1

Example call
  • General
  • PHP
GET
  http://example.com/api/customersgroups
 

Mandatory parameters

Name Type Description
apikey text API key


Call response description
 

Return fields

Name Type Description
groups list List all groups of all customers
Field groups has 2 columns:
id text Group id
name text Group name

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <groups>
  <group>
   <id>ag0h</id>
   <name>VIP</name>
  </group>
  <group>
   <id>2kt8</id>
   <name>Premium</name>
  </group>
 </groups>
</response>


Add customers group

Avaliable from application version: 4.17.1.3

Example call
  • General
  • PHP
POST
  http://example.com/api/customersgroups
Note: You must send parameters for this call as POST fields.
 

Mandatory parameters

Name Type Description
name text Name of the customers group
apikey text API key
 

Optional parameters

Name Type Description
color text Color for name
bg_color text Color for background


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request
id text Id of tag
name text Name of tag
color text Color for name
bg_color text Color for background

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
 <id>sh3j</id>
 <name>VIP</name>
 <color>FFFFFF</color>
 <bg_color>0000FF</bg_color>
</response>


Change customers group

Avaliable from application version: 4.17.1.3

Example call
  • General
  • PHP
PUT
  http://example.com/api/customersgroups/[groupid]
Note: You must send parameters for this call as PUT fields.
 

Mandatory parameters

Name Type Description
[groupid] text Customers group ID
apikey text API key
 

Optional parameters

Name Type Description
name text Name of the customers group
color text Color for name
bg_color text Color for background


Call response description
 

Return fields

Name Type Description
status text OK
statuscode int Status code of executed request

Example responses
  • XML
  • JSON
<?xml version='1.0' encoding='utf-8'?>
<response>
 <status>OK</status>
 <statuscode>0</statuscode>
</response>



Departments


Retrieve all agents statuses in departmnet

Avaliable from application version: 2.8.2.1
Avaliable examples: Wordpress widget example

Example call
  • General
  • PHP
GET
  http://example.com/api/departments/[departmentid]/agents
 

Mandatory parameters

Name Type Description
[departmentid] text Department ID
apikey text API key


Call response description
 

Return fields

Name Type Description
agents list List of all agents in department
Field agents has 6 columns:
userid text Agent userid
firstname text Agent first name
lastname text Agent last name