Simply CRM Web Service & API Documentation

This documentation describes the REST based application programming interface (the API) published by Simply CRM. It is meant as a reference document for everyone who uses our 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 formatted 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.

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

Currently, Simply CRM supports the following operations:

  • 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 information should be sent to the server as part of each request.

Web service

The web service 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

All responses will have the format shown below. If the request is processed successfully, then the format is:

If a failure occurs while the request is being processed, you will receive the following response format:

Response {   
success:Boolean=true
result:Object //The Result object
}
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

SimplyObject is a map representing the contents of a crm entity based object. All reference fields use the ID type, which assigns a unique number to each object. This field is present for all objects fetched from the database.

ID format

objectTypeId 'x' objectId

objectTypeId - Id of the object type. This is generated uniquely for each entity supported by the 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 the create operation.

TimeStamp

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

Operations

Login

Login is a two step process : First we generate a unique token calling getChallenge. And then use that token and our unique access key to generate a session ID which acts like an authentication identifier.

Get Challenge

Used to get a challenge token from the server.

Request

Type: GET
username: A Simply username

operation: getchallenge

GET /webservice.php?operation=getchallenge&username=[username]

Response

{
        success: true,
        result: {
                token: String,
                serverTime: TIMESTAMP,
                expireTime: TIMESTAMP
        }
}
Login

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

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

Request

Type: POST

operation: login

username: A Simply username.

accessKey: An md5 of the concatenation of the challenge token and the user’s web service access key.

Response

{
        success: true,
        result: {
                sessionId: String,
                userId: String,
                version: String,
                SimplyVersion:String
        }
}

Note: In accessKey, ‘K’ is uppercase.

Create

Create a new entry on the server. An entity is a record in one of Simply’s modules. To get the list of fields for the create operation you can call Describe operation first

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

Request

Type: POST

operation: create

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 ‘successful’

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 maps containing the fields selected.

Queries are currently limited to a single object. Joins are not supported. The query always limits its output to 100 records. The client application can use limit operators to get different records.

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 the 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.

Response

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.  
} 

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 webservice session, which leaves the webservice session invalid for further use.

logout(): Map

Request Type: GET Returns a map containing the key ‘message’ with the value ‘successful’.

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 the current Simply web session to the web service and returns the webservice’s 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

What follows is the list of CRM entities exposed by the API.

NameDescription
CalendarThe Calendar module is used to manage to-dos, events and meetings.
LeadsThe Leads module is used to track sales leads.
AccountsThe Accounts module is used to manage individuals or organizations involved with your business.
ContactsThe Contacts module is used to manage individuals that may be associated with an account.
PotentialsThe Potentials module is used to manage sales opportunities.
ProductsThe Products module is used to manage the products that your organization sells.
DocumentsThe Documents module is used to manage the uploaded documents and notes.
EmailsThe Emails module is a email client used to manage your emails.
HelpDeskThe HelpDesk module is used to track customer issues such as feedback, problems, etc.
FAQThe FAQ module is used to manage the frequently asked question posed by your customers.
VendorsThe Vendors module is used to manage manufacturers and producers.
PriceBooksThe PriceBook Module is used to manage the pricing of products.
QuotesThe Quotes module is used to manage product quotes.
PurchaseOrderThe PurchaseOrder module is used to manage and process the purchase orders.
SalesOrderThe SalesOrder module is used to manage and process sale orders.
InvoiceThe Invoice module is used to create invoice reports.
CampaignsThe Campaigns module is used to manage marketing campaigns.
EventsThe Events module is used to manage activities such as calls and meetings.
UsersThe Users module is used to manage the CRM users.
GroupsUser groups in Simply CRM.
CurrencyCurrency module lets the administrator define different currencies and set the expected conversion rates with respect to the base currency. These currencies can be used in the Inventory module to support multi-currency.
DocumentFoldersThe DocumentFolders module is used to Groups Documents.

Field Types

Picklist

A field that can a hold one of a list of values, in which case the map will contain two elements: picklistValues which is a list of possible values, and defaultValue which is the default value for the picklist.

NameDescription
picklistValuesRepresents the list of possible values.
defaultValueSpecifies which value should be used as the default value for the picklist.
nameThe 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 modules to which the field can point.

NameDescription
refersToAn array containing the modules to which the field can point.
nameThe 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 specifies the expected format of the field value, based on the user’s date format settings.

NameDescription
formatThe expected format of the field value.
nameThe name of the field type.

Text

A multiline text field.

Time

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

String

A one line text field.

Boolean

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

Integer

A non-decimal number field.

Owner

A field used to define the owner of the field. This can be a group or an individual user.

Autogenerated

Fields, such as the object’s ID, whose values are generated automatically by Simply.

Email

A field used to store email IDs.

Phone

A field used to store phone numbers.

URL

A field for storing URLs.

Double

A field for for floating point numbers.

File

A field used to add files to Simply.

NameDescription
maxUploadFileSizeThe maximum allowed size allowed for uploading files.
nameThe name of the field type.

Password

A field used to store passwords.

Decimal

A field used for floating point numbers.

Skype

A field used to store 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.

Updated on 18/11/2020

Was this article helpful?

Related Articles