This document is intended to provide a language-neutral guide of using the SugarCRM Rest API v4_1 by displaying the HTTP POSTs used to send and request data. I believe that these POSTs are the best way to understand how these API calls work, since some information is carried in the POST and some as JSON-encoded arrays.
Please also note that SugarCRM offers a newer version of it's REST API, dubbed v10, which is notably more RESTful. It is a complete redesign and it is not compatable with the methods described in this guide.
SugarCRM Systems' REST APIs are accessed at /service/v4_1/rest.php. So, if your system is at http://localhost/sugarcrm, then the full path to your API Endpoint would be http://localhost/sugarcrm/service/v4_1/rest.php.
This document will demonstrate the full POST data that a system must send to SugarCRM. The POST will be fully URL-encoded parameters, including the rest_data param which is also JSON-encoded. The document will show the POST string in its entirety, then show the URL-decoded and JSON-decoded rest_data array. It will also show a sample of response data.
This document is written in Markdown.
- rest_data params must be ordered specicifcally according to the documentation, i.e. session, then module name, then more values (if required). This is important in languages where the JSON-encoded process may disrupt the array's order, e.g. CFML.
Auth uses the API method 'login'. Note that the password parameter must be the md5 hash of the plaintext password.
method=login&input_type=JSON&response_type=JSON&rest_data=%7B%22user_auth%22%3A%7B%22user_name%22%3A%22mpoer%22%2C%22password%22%3A%22--md5-of-my-password--%22%7D%2C%22name_value_list%22%3A%5B%7B%22name%22%3A%22notifyonsave%22%2C%22value%22%3A%22true%22%7D%5D%7D
{
"user_auth":{
"user_name":"mpoer",
"password":"--md5-of-my-password--"
},
"name_value_list":[
{
"name":"notifyonsave",
"value":"true"
}
]
}
{"id":"nis7iusoep2ttstbb6jtpqhth3","module_name":"Users","name_value_list":{"user_id":{"name":"user_id","value":"aa5ab172-6e57-01c7-f39e-4d9e91d7aabe"},"user_name":{"name":"user_name","value":"mpoer"},"user_language":{"name":"user_language","value":"en_us"},"user_currency_id":{"name":"user_currency_id","value":"-99"},"user_currency_name":{"name":"user_currency_name","value":"US Dollar"}}}
Creating a new record uses the API method 'set_entry'
method=set_entry&input_type=JSON&response_type=JSON&rest_data=%7B%22session%22%3A%22ivdphgq30l7rq7cf5retig1v40%22%2C%22module_name%22%3A%22Accounts%22%2C%22name_value_list%22%3A%7B%22name%22%3A%22ABC%20Corp%22%2C%22description%22%3A%22Here%20is%20some%20new%20account%20information%22%7D%7D
{
"session":"ivdphgq30l7rq7cf5retig1v40",
"module_name":"Accounts",
"name_value_list":{
"name":"ABC Corp",
"description":"Here is some new account information"
}
}
{"id":"16fc613d-9911-20b1-4e87-5388c5ba6160"}
Updating a record works the same as creating a new record, using the method 'set_entry' but you will specify a record id in the rest_data. This id may be known to a user, stored in your third-party application, or retrieved by a previous service call.
method=set_entry&input_type=JSON&response_type=JSON&rest_data=%7B%22session%22%3A%22ivdphgq30l7rq7cf5retig1v40%22%2C%22module_name%22%3A%22Accounts%22%2C%22name_value_list%22%3A%7B%22id%22%3A%2216fc613d%2D9911%2D20b1%2D4e87%2D5388c5ba6160%22%2C%22name%22%3A%22ABC%20Corp%22%2C%22description%22%3A%22Here%20is%20some%20new%20account%20information%22%7D%7D
{
"session":"ivdphgq30l7rq7cf5retig1v40",
"module_name":"Accounts",
"name_value_list":{
"id":"16fc613d-9911-20b1-4e87-5388c5ba6160",
"name":"ABC Corp",
"description":"Here is some updated account information"
}
}
{"id":"16fc613d-9911-20b1-4e87-5388c5ba6160"}
Retreiving lists of records will use the method 'get_entry_list'
method=get_entry_list&input_type=JSON&response_type=JSON&rest_data=%7B%22session%22%3A%22nis7iusoep2ttstbb6jtpqhth3%22%2C%22module_name%22%3A%22Accounts%22%2C%22query%22%3Anull%2C%22order_by%22%3Anull%2C%22offset%22%3A0%2C%22select_fields%22%3A%5B%22id%22%2C%22name%22%5D%2C%22link_name_to_fields_array%22%3A%5B%5D%2C%22max_results%22%3A20%2C%22deleted%22%3Afalse%7D
{
"session":"nis7iusoep2ttstbb6jtpqhth3",
"module_name":"Accounts",
"query":null,
"order_by":null,
"offset":0,
"select_fields":[
"id",
"name"
],
"link_name_to_fields_array":[
],
"max_results":20,
"deleted":false
}
{"result_count":21,"next_offset":21,"entry_list":[{"id":"1049ced5-3602-5226-6e31-512fd522cc21","module_name":"Accounts","name_value_list":{"id":{"name":"id","value":"1049ced5-3602-5226-6e31-512fd522cc21"},"name":{"name":"name","value":"Frandev"}}}....
Retreiving lists of records will use the method 'get_entry_list'. This example will filter for Active Accounts (custom field status_c = 'Active') located in Georgia (billing_address_state = 'GA'). We'll also limit the number of results to 3.
method=get_entry_list&input_type=JSON&response_type=JSON&rest_data=%7B%22session%22%3A%222o764p0ol00eenp8vnjdrhesi1%22%2C%22module_name%22%3A%22Accounts%22%2C%22query%22%3A%22accounts_cstm.status_c+%3D+%27Active%27+and+accounts.billing_address_state+%3D+%27GA%27%22%2C%22order_by%22%3Anull%2C%22offset%22%3A0%2C%22select_fields%22%3A%5B%22id%22%2C%22name%22%5D%2C%22link_name_to_fields_array%22%3A%5B%5D%2C%22max_results%22%3A%222%22%2C%22deleted%22%3Afalse%7D
{
"session":"2o764p0ol00eenp8vnjdrhesi1",
"module_name":"Accounts",
"query":"accounts_cstm.status_c = 'Active' and accounts.billing_address_state = 'GA'",
"order_by":null,
"offset":0,
"select_fields":[
"id",
"name"
],
"link_name_to_fields_array":[
],
"max_results":"2",
"deleted":false
}
{"result_count":3,"next_offset":3,"entry_list":[{"id":"11cafc8e-9b32-5459-91cc-522f465e7708","module_name":"Accounts","name_value_list":{"id":{"name":"id","value":"11cafc8e-9b32-5459-91cc-522f465e7708"},"name":{"name":"name","value":"Account One"}}},{"id":"2115f4cd-3ecb-3eb6-a555-5286b82be466","module_name":"Accounts","name_value_list":{"id":{"name":"id","value":"2115f4cd-3ecb-3eb6-a555-5286b82be466"},"name":{"name":"name","value":"Account Two"}}},{"id":"2bdd60c5-699b-abc7-08e7-5358199fc39c","module_name":"Accounts","name_value_list":{"id":{"name":"id","value":"2bdd60c5-699b-abc7-08e7-5358199fc39c"},"name":{"name":"name","value":"Account Three"}}}],"relationship_list":[]}
Retrieve a list of records with information about related records. We will continue to use 'get_entry_list' here. This will also use the filters and limit of the previous example to limit our result set.
method=get_entry_list&input_type=JSON&response_type=JSON&rest_data=%7B%22session%22%3A%2251744be2srf9ebp7jrr71nrth5%22%2C%22module_name%22%3A%22Accounts%22%2C%22query%22%3A%22accounts_cstm.status_c+%3D+%27Active%27+and+accounts.billing_address_state+%3D+%27GA%27%22%2C%22order_by%22%3Anull%2C%22offset%22%3A0%2C%22select_fields%22%3A%5B%22id%22%2C%22name%22%5D%2C%22link_name_to_fields_array%22%3A%5B%7B%22name%22%3A%22contacts%22%2C%22value%22%3A%5B%22id%22%2C%22last_name%22%5D%7D%5D%2C%22max_results%22%3A%222%22%2C%22deleted%22%3Afalse%7D
{
"session":"51744be2srf9ebp7jrr71nrth5",
"module_name":"Accounts",
"query":"accounts_cstm.status_c = 'Active' and accounts.billing_address_state = 'GA'",
"order_by":null,
"offset":0,
"select_fields":[
"id",
"name"
],
"link_name_to_fields_array":[
{
"name":"contacts",
"value":[
"id",
"last_name"
]
}
],
"max_results":"2",
"deleted":false
}
{"result_count":3,"next_offset":3,"entry_list":[{"id":"11cafc8e-9b32-5459-91cc-522f465e7708","module_name":"Accounts","name_value_list":{"id":{"name":"id","value":"11cafc8e-9b32-5459-91cc-522f465e7708"},"name":{"name":"name","value":"Account One"}}},{"id":"2115f4cd-3ecb-3eb6-a555-5286b82be466","module_name":"Accounts","name_value_list":{"id":{"name":"id","value":"2115f4cd-3ecb-3eb6-a555-5286b82be466"},"name":{"name":"name","value":"Account Two"}}},{"id":"2bdd60c5-699b-abc7-08e7-5358199fc39c","module_name":"Accounts","name_value_list":{"id":{"name":"id","value":"2bdd60c5-699b-abc7-08e7-5358199fc39c"},"name":{"name":"name","value":"Account Three"}}}],"relationship_list":[[{"name":"contacts","records":[{"id":{"name":"id","value":"111db6f8-a14b-8a43-263d-522f46258959"},"last_name":{"name":"last_name","value":"Jones"}},{"id":{"name":"id","value":"300d3fda-ddb7-b742-62ca-522f639c0f67"},"last_name":{"name":"last_name","value":"Riedemann"}},{"id":{"name":"id","value":"843c84af-68f7-9cc0-75dc-52cea89fb9db"},"last_name":{"name":"last_name","value":"Smith"}}]}],[{"name":"contacts","records":[{"id":{"name":"id","value":"2069ccef-1c68-99a8-294e-5286b8361e07"},"last_name":{"name":"last_name","value":"Jameson"}}]}],[{"name":"contacts","records":[{"id":{"name":"id","value":"28b7c2e7-de23-457c-fb46-535819710009"},"last_name":{"name":"last_name","value":"New"}}]}]]}
Hello i'm trying to get data from accounts but its say Module Does Not Exist.