Simply Webservices / API documentation

Posted on by Kim Hvidkjaer

This documentation describes the REST based application programming interface(the API) published by Simply. It is meant as a reference document for consumers of the API’s.
We recommend that you go through the tutorial before you attempt reading this documentation.

All structural data including response from the api is represented as JSON strings.

Each entity has a specially formated id that can be used to look up an entity’s type and the record. Create is the one case that does not require an id.

URL Format

http://Simply_url/webservice.php?operation= [operation type]&sessionName=[session Name]&[operation specific parameters]

Operation

Currently the following operations are supported:

  • getchallenge
  • login
  • create
  • retrieve
  • update
  • delete
  • sync
  • query
  • listtypes
  • describe
  • logout
  • extendsession

sessionName

The key that is used to uniquely identify the current session. This should be sent to the server as part of each request.

Security

The web services api supports the security model followed in the Simply web user interface.

The login process uses a two step challenge/response scheme.

Data Types used by the api

The Response Format

All responses will have the following format.If the request is processed successfully, hen the format is 

Response { 
 success:Boolean=true 
 result:Object //The Result object 
}

If there is a failure while processing the request, 

Response { 
 success:Boolean=false 
 error:ErrorObject 
} 

ErrorObject { 
 errorCode:String //String representation of the error type 
 errorMessage:String //Error message from the api. 
}

errorCode is a string representation of the error type.

SimplyObject

A Map representing the contents of a crmentity based object. All reference fields are represented using Id type. A key called id of type Id represents the object’s unique id. This field is present for any object fetched from the database.

Id Format

objectTypeId 'x' objectId 

objectTypeId - Id of the object type. This is generated uniquely for each entity supported by Web service API and returned in the result of describe operation as idPrefix. 

objectId - id of object in database. This is a globally unique id for objects of the given entity.

Map

An associative array of key value pairs. Usually used in create operation.

TimeStamp

A long representation of the number of seconds since unix epoch.

GetChallengeResult

An object representing the response of a getchallenge operation, 

GetChallengeResult { 
 token:String //Challenge token from the server. 
 serverTime:TimeStamp //The current server time. 
 expireTime:TimeStamp //The time when the token expires. 
}

LoginResult

An object representing the response of a login operation, 

LoginResult { 
 sessionId:String //Unique Identifier for the session 
 userId:String //The Simply id for the logged in user 
 version:String //The version of the webservices api 
 SimplyVersion:String //The version of the Simply crm. 
}

SyncResult

An object representing the response of a sync operation, 

SyncResult { 
 updated:[Object] //List of Objects created or modified. 
 deleted:[Id] //List of *Id* of objects deleted. 
 lastModifiedTime:Timstamp //time of the latest change. which can used in the next call to the Sync api to get all the latest changes that the client hasn't obtained. 
}

Operations

Get Challenge

Get a challenge token from the server.

getchallenge(username:String):GetChallengeResult

Request Type: GET
username: A Simply username.
response: A GetChallengeResult object containing the server’s challenge token.

This must be a GET request.

url format 

http://Simply_url/webservice.php?operation=getchallenge&username= [username]

Login

Login to the server using the challenge token obtained in get challenge operation.

login(username:String, accessKey:String):LoginResult

Request Type:POST

username: A Simply username.accessKey: An md5 of the concatenation of the challenge token and the user’s webservice access key.

response: A LoginResult object containing the session id, the api version id and the user id.

This must be a POST request.

url format 

http://Simply_url/webservice.php?operation=login&username= [username]&accessKey=[md5(challenge_token + accessKey)]

Note: In accessKey ‘K’ is uppercase.

Create

Create a new entry on the server.

create(element:Map, elementType:String): SimplyObject

Request Type: POST

element: Fields of the object to populate. Values for mandatory fields must be provided.elementType: The class name of the object.

This Must be a POST request.

url format 

http://Simply_url/webservice.php?operation=create&sessionName= [session id]&element=[object]&elementType=[object type]

response: A SimplyObject instance representing the new object.

Retrieve

Retrieve an existing entry from the server.

retrieve(id: Id): SimplyObject

Request Type: GET

id: The Id of the object.

response: A SimplyObject instance representing the retrieved object.

This Must be a GET request.url format 

http://Simply_url/webservice.php?operation=retrieve&session_name= [session id]&id=[object id]

Update

Update an existing entry on the Simply crm object.

update(object: SimplyObject): SimplyObject

Request Type: POST

object: The SimplyObject to update.

response:A SimplyObject representing the object after the update.

This Must be a POST request.url format 

http://Simply_url/webservice.php?operation=update&sessionName= [session id]&element=[object]

Delete

Delete an entry from the server.

delete(id:Id):Nothing

Request Type: POST

id: The Id of the object to be deleted.response: A map with one key status with value ‘successfull’

This Must be a POST request.url format 

http://Simply_url/webservice.php?operation=delete&sessionName= [session id]&id=[object id]

Query

The query operation provides a way to query Simply for data.

query(queryString : String): [SimplyObject]

Request Type: GET

queryString:The query to process.

response: A list of Map containing the fields selected.

Queries are currently limited to a single object. Joins are not supported. Query always limits its output to 100 records, Client application can use limit operator to get different records.The query format 

select * | <column_list> | <count(*)> 

from <object> [where <conditionals>] 

[order by <column_list>] [limit [<m>, ]<n>]; 

