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

Avaliable examples: WordPress subscribers integration

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

Komplett dokumentation över LiveAgent Rest API

Datafield formats

Return messages formats

Error messages formats

API version 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