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.
Important: It is required to enter the IP in the Whitelist IP field under My Preferences on the user’s profile in Simply CRM that is being used to access the API.
Get Challenge
Used to get a challenge token from the server.
Request
Type: GET
username: A Simply username
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.
| Name | Description |
| 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 individuals or organizations involved with your business. |
| Contacts | The Contacts module is used to manage individuals that may be associated with an account. |
| Potentials | The Potentials module is used to manage sales opportunities. |
| Products | The Products module is used to manage the products that your organization sells. |
| 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 posed by your customers. |
| Vendors | The Vendors module is used to manage manufacturers and producers. |
| PriceBooks | The PriceBook Module is used to manage the pricing of products. |
| Quotes | The Quotes module is used to manage product quotes. |
| PurchaseOrder | The PurchaseOrder module is used to manage and process the purchase orders. |
| SalesOrder | The SalesOrder module is used to manage and process sale orders. |
| Invoice | The Invoice module is used to create invoice reports. |
| Campaigns | The Campaigns module is used to manage marketing campaigns. |
| Events | The Events module is used to manage activities such as calls and meetings. |
| Users | The Users module is used to manage the CRM users. |
| Groups | User groups in Simply CRM. |
| Currency | Currency 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. |
| DocumentFolders | The 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.
| Name | Description |
| picklistValues | Represents the list of possible values. |
| defaultValue | Specifies which value should be used as the default value for the picklist. |
| name | The 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.
| Name | Description |
| refersTo | An array containing the modules to which the field can point. |
| name | The 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.
| Name | Description |
| format | The expected format of the field value. |
| name | The 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.
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.
| Name | Description |
| maxUploadFileSize | The maximum allowed size allowed for uploading files. |
| name | The 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.