The column list in the order by clause can have at most two column names.
  • column_list: comma separated list of field names.
  • object: type name of the object.
  • conditionals: condition operations or in clauses or like clauses separated by ‘and’ or ‘or’ operators these are processed from left to right. The are no grouping that is bracket operators.
  • conditional operators: <, >, <=, >=, =, !=.
  • in clauses: in ().
  • like clauses: like ‘sqlregex’.
  • value list: a comma separated list of values.
  • m, n: integer values to specify the offset and limit respectively.

This Must be a GET request.

Query operation is currently supported for Entity module only.url format 

http://Simply_url/webservice.php?operation=query&sessionName= [session id]&query=[query string]

Sync

Sync will return a SyncResult object containing details of changes after modifiedTime.

sync(modifiedTime: Timestamp, elementType: String):SyncResult

Request Type: GET

modifiedTime: The time of the last synced modification.elementType: This is an optional parameter, if specified the changes for that module after the given time otherwise changes to all user accessible module are returned.

Returns a SyncResult object representing the sync data.

This Must be a GET request.url format 

http://Simply_url/webservice.php?operation=sync&sessionName= [session id]&modifiedTime=[timestamp]&elementType=[elementType]

Logout

Logout from the webservices session, this leaves the webservice session invalid for further use.

logout(): Map

Request Type: GET

Returns a map containing the key ‘message’ with the value ‘successfull’.

This Must be a GET request.url format 

http://Simply_url/webservice.php?operation=logout&sessionName= [session id]

List Types

List the names of all the Simply objects available through the api.

listtypes(): Map

Request Type: GET

Returns a map containing the key ‘types’ with the value being a list of names of Simply objects.

This Must be a GET request.url format 

http://Simply_url/webservice.php?operation=listtypes&sessionName= [session id]

Describe

Get the type information about a given Simply object.

describe(elementType: String): DescribeResult

Request Type: GET

elementType: The type name of the Simply object to describe.

Returns a DescribeResult instance.

This Must be a GET request.url format 

http://Simply_url/webservice.php?operation=describeobject&sessionName= [session id]&elementType=[elementType]

Extend Session

Extends current Simply web-session to webservices and returns a webservices session id.

extendsession(username:String):LoginResult

Request Type: POST

username: A Simply username.

This Must be a POST request.url format 

http://Simply_url/webservice.php?operation=extendsession 

CRM Entities

List of CRM Entities exposed by the API.

Name                               Description <hr>

Calendar                           The Calendar module is used to Manage To dos ,Events and Meetings.

Leads                               The Leads module is used to track Sales leads.

Accounts                          The Accounts module is used to Manage individual or organizations involved in your business.

Contacts                           The Contacts module is used to Manage individuals, who may be associated with an Account.

Potentials                         The Potential module is used to Manage Sales Opportunity.

Products                           The Products module is used to Manage the product that your organization sales.

Documents                       The Documents module is used to Manage the uploaded Documents and Notes.

Emails                             The Emails module is a email client used to manage your emails.

HelpDesk                         The HelpDesk module is used to track customer issues such as feedback, problems etc.

Faq                                 The FAQ module is used to manage the frequently asked question by your customer.

Vendors                           The Vendors Module is used for managing Manufacturers.

PriceBooks                      The PriceBook Module is used for managing pricing of products.

Quotes                            The Quotes Module is used for managing the Quotes for products.

PurchaseOrder                 The PurchaseOrder module is used for managing the PurchaseOrders.

SalesOrder                      The SalesOrder module is used for managing the SalesOrders.

Invoice                            The Invoice module is used for creating invoice reports.

Campaigns                      The Campaigns module is used for managing Marketing Campaigns.

Events                            The Events module is used for Managing Activities such as Calls and Meetings.

Users                             The Users module is used for managing the CRM users.

Groups                           Users groups on the Simply CRM.

Currency                        Currency module let’s the administrator to define different currencies and set the expected conversion rate with respect to the base currency.                          These currencies can be used in Inventory modules to support multi-currency.

DocumentFolders            The DocumentFolders module is used to Groups Documents.

Field Types

picklist

A field that can a hold one of a list of values, the map will contain two elements,

picklistValues which is a list of possible values, and defaultValue which is the default value for the picklist.

Name                    Description

picklistValues        Which is a list of possible values.

defaultValue           specifies which value should be used as the default value for the picklist.

name                     Name of the field type.

reference

A field that shows a relation to another object, the field type map will contain another element called refersTo which is an array containing the name of modules of which the field can point to.

Name                    Description

refersTo                 Which is an array containing the name of modules to which the field can point to.

name                     Name of the field type.

datetime

A string representing the date and time, the format is base on the user’s settings date format.

date

A string representing a date, the field type map will contain another element called format which is the format in which the value of this field is expected, its based on the user’s settings date format.

Name                     Description

format                    The format in which the value of this field is expected.

name                     Name of the field type.

text

A multiline text field.

time

A string of the format hh:mm, format is based on the user’s settings time format.

string

A one line text field.

boolean

A boolean field, can have the values true or false.

integer

A non decimal number field.

owner

A field for defining the owner of the field. which could be a group or individual user.

autogenerated

These are fields for which the values are generated automatically by Simply, this is usually an object’s id field.

email

A field for storing email ids.

phone

A field for storing phone numbers.

url

A field for storing urls.

double

A field for for floating point numbers.

file

A field for Adding file to Simply.

Name                           Description

maxUploadFileSize       Max allowed size of a file getting uploaded.

name                           Name of the field type.

password                    

A field for storing passwords.

decimal                      

A field for for floating point numbers.

skype                      

A field for storing skype ids or phone numbers.

multipicklist

A picklist field where multiple values can be selected.

Known Issues

  • Sync does not work on the users module And non Entity modules like Currency,Groups etc.
  • Query does not work on non Entity modules like Currency,Groups etc..