Introduction
What can this API do for you?
SarvCRM API is designed as a REST/SOAP API for multiple clients: web (the web app, used on computers), iOS, and Android. A client is a program that will consume our API, that will use its endpoints and returned data.
You can do pretty much anything our web client can.
This will be most useful to:
Integrate SarvCRM capabilities into your own website, mobile application, portal and etc. with your own layout and your own way of managing rights
How do I access the SarvCRM API?
The REST service in SarvCRM can be found by navigating to:
http://app.sarvcrm.com/API.php
Versioning
Languages
SarvCRM differentiates languages with unique language keys.
The following table displays the list of current languages and their corresponding keys:
Language | Language key |
---|---|
Persian (فارسی) | fa_IR |
English (US) | en_US |
Module List
Below you will find a list of all the modules that the SarvCRM provides.
Module Key | Persian Label | English Label |
---|---|---|
Accounts | حساب ها | Accounts |
AOS_Contracts | قراردادهای فروش | Sales Contract |
AOS_Invoices | فاکتورها | Invoices |
AOS_PDF_Templates | قالب های PDF | PDF Templates |
AOS_Product_Categories | دسته های محصول | Product Categories |
AOS_Products | محصولات | Products |
AOS_Quotes | پیش فاکتورها | Quotes |
Appointments | بازدیدها | Appointments |
Approval | تاییدیه | Approval |
asol_Project | پروژه | Project |
Branches | شعب | Branches |
Bugs | پیگیری ایرادهای محصول | Bug Tracker |
Calls | تماس ها | Calls |
Cases | سرویس ها | Cases |
Communications | ارتباطات | Communications |
Communications_Target | هدف ارتباطات | Communications Target |
Communications_Template | قالب ارتباطات | Communications Template |
Campaigns | کمپین ها | Campaigns |
Contacts | افراد | Contacts |
Deposits | ودیعه | Deposits |
Documents | اسناد | Documents |
Emails | ایمیل ها | Emails |
Knowledge_Base | پایگاه دانش | Knowledge Base |
Knowledge_Base_Categories | دسته پایگاه دانش | Knowledge Base Categories |
Leads | سرنخ | Leads |
Meetings | جلسات | Meetings |
Notes | یادداشت ها | Notes |
OBJ_Conditions | شرایط شاخص | Conditions |
OBJ_Indicators | شاخص | Indicators |
OBJ_Objectives | اهداف | Objectives |
Opportunities | فرصت ها | Opportunities |
Payments | پرداخت ها | Payments |
Purchase_Order | سفارش خرید | Purchase Order |
sc_competitor | رقبا | Competitor |
sc_Contract | قراردادهای پشتیبانی | Support Contracts |
sc_contract_management | خدمات | Services |
Service_Centers | مراکز سرویس | Service Centers |
Tasks | وظایف | Tasks |
Timesheet | تایم شیت | Timesheet |
Vendors | تامین کنندگان | Vendors |
Data Types
Input / Output Data Types
The default input / output datatype for REST is JSON.
Date Handling
Date and date time inputs should be formatted following the ISO 8601 format.
There are generally 3 types of date or time output formats :
Type | Format |
---|---|
Date | "2018-04-22" |
Datetime | "2018-04-22T14:40:00+03:30" |
Time | "14:40:00" |
Request
The default input / output datatype for REST is JSON.
We accept these values of Content-Type header when using POST methods:
- application/json
- multipart/form-data
- application/x-www-form-urlencoded
HTTP Methods
verb | Description |
---|---|
GET | Obtain information. Query path parameters are allowed. |
POST | Add new information. Body is allowed. |
PUT | Edit an existing information. Body is allowed. |
DELETE | Delete a record. Query path parameters are allowed. |
Response
API response is JSON formatted and it has Content-Type: application/json header.
Response Status
Code | name | Meaning |
---|---|---|
200 | OK | The request execution has been succeeded. |
400 | Request Error | The request execution has been encountered an error. The appropriate error code will be returned in response message. See the error types |
401 | Unauthorized | The request requires user authentication. See the error types |
403 | Forbidden | The server understood the request, but is refusing to fulfill it. See the error types |
404 | Not Found | The server has not found anything matching the Request-URI. See the error types |
500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Errors
{
"status": 401,
"message": "Login attempt failed please check the username and password",
"data": []
}
The SarvCRM API uses the following error codes:
HTTP Status Code | Code | name | Meaning |
---|---|---|---|
401 | 10 | Invalid login | Login attempt failed please check the username and password. |
401 | 11 | Invalid Session ID | The session ID is invalid. |
401 | 12 | User Not Configured | Please log into your instance of SarvCRM to configure your user. |
400 | 12 | Invalid Portal Client | Portal Client does not have authorized access. |
400 | 14 | Required Fields | Please fill out the required fields and try again. |
400 | 15 | Type Mismatch | Type mismatch Error. |
400 | 16 | File is Too Large | Uploaded file is too large and exceeded the file size limit. |
404 | 20 | Module Does Not Exist | This module is not available on this server. |
404 | 21 | File Does Not Exist | The desired file does not exist on the server. |
400 | 22 | Deleted Record | Access to this object is denied since it has been deleted or does not exist. |
400 | 30 | Module Not Supported | This module does not support this feature. |
400 | 31 | Relationship Not Supported | This module does not support this relationship. |
403 | 40 | Access Denied | You do not have access. |
400 | 50 | Duplicate Records | Duplicate records have been found. Please be more specific. |
404 | 51 | No Records | No records were found. |
401 | 60 | Sessions Exceeded | Number of sessions exceeded. |
401 | 70 | Admin credentials are required | The logged-in user is not an administrator. |
400 | 90 | Resource Management Error | The resource query limit specified in config.php has been exceeded during execution of the SOAP method. |
400 | 1000 | Invalid call for this module | This is an invalid call for this module. Please look at WSDL file for details. |
400 | 1001 | Invalid data sent | The data sent for this function is invalid. Please look at WSDL file for details. |
400 | 1005 | Invalid set_campaign_merge data | set_campaign_merge: Merge action status will not be updated, because, campaign_id is null or no targets were selected. |
401 | 1008 | Password Expired | Your password has expired. Please provide a new password. |
401 | 1009 | lockout reached | You have been locked out of the SarvCRM application and cannot log in using existing password. Please contact your Administrator. |
Authentication
Login POST
{ "utype": "[UTYPE]" "user_name": "[USERNAME]", "password": "[MD5_PASSWORD]", "login_type": "portal", "language": "en_US", }
{ "status": 200, "message": "", "data": { "token": "[TOKEN_STRING]" } }
$url = "https://app.sarvcrm.com/API.php?method=Login"; $data = [ "utype" => $utype, "user_name" => $username, "password" => md5($password), "login_type" => "portal", "language" => "en_US", ]; $result = CurlCall("POST", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const data = { utype: utype, username: username, password: md5(password), login_type: "portal" language: "en_US" }; const response = await axios.post( "https://app.sarvcrm.com/API.php?method=Login", data ).then(response => { console.log(response.data); });
Logs a user into the SarvCRM application and get session id
Header parameters
---
Get parameters
-
method: LoginRequired
An API endpoint.
Post Parameters
-
utype: StringRequired
The account name
-
username: StringRequired
The correct username that created in your CRM.
-
password: StringRequired
Password needs to be in the right encoding for the type of authentication the user is setup for. For Base SarvCRM validation, password is the MD5 sum of the plain text password
-
login_type: StringOptional
For portal users, this parameter is required and should be set "portal".
-
language: StringOptional
The default langugage for the SarvCRM is "fa_IR" but you can change it. see the Languages section
Returns [data]
-
token: String
An API token or access token is a bunch of unique code bundled with every API and features user-specific information.
CRUD Methods
Create POST
{ "first_name": "Joel", "last_name": "Miller", "type": "Individual", "lead_source": "Conference", "status": "New", "numbers": [{ "type": "Mobile", "number": "09121111234", "phoneCode": "+98", "phoneFlag": "IR", "primary": 1, "sms": 1, "fax": 0 }, "02122225678", "09123456789" ] }
{ "status": 201, "message": [ "The record has been created." ], "data": { "id": "5316cfc7-55e7-73ba-8e02-64c0b2a26b3b" } }
$url = "https://app.sarvcrm.com/API.php?method=Save&module=Leads"; $data = [ "first_name" => $firstname, "last_name" => $lastname, "type" => "Individual", "lead_source" => "Conference", "status" => "New", "numbers" => [ [ "type" => "Mobile", "number" => "09121111234", "phoneCode" => "+98", "phoneFlag" => "IR", "primary" => 1, "sms" => 1, "fax" => 0, ], "02122225678", "09123456789", ], ]; $result = CurlCall("POST", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const data = { first_name: firstname last_name: lastname type: "Individual" lead_source: "Conference" status: "New" numbers: [ { type: "Mobile", number: "09121111234", phoneCode: "+98", phoneFlag: "IR", primary: 1, sms: 1, fax: 0, }, "02122225678", "09121111234", ] }; const response = await axios.post( "https://app.sarvcrm.com/API.php?method=Save&module=Leads", data ).then(response => { console.log(response.data); });
Create a single Record in specific module.
Header parameters
-
Authorization: Bearer [TOKEN]Required
The token generated by the server in response to a login request.
Get parameters
-
method: SaveRequired
An API endpoint.
-
module: [MODULE_NAME]Required
The name of specific module that you can get it from "Get module lists" API method.
Post Parameters
-
Fields list: Array
The keys of the array are the Record attributes, the values of the array are the values the attributes should have.
Returns [data]
-
id: Array
The ID of the created record.
Read (List) GETPOST
# You can provide JSON data in the body of the POST requests. { "query": "", "order_by": "accounts.date_entered", "selected_fields": [ "id", "name" ], "limit": 25, "offset": 0, }
{ "status": 200, "message": "", "data": [ { "id": "5316cfc7-55e7-73ba-8e02-64c0b2a26b3b" "name": "Ellie Williams" }, { "id": "393fe40f-38c6-e5e7-08ad-5fad612ae79e" "name": "Joel Miller" } ] }
# A sample for the HTTP POST request. $url = "https://app.sarvcrm.com/API.php?method=Retrieve&module=Accounts"; $data = [ "query" => "", "order_by" => "accounts.date_entered", "selected_fields" => ["id", "name"], "limit" => 25, "offset" => 0 ]; $result = CurlCall("POST", $url, $data); error_log(print_r($result, 1));
# A sample for the HTTP GET request. $url = "https://app.sarvcrm.com/API.php?method=Retrieve&module=Accounts"; $result = CurlCall("GET", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const data = { query: "", order_by: "accounts.date_entered", selected_fields: ["id", "name"], limit: 25, offset: 0 }; const response = await axios.post( "https://app.sarvcrm.com/API.php?method=Retrieve&module=Accounts", data ).then(response => { console.log(response.data); });
# A sample for the HTTP GET request. const axios = require("axios"); const response = await axios.get( "https://app.sarvcrm.com/API.php?method=Retrieve&module=Accounts" ).then(response => { console.log(response.data); });
Retrieve a list of records. This is the primary method for getting list of records from SarvCRM using the REST API.
Header parameters
-
Authorization: Bearer [TOKEN]Required
The token generated by the server in response to a login request.
Get parameters
-
method: RetrieveRequired
An API endpoint.
-
module: [MODULE_NAME]Required
The name of specific module that you can get it from "Get module lists" API method.
Post Parameters
-
query: StringOptional
SQL where clause without the word 'where'
-
order_by: StringOptional
SQL order by clause without the phrase 'order by'
-
select_fields: ArrayOptional
A list of the fields to be included in the results. This optional parameter allows for only needed fields to be retrieved.
-
limit: integerOptional
The maximum number of records to return. The default is the SarvCRM configuration value for 'list_max_entries_per_page'
-
offset: integerOptional
The record offset to start from.
Returns [data]
-
Field list | Array
A list of the resources. The keys of the array are the Record attributes, the values of the array are the values the attributes should have.
Read (Record) GET
# There isn't body for the GET requests.
{ "status": 200, "message": "", "data": [ { "id": "5316cfc7-55e7-73ba-8e02-64c0b2a26b3b" "name": "Ellie Williams" "type": "Individual" } ] }
$url = "https://app.sarvcrm.com/API.php?method=Retrieve&module=Accounts&id=[ID]"; $result = CurlCall("GET", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const response = await axios.get( "https://app.sarvcrm.com/API.php?method=Retrieve&module=Accounts&id=[ID]" ).then(response => { console.log(response.data); });
Retrieve a specific record. This is the primary method for getting a record from SarvCRM using the REST API.
Header parameters
-
Authorization: Bearer [TOKEN]Required
The token generated by the server in response to a login request.
Get parameters
-
method: RetrieveRequired
An API endpoint.
-
module: [MODULE_NAME]Required
The name of specific module that you can get it from "Get module lists" API method.
-
id: [RECORD_ID]Required
The record's ID value.
Post Parameters
---
Returns [data]
-
Field list | Array
An array of the resource. The keys of the array are the Record attributes, the values of the array are the values the attributes should have.
Update PUT
{ "first_name": "Joel", "last_name": "Miller", "type": "Individual", "lead_source": "Conference", "status": "New", "numbers": [{ "type": "Mobile", "number": "09121111234", "phoneCode": "+98", "phoneFlag": "IR", "primary": 1, "sms": 1, "fax": 0 }, "02122225678", "09123456789" ] }
{ "status": 200, "message": [ "The record has been updated." ], "data": { "id": "5316cfc7-55e7-73ba-8e02-64c0b2a26b3b" } }
$url = "https://app.sarvcrm.com/API.php?method=Save&module=Leads&id=[ID]"; $data = [ "first_name" => $firstname, "last_name" => $lastname, "type" => "Individual", "lead_source" => "Conference", "status" => "New", "numbers" => [ [ "type" => "Mobile", "number" => "09121111234", "phoneCode" => "+98", "phoneFlag" => "IR", "primary" => 1, "sms" => 1, "fax" => 0, ], "02122225678", "09123456789", ], ]; $result = CurlCall("PUT", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const data = { first_name: firstname last_name: lastname type: "Individual" lead_source: "Conference" status: "New" numbers: [ { type: "Mobile", number: "09121111234", phoneCode: "+98", phoneFlag: "IR", primary: 1, sms: 1, fax: 0, }, "02122225678", "09121111234", ] }; const response = await axios.put( "https://app.sarvcrm.com/API.php?method=Save&module=Leads&id=[ID]", data ).then(response => { console.log(response.data); });
Update an existing resource. if the resource does not exist, then API not create a new resource.
Header parameters
-
Authorization: Bearer [TOKEN]Required
The token generated by the server in response to a login request.
Get parameters
-
method: SaveRequired
An API endpoint.
-
module: [MODULE_NAME]Required
The name of specific module that you can get it from "Get module lists" API method.
-
id: [RECORD_ID]Required
The record's ID value.
Post Parameters
-
Fields list: Array
The keys of the array are the Record attributes, the values of the array are the values the attributes should have.
Returns [data]
-
id: Array
The ID of the created record.
Delete DELETE
# There isn't body for the DELETE requests.
{ "status": 200, "message": "The record has been deleted.", "data": [] }
$url = "https://app.sarvcrm.com/API.php?method=Save&module=[MODULE]&id=[ID]"; $result = CurlCall("DELETE", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const response = await axios.delete( "https://app.sarvcrm.com/API.php?method=Save&module=[MODULE]&id=[ID]" ).then(response => { console.log(response.data); });
As the name applies, DELETE method delete the resources. If you DELETE a resource, it’s removed from the collection of resources.
Header parameters
-
Authorization: Bearer [TOKEN]Required
The token generated by the server in response to a login request.
Get parameters
-
method: SaveRequired
An API endpoint.
-
module: [MODULE_NAME]Required
The name of specific module that you can get it from "Get module lists" API method.
-
id: [RECORD_ID]Required
The record's ID value.
Post Parameters
---
Returns [data]
---
Custom Methods
Get Module Fields GET
# There isn't body for the GET requests.
{ "status": 200, "message": "", "data": { "id": { "name": "id" "type": "varchar" "required": 0 "label": "شناسه" "options": [] }, "date_entered": { "name": "date_entered" "type": "datetime" "required": 0 "label": "تاریخ ایجاد" "options": [] }, "status": { "name": "status" "type": "enum" "required": 1 "label": "وضعیت" "options": [ "New": "جدید" "Converted": "تبدیل شده" "Expired": "منقضی شده" ] }, } }
$url = "https://app.sarvcrm.com/API.php?method=GetModuleFields&module=Accounts"; $result = CurlCall("GET", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const response = await axios.get( "https://app.sarvcrm.com/API.php?method=GetModuleFields&module=Accounts" ).then(response => { console.log(response.data); });
An endpoint for getting list of the module fields and their attributes.
Header parameters
-
Authorization: Bearer [TOKEN]Required
The token generated by the server in response to a login request.
Get parameters
-
method: GetModuleFieldsRequired
An API endpoint.
-
module: [MODULE_NAME]Required
The name of specific module that you can get it from "Get module lists" API method.
Post Parameters
---
Returns [data]
-
Field list | Array
An array of the module fields with their information.
Get Relationships GETPOST
# You can provide JSON data in the body of the POST requests. { "query": "", "order_by": "accounts.date_entered", "selected_fields": [ "id", "name" ], "limit": 25, "offset": 0, }
{ "status": 200, "message": "", "data": [ { "id": "5316cfc7-55e7-73ba-8e02-64c0b2a26b3b" "name": "Ellie Williams" }, { "id": "393fe40f-38c6-e5e7-08ad-5fad612ae79e" "name": "Joel Miller" } ] }
# A sample for the HTTP POST request. $url = "https://app.sarvcrm.com/API.php?method=Retrieve&module=Accounts"; $data = [ "query" => "", "order_by" => "opportunities.date_entered", "selected_fields" => ["id", "name"], "limit" => 25, "offset" => 0 ]; $result = CurlCall("POST", $url, $data); error_log(print_r($result, 1));
# A sample for the HTTP GET request. $url = "https://app.sarvcrm.com/API.php?method=GetRelationship&module=Accounts&id=[ID]&related_field=[FIELD_NAME]"; $result = CurlCall("GET", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const data = { query: "", order_by: "opportunities.date_entered", selected_fields: ["id", "name"], limit: 25, offset: 0 }; const response = await axios.post( "https://app.sarvcrm.com/API.php?method=Retrieve&module=Accounts", data ).then(response => { console.log(response.data); });
# A sample for the HTTP GET request. const axios = require("axios"); const response = await axios.get( "https://app.sarvcrm.com/API.php?method=GetRelationship&module=Accounts&id=[ID]&related_field=[FIELD_NAME]" ).then(response => { console.log(response.data); });
Getting all the relationships of specific resource
Header parameters
-
Authorization: Bearer [TOKEN]Required
The token generated by the server in response to a login request.
Get parameters
-
method: GetRelationshipRequired
An API endpoint.
-
module: [MODULE_NAME]Required
The name of specific module that you can get it from "Get module lists" API method.
-
id: [RECORD_ID]Required
The record's ID value.
-
related_field: [RELATED_FIELD]Required
The field name of the relationship.
Post Parameters
-
query: StringOptional
SQL where clause without the word 'where'
-
order_by: StringOptional
SQL order by clause without the phrase 'order by'
-
select_fields: ArrayOptional
A list of the fields to be included in the results. This optional parameter allows for only needed fields to be retrieved.
-
limit: integerOptional
The maximum number of records to return. The default is the SarvCRM configuration value for 'list_max_entries_per_page'
-
offset: integerOptional
The record offset to start from.
Returns [data]
-
Field list | Array
A list of the resources. The keys of the array are the Record attributes, the values of the array are the values the attributes should have.
Search By NumberGET
# There isn't body for the GET requests.
{ "status": 200, "message": "", "data": [ { "module": "Accounts" "id": "5316cfc7-55e7-73ba-8e02-64c0b2a26b3b" "name": "Ellie Williams" } ] }
$url = "https://app.sarvcrm.com/API.php?method=SearchByNumber&number=[NUMBER]&module=Accounts"; $result = CurlCall("GET", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const response = await axios.get( "https://app.sarvcrm.com/API.php?method=SearchByNumber&number=[NUMBER]&module=Accounts" ).then(response => { console.log(response.data); });
Find someone name with a specific phone number.
Header parameters
-
Authorization: Bearer [TOKEN]Required
The token generated by the server in response to a login request.
Get parameters
-
method: SearchByNumberRequired
An API endpoint.
-
number: [NUMBER]Required
The record's ID value.
-
module: [MODULE_NAME]Optional
The name of specific module that you can get it from "Get module lists" API method.
Post Parameters
---
Returns [data]
-
Field list | Array
A list of the resources. The keys of the array are the Record attributes, the values of the array are the values the attributes should have.
Save Relationships POST
# You can provide JSON data in the body of the POST requests. { "field_name": "products", "related_records": [ { "393fe40f-38c6-e5e7-08ad-5fad612ae79e" }, { "id": "8f4d8930-e8a9-698c-5414-6447c03045bc" "qty": 180 "unit_id": Branch "id_AS": 4 } ] }
{ "status": 200, "message": "Created Successfully" }
# A sample for the HTTP POST request. $url = "https://app.sarvcrm.com/API.php?method=SaveRelationships&module=Product_Bundle&id=[ID]"; $data = [ "field_name" => "products", "related_records" => [ "393fe40f-38c6-e5e7-08ad-5fad612ae79e", [ "id": "8f4d8930-e8a9-698c-5414-6447c03045bc", "qty": 180, "unit_id"; 'Branch" ], ] ]; $result = CurlCall("POST", $url, $data); error_log(print_r($result, 1));
const axios = require("axios"); const data = { field_name: "products", related_records: [ "393fe40f-38c6-e5e7-08ad-5fad612ae79e", [ "id": "8f4d8930-e8a9-698c-5414-6447c03045bc", "qty": 180, "unit_id": 'Branch" ], ] }; const response = await axios.post( "https://app.sarvcrm.com/API.php?method=SaveRelationships&module=Product_Bundle&id=[ID]", data ).then(response => { console.log(response.data); });
Save many to many relationships
Header parameters
-
Authorization: Bearer [TOKEN]Required
The token generated by the server in response to a login request.
Get parameters
-
method: SaveRelationshipsRequired
An API endpoint.
-
module: [MODULE_NAME]Required
The name of specific module that you can get it from "Get module lists" API method.
-
id: [RECORD_ID]Required
The record's ID value.
Post Parameters
-
field_name: StringRequired
The name of relation field. you can get the name by "Get Module Fields" method.
-
related_records: ArrayRequired
An array of related_module data that includes ID and additional fields.
Returns [data]
---
Postman Collection
Here you can download a Postman collection file which includes a few examples:
- Login
- Create a Lead [With numbers]
- Create a Quote [With line items]
- Retrieve a List of Accounts
- Retrieve an Account
- Update a Lead
- Delete a Lead
- Get Module Fields
- Get Relationships
- Save Relationships
- Get Survey Questions
- Get Resource Attachment
- Leave a Comment