The SugarCRM SOAP interface is designed with simplicity in mind.

Step 1: Test

If you would like to make sure you can connect to the SugarCRM SOAP API’S, use this test call. This call will echo whatever you send to it.

call: test

arguments:

string:string - this is a string that you want to be echoed back to you

results:

string:string - this is the string that was sent as an argument.

Step 2: Login
First you will need to login to the SugarCRM system through the SOAP interface.

call: login

arguments:

complex-type:user_auth

string:application_name - this is a unique application name

results:

complex-type: set_entry_result
Note: In this case the id of set_entry_result is the SugarCRM SOAP API’s session_id. This will be used in all future calls. So you will want to store this in a session or application level.

New complex types introduced in this step

user_auth

is a struct containing 3 parameters

parameter 1: string:user_name - this is the SugarCRM SOAP user name

parameter 2: string:password - this is an md5 of the SugarCRM SOAP user password

parameter 3: string:version - this is the version of soap you are expecting

set_entry_result

is a struct containing 2 parameters

parameter 1: string:id -this is the id for the result

parameter 2:complex-type:error(error_value) this is the error if any

error_value

is a struct containing 3 parameters

parameter 1: string:number - this is the error number

parameter 2: string:name - this is the error name

parameter 3: string:description - this is the error description

an error number of 0 indicates no errors were encountered

Step 3: Get the current User Id

Sometimes it is useful to know the current user id. To get this information returned, call get_user_id.

call: get_user_id

arguments:

string:session - this is the session_id retrieved during login that you should have stored in either the application or the session scope

results:

strung:return - this is the user_id for the current SugarCRM SOAP user who logged in during step 1
Step 4: Get the List results for a module

This will return a list of entries (results) for a list view of a module. Full row level security restrictions apply in terms of who can access what data in the system. It should also be noted that only the fields available in the module’s list view is available through the get_entry_list call.

Call: get_entry_list

arguments:

string:session - this is the session_id

string:module_name - this is the module you wish to get results for (e.g. ‘Calls’)

string:query - this is the search query you wish to apply in retrieving the results

(e.g “(calls.name LIKE ‘doctor appointment%’ AND calls.date_start = CURDATE())” )

string:order_by - this is what you would like to order by for the results

(e.g. “calls.name”)

complex-type:select_fields - these are the fields you want returned

(it is faster if you only retrieve the fields you need)

(e.g. Name, description, date_start, time_start)

int:max_results - this is the maximum number of results you want returned if set to 0 it will return the default SugarCRM SOAP API’s amount for list-views

results:

complex-type: get_entry_list_result
New complex types introduced in this step

select_fields

is an array of strings (these are the names of fields for a given module)

get_entry_list_result

is an struct containing 5 parameters

parameter 1: int:result_count - the number of results returned

parameter 2: int:next_offset - the next offset to use in a request

parameter 3:complex-type:field_list - this is meta data of the fields returned

parameter 4:complex-type:entry_list - this is the actual result data

parameter 5:complex-type:error (error_value) any errors that occurred

field_list

is an array of complex-type:field

field

is an struct containing 5 parameters

parameter 1: string:name - the db/sugar name for a field

parameter 2: string:type - the type of field (enum, text)

parameter 3:string:label - the translated label for the field

parameter 4: int:required - 1 for required 0 for not

parameter 5:complex-type:name_value_list - these are additional options such as for enumeration it would be the list of values for the enumeration.

name_value_list

an array of complex-type:name_value

name_value

a struct containing 2 parameters this is a name value pair

parameter 1: string:name - the name of the value (a.k.a key)

parameter 2: string:value - the value for the name

entry_list

an array of complex-type:entry_value

entry_value

a struct containing 3 parameters

parameter 1: string:id - the sugar id for the entry

parameter 2: string:module_name - the module this entry is from

parameter 3: complex-type:name_value_list - the field values for this entry
Step 5: Get the full results for an entry

So we retrieved a list of results for a module but you might need more details on a single entry since get_entry_list is limited to what is available in the list view. You can get this information by retrieving a single entry using get_entry

call: get_entry

arguments:

string:session - the session_id

string:module_name - the module for the entry you want to retrieve

string:id - the id of the entry you want to retrieve

complex-type:select_fields - the fields you want to retrieve

results:

complex-type: get_entry_result

New complex types introduced in this step

get_entry_result

is a struct containing 3 parameters

parameter 1:complex-type:field_list - this is metadata of the fields returned

parameter 2:complex-type:entry_list - this is the actual result data(in this case it will be an array of size 1)

parameter 3:complex-type:error (error_value) any errors that occurred

the reason for including entry_list in the same manner as get_entry_list_result is so that the same function can create data structures for both calls
Step 6: Set the values for an entry

You may want to now modify or even create a new entry. This is where set_entry comes into place. Both modifying and creating a record are done from the same function call.

call: set_entry

arguments:

string:session - the session_id

string:module_name - the module for the entry you want to update/create

complex-type:name_value_list - the fields you want to set

results:

complex-type: get_entry_result

Pass in the primary id of a record in the name_value_list complex field if you have a field called id otherwise to update a specific record. Otherwise if this field is empty, the system will create a new entry. It’s that easy.

Step 7: Set the values for an entry

If you want to create an entry but don’t have any fields to work with and there are no results in the database, you can get a list of the available fields for a module. You use get_module_fields.

call: get_module_fields

arguments:

string:session - the session_id

string:module_name - the module that you want a list of fields for

results:

complex-type: module_fields - these are the fields to use
New complex types introduced in this step

module_fields is a struct containing 3 parameters

parameter 1:string:module_name- the module name for the fields

parameter 2:complex-type:module_fields(field_list) - these are the fields

parameter 3:complex-type:error (error_value) any errors that occurred

Step 8: Logout

You need to clean up your session after you’re done.

call: logout

arguments:

string:session - the session_id

results:

complex-type:error(error_value) - any errors (not logged in?)