********************************************************************************************************************
Cowtacular API Calls
********************************************************************************************************************

Cowtacular has some basic API functions that allow external applications to
interact with it.  All calls are
made using a simple REST call.  All calls return an XML document with the
exception of the AUTHCODE call.

All calls are required to have the following information set.
	
	apipassword=xxxxxxx	This should match the API password as set in
the Admin,System menu
	module=API		This only exists to match the rest of the
system design and always
				should be set to the value API.
	action=yyyyyyy		This indicates what kind of API call you are
making.

And example API call might look like

	http://serverurl/api.php?apipassword=1234567890&module=API&action=SYSTEMCHECK



===================================================================================================================
SYSTEMCHECK
===================================================================================================================
This call tests if the database is working properly and you put in a correct
apipassword.

There are no values to pass

Example:
	http://serverurl/api.php?apipassword=1234567890&module=API&action=SYSTEMCHECK

Results:
	OK



===================================================================================================================
AUTHCODE
===================================================================================================================
This call will return part of a URL with a temporary AUTHCODE.  This
authcode is only valid once and must be used
within 5 minutes.  

Either POST or GET the following fields:
	EMAIL=			Text (< 80 characters) - Email of the rep
you want an authcode for

Example:
	http://serverurl/api.php?apipassword=1234567890&module=API&action=AUTHCODE&EMAIL=cvanhorn@cowtacular.com

Results:
	AUTHCODE=0987654321&AUTHREPID=10000035

You can then append these results to the rep.php? URL to gain access.
	http://serverurl/rep.php?AUTHCODE=0987654321&AUTHREPID=10000035




===================================================================================================================
GENERATETICKET
===================================================================================================================
This call will generate a new ticket or update an existing ticket if a
non-closed ticket with the same
subject and email is found.

Either POST or GET the following fields

	Fields required:
	  EMAIL=		Text (< 80 Characters)
  	  SUBJECT=		Text (< 40 Characters)
  	  DESCRIPTION=		Text (< 8000 Characters)
  	Fields that are optional:
  	  CATEGORYID=		List Select ID
  	  GROUPID=		List Select ID
  	  STATUSID=		List Select ID
  	  PRIORITYID=  		List Select ID
  	  SUBMITTERIP=  	x.x.x.x
  	  PRIVATE=  		1,0

Note: You must make sure each subject line is UNIQUE!  If the
      api finds a matching subject line for an open ticket,
      it will add the description as a note and not as a new
      ticket.

Example: 
  Create a critical server down ticket
  http://serverurl/api.php?apipassword=1234567890&module=API&action=GENERATETICKET&EMAIL=cvanhorn@cowtacular.com&GROUPID=1000170&PRIORITYID=1000276&CATEGORYID=1000248&PRIVATE=1&SUBJECT=EMAILSERVER&DESCRIPTION=Email_Server_is_down

Results:
  
    
      value
      value
    
    
      Error description
    
  



===================================================================================================================
GETOBJECTS
===================================================================================================================
This call will return objects that match a basic query.  They are not sorted
in any way.

Either POST or GET the following fields

	OBJECTTYPE=		TICKET,DEVICE,SOFTWARE,SOFTWARELICENSE
	
	FIELD[x]=		Field name
	TEST[x]=		eq,neq,lt,gt,contains
	VALUE[x]=		Value to test against
	   x = a valid integer > 0

Example:
  Get all tickets by cvanhorn@cowtacular.com that are not private
  http://serverurl/api.php?apipassword=1234567890&module=API&action=GETOBJECTS&OBJECTTYPE=TICKET&FIELD[0]=EMAIL&TEST[0]=eq&VALUE[0]=cvanhorn@cowtacular.com&FIELD[1]=PRIVATE&TEST[1]=neq&VALUE[1]=1

Results:

  
    
      value
      value
    
    
      Error description
    
  



===================================================================================================================
GETOBJECTTYPES
===================================================================================================================
This call returns a list of valid object types that the system knows about

There are no values to pass

Example:

http://serverurl/api.php?apipassword=1234567890&module=API&action=GETOBJECTTYPES

Results:

  
    value
    
      Error description
    
  



===================================================================================================================
GETLISTS
===================================================================================================================
This call returns a list of list items.  (pull down options)

There are no values to pass

Example:
  http://serverurl/api.php?apipassword=1234567890&module=API&action=GETLISTS

Results:

  
    
       value
    
    
      Error description
    
  

© 2009 Cowtacular LLC