Endpoints

This page documents the legacy v4.1 API methods. New integrations should use the V8 API.

Error Handling

All API methods return errors using the same structure. Check for a non-zero number field to detect failures.

Name Type Desc

error

array

An array containing error details. Present on failure.

error[number]

int

The error number. 0 indicates success.

error[name]

string

A short name for the error (e.g. invalid_login).

error[description]

string

A human-readable description of the error.

Common error numbers:

Number Meaning

10

Invalid login credentials or expired session

11

Invalid session

20

No module specified

1000

Unknown error

Several methods include a favorites parameter. Favorites were a SugarCRM Professional feature and this parameter is ignored in SuiteCRM. Similarly, calculated fields in get_module_fields responses will always be empty.

Methods

login

Logs into SuiteCRM and returns a session id used for subsequent API calls.

Arguments

Name Type Desc

user_auth

array

Authentication details for the API User

user_auth[user_name]

string

The user name of the SuiteCRM user. Required.

user_auth[password]

string

The MD5 hash of the password for user_name. Required.

application_name

string

An identifier for the application accessing the API

name_value_list

name_value_list

An array of login options

name_value_list[language]

string

The language for this user

name_value_list[notifyonsave]

bool

Send email notifications when a new record is saved and assigned to a user

Response

Name Type Desc

id

string

The session id for this login. Required for all other API calls.

name_value_list

name_value_list

An array containing information about this user.

name_value_list[user_id]

string

The id of the logged in user.

name_value_list[user_name]

string

The user_name of the logged in user

name_value_list[user_language]

string

The language setting of the logged in user

name_value_list[user_currency_id]

string

The id of the currency of the logged in user. -99 is the default currency.

name_value_list[user_currency_name]

string

The name of the currency of the logged in user.

name_value_list[user_is_admin]

bool

Whether the logged in user is an admin

name_value_list[user_default_team_id]

string

The default team of the logged in user. This value comes from before the fork of SuiteCRM and isn’t used.

name_value_list[user_default_dateformat]

string

The default date format of the logged in user.

name_value_list[user_default_timeformat]

string

The default time format of the logged in user

name_value_list[user_number_seperator]

string

The number separator of the logged in user. (I.e. comma for numbers in the 1,000.00 format)

name_value_list[user_decimal_seperator]

string

The decimal separator of the logged in user. (I.e. period for numbers in the 1,000.00 format)

name_value_list[mobile_max_list_entries]

int

Max list entries for the logged in user (simply grabs the wl_list_max_entries_per_subpanel config key)

name_value_list[mobile_max_subpanel_entries]

int

Max subpanel entries for the logged in user(simply grabs the wl_list_max_entries_per_subpanel config key)

logout

Logs the web user out of SuiteCRM and destroys the session.

Arguments

Name Type Desc

session

string

The session id. See login.

Response

No response.

get_available_modules

Returns a list of the modules available for use. Also returns the ACL (Access Control List) for each module.

Arguments

Name Type Desc

session

string

The session id. See login.

filter

string

Filter the modules returned. Either ‘default’, ‘mobile’ or ‘all’.

Response

Name Type Desc

modules

array

An array containing the module details.

modules[][module_key]

string

The key for this module

modules[][module_label]

string

The label for this module

modules[][favorite_enabled]

bool

Always empty. See note at top of page.

modules[][acls]

array

An array containing the ACL list - that is what actions are allowed.

modules[][acls][][action]

string

The action i.e. edit, delete, list etc.

modules[][acls][][access]

bool

Whether or not access is allowed.

get_document_revision

Returns the details for a specific document revision.

Arguments

Name Type Desc

session

string

The session id. See login.

i

string

The id of the document revision to retrieve

Response

Name Type Desc

document_revision

array

An array containing the document revision details

document_revision[id]

string

The id of the document revision.

document_revision[document_name]

string

The name of the document revision

document_revision[revision]

int

The revision number of the document revision.

document_revision[filename]

string

The filename of the file

document_revision[file]

binary string

The full contents of the file

get_entries

Gets a list of entries for a specific module and list of module ids. Optionally allows returning related records.

Arguments

Name Type Desc

session

string

The session id. See login.

module_name

string

The name of the module to display entries for.

ids

array

An array of record ids to fetch

ids[]

string

An individual id

select_fields

array

An array of fields to return. An empty array will return all fields.

select_fields[]

string

The name of a field to return

link_name_to_fields_array

name_value_list

An array of relationships to retrieved.

link_name_to_fields_array[][name]

string

The name of the link to follow (as defined in module_name).

link_name_to_fields_array[][value]

array

An array of the fields to return for this related module.

link_name_to_fields_array[][value][]

string

The field name

track_view

bool

Whether to mark these records as recently viewed.

Response

Name Type Desc

entry_list

array

An array of records.

entry_list[]

array

Details for an individual record.

entry_list[][id]

string

The id of this record.

entry_list[][module_name]

string

The name of the module this record belongs to.

entry_list[][name_value_list]

name_value_list

An array containing each returned field.

entry_list[][name_value_list][]

array

Details for an individual field.

entry_list[][name_value_list][][name]

string

The name of the field.

entry_list[][name_value_list][][value]

string

The value of the field.

relationship_list

array

An array of arrays containing the relationships for the corresponding record.

relationship_list[]

array

The relationships for the corresponding record.

relationship_list[link_list]

array

The list of relationships for this record.

relationship_list[link_list][]

array

Details of a single relationship.

relationship_list[link_list][][name]

string

The name of this relationship.

relationship_list[link_list][][records]

array

The related records for this relationship.

relationship_list[link_list][][records][]

array

Details of a single related record.

relationship_list[link_list][][records][][link_value]

name_value_list

An array of the requested fields for this relationship.

relationship_list[link_list][][records][][link_value][]

array

A name value pair for this particular field.

relationship_list[link_list][][records][][link_value][name]

string

The name of the field.

relationship_list[link_list][][records][][link_value][value]

string

The value of the field.

get_entries_count

Returns a count of entries matching the given query.

Arguments

Name Type Desc

session

string

The session id. See login.

module_name

string

The name of the module to display entries for.

query

string

An SQL WHERE clause to apply to the query.

deleted

bool

Whether to include deleted records

Response

Name Type Desc

result_count

int

The count of matching entries.

get_entry

Returns the details for a single record. Optionally allows returning related records.

Arguments

Name Type Desc

session

string

The session id. See login.

module_name

string

The name of the module to fetch the entry for.

id

string

The id of the record to fetch

select_fields

array

An array of fields to return. An empty array will return all fields.

select_fields[]

string

The name of a field to return

link_name_to_fields_array

name_value_list

An array of relationships to retrieved.

link_name_to_fields_array[][name]

string

The name of the link to follow (as defined in module_name).

link_name_to_fields_array[][value]

array

An array of the fields to return for this related module.

link_name_to_fields_array[][value][]

string

The field name

track_view

bool

Whether to mark these records as recently viewed.

Response

Identical to the response by get_entries except only one record will be returned.

get_entry_list

Returns a list of records for a given module, with optional filtering, pagination, and related record retrieval.

Arguments

Name Type Desc

session

string

The session id. See login.

module_name

string

The name of the module to fetch the entry for.

query

string

An SQL WHERE clause to apply to the query.

order_by

string

In theory for ordering results but this is unused.

offset

int

The result offset. Useful for pagination.

select_fields

array

An array of fields to return. An empty array will return all fields.

select_fields[]

string

The name of a field to return

link_name_to_fields_array

name_value_list

An array of relationships to retrieved.

link_name_to_fields_array[][name]

string

The name of the link to follow (as defined in module_name).

link_name_to_fields_array[][value]

array

An array of the fields to return for this related module.

link_name_to_fields_array[][value][]

string

The field name

max_results

int

The maximum number of results to return. Useful for pagination.

deleted

bool

Whether to include deleted records.

favorites

bool

Unused. See note at top of page.

Response

Name Type Desc

result_count

int

The number of returned records.

total_count

int

The total number of records matching the query.

next_offset

int

The offset of the next set of records.

entry_list

array

An array of records.

entry_list[]

array

Details for an individual record.

entry_list[][id]

string

The id of this record.

entry_list[][module_name]

string

The name of the module this record belongs to.

entry_list[][name_value_list]

name_value_list

An array containing each returned field.

entry_list[][name_value_list][]

array

Details for an individual field.

entry_list[][name_value_list][][name]

string

The name of the field.

entry_list[][name_value_list][][value]

string

The value of the field.

relationship_list

array

An array of arrays containing the relationships for the corresponding record.

relationship_list[]

array

The relationships for the corresponding record.

relationship_list[link_list]

array

The list of relationships for this record.

relationship_list[link_list][]

array

Details of a single relationship.

relationship_list[link_list][][name]

string

The name of this relationship.

relationship_list[link_list][][records]

array

The related records for this relationship.

relationship_list[link_list][][records][]

array

Details of a single related record.

relationship_list[link_list][][records][][link_value]

name_value_list

An array of the requested fields for this relationship.

relationship_list[link_list][][records][][link_value][]

array

A name value pair for this particular field.

relationship_list[link_list][][records][][link_value][name]

string

The name of the field.

relationship_list[link_list][][records][][link_value][value]

string

The value of the field.

get_language_definition

Returns the language label definitions for one or more modules. Useful for retrieving display labels for fields and dropdowns. Optionally returns an md5 of the labels instead of the labels themselves, which can be used for caching.

Arguments

Name Type Desc

session

string

The session id. See login.

modules

array

An array of the modules to return language labels for

modules[]

string

The modules name.

md5

bool

Whether to return the md5 for each module. Can be useful for caching responses.

Response

Name Type Desc

result[<modulename>]</modulename>

string/array

An array of the labels or an md5 string for <modulename />

get_last_viewed

Returns a list of the most recently viewed modules for the current user.

Arguments

Name Type Desc

session

string

The session id. See login.

module_names

array

An array of the modules to return the last viewed records for.

module_names[]

string

The modules name.

Response

Name Type Desc

result[]

array

An array of the details of recently viewed records

result[][id]

string

The id of the tracker row for this viewing

result[][item_id]

string

The id of the viewed record.

result[][item_summary]

string

The summary of the record. This is usually it’s name.

result[][module_name]

string

The module for this record.

result[][monitor_id]

string

The monitor id for this viewing. Legacy and unused.

result[][date_modified]

string

The date that this record was viewed.

get_modified_relationships

Returns a list of the modified relationships for the current user between one of the Calls, Meetings or Contacts modules.

Arguments

Name Type Desc

session

string

The session id. See login.

module_name

string

The name of the module to retrieve relationships for. Always Users.

related_module

string

The related module to retrieve records for. One of Meetings, Calls or Contacts.

from_date

string

The start date of the range to search. In the format Y-m-d H:i:s.

to_date

string

The end date of the range to search. In the format Y-m-d H:i:s.

offset

int

The record offset to start with.

max_results

int

The maximum number of results to return.

deleted

bool

Whether to include deleted records.

module_user_id

string

In theory the id of the user to return relationships for. However the current user is always used.

select_fields

array

An array of the fields to return for the relationship record. An empty array will return all fields.

select_fields[]

string

The name of the field to return.

relationship_name

string

The name of the relationship between module_name and related_module.

deletion_date

string

A start date for the range in which to return deleted records. In the format Y-m-d H:i:s.

Response

Name Type Desc

result_count

int

The number of returned records.

next_offset

int

The offset of the next set of records.

entry_list

array

An array of the returned records.

entry_list[]

array

Details for an individual record.

entry_list[][id]

string

The id of this record.

entry_list[][module_name]

string

The name of the module this record belongs to.

entry_list[][name_value_list]

name_value_list

An array containing each returned field.

entry_list[][name_value_list][]

array

A name value pair of the field information.

entry_list[][name_value_list][][name]

string

The name of the field.

entry_list[][name_value_list][][value]

string

The value of the field.

error

array

An array containing the error details.

error[number]

int

The error number of the error that occurred.

error[name]

string

The name of the error that occurred.

error[description]

string

A description of the error that occurred.

get_module_fields

Returns the field definitions for a given module.

Arguments

Name Type Desc

session

string

The session id. See login.

module_name

string

The name of the module to return field definitions for.

fields

array

An array of fields to return definitions for. An empty array will return all fields.

fields[]

string

The name of the field.

Response

Name Type Desc

module_name

string

The name of the module.

table_name

string

The name of the database table for this module.

module_fields

array

An array of the requested fields for this module.

module_fields[]

array

The details of a specific field.

module_fields[name]

string

The name of the field.

module_fields[type]

string

The type of the field.

module_fields[group]

string

The group of fields that this field belongs to. Used for addresses or link definitions.

module_fields[id_name]

string

The name of the id field on this module for this link if appropriate.

module_fields[label]

string

The display label for this field.

module_fields[required]

bool

Whether this field is required or not.

module_fields[options]

name_value_list

An array of possible options for this field. An empty array if options are not appropriate for this field type.

module_fields[options][]

array

A name value pair of a single option.

module_fields[options][][name]

string

The options key.

module_fields[options][][value]

string

The options display value.

module_fields[related_module]

string

The related module for this field if it is a related type. Empty otherwise.

module_fields[calculated]

string

Always empty. See note at top of page.

module_fields[len]

int

The length of this field or an empty string if this is not appropriate for this field type.

link_fields

array

An array of the requested link fields for this module.

link_fields[]

array

The details of a specific field.

link_fields[name]

string

The name of the field.

link_fields[type]

string

The type of the field. Will always be link.

link_fields[group]

string

The group of fields that this field belongs to. Will be empty for links.

link_fields[id_name]

string

The name of the id field on this module for this link if appropriate.

link_fields[relationship]

string

The relationship name for this link.

link_fields[module]

string

The module this field links to.

link_fields[bean_name]

string

The bean that this field links to.

get_module_fields_md5

Returns an md5 of the a modules field definitions. Useful for caching.

Arguments

Name Type Desc

session

string

The session id. See login.

module_names

array

An array of modules to return the md5 for.

module_names[]

string

The name of the module to return the field definitions md5 for.

Response

Name Type Desc

result[]

array

An array of the md5’s keyed by the module name.

result[<modulename>]</modulename>

string

The md5 string for <modulename />

get_module_layout

Returns the layout for specified modules and views. Optionally returns an md5 of the layouts.

Arguments

Name Type Desc

session

string

The session id. See login.

modules

array

An array of the modules to return layouts for.

modules[]

string

The name of the module.

types

array

An array of the types of views to return. Only default is supported.

types[]

string

The type of the views.

views

array

An array of the views to return. One of edit, detail, list and subpanel.

views[]

string

The name of the view.

acl_check

bool

Whether or not to check that the current user has access to this module and view.

md5

bool

Whether or not to return the view as an md5 string. Useful for caching.

Response

Name Type Desc

result

array

The array of results keyed by module name.

result[<modulename>]</modulename>

array

An array of layouts for <modulename>.</modulename>

result[<modulename>][default]</modulename>

array

An array of the layouts keyed by the view name.

result[<modulename>][default][<viewname>]</viewname></modulename>

array/string

The layout of the view <viewname> for the module <modulename> or an md5 of the layout. See the section on metadata for the layout format.</modulename></viewname>

get_module_layout_md5

Returns the md5 of the specified views for the specified modules. Behaves identically to get_module_layout with the md5 parameter set to true.

Arguments

Name Type Desc

session

string

The session id. See login.

modules

array

An array of the modules to return layouts for.

modules[]

string

The name of the module.

types

array

An array of the types of views to return. Only default is supported.

types[]

string

The type of the views.

views

array

An array of the views to return. One of edit, detail, list and subpanel.

views[]

string

The name of the view.

acl_check

bool

Whether or not to check that the current user has access to this module and view.

Response

Name Type Desc

md5

array

The array of results keyed by module name.

md5[<modulename>]</modulename>

array

An array of layouts for <modulename>.</modulename>

md5[<modulename>][default]</modulename>

array

An array of the layouts keyed by the view name.

md5[<modulename>][default][<viewname>]</viewname></modulename>

string

The md5 of the layout layout of the view <viewname> for the module <modulename>.</modulename></viewname>

get_relationships

Returns related records given a specific module, record and list of links.

Arguments

Name Type Desc

session

string

The session id. See login. 

module_name

string

The module to return relationships for.

module_id

string

The record to return relationships for. 

link_field_name

string

The link field to follow for this record. 

related_module_query

string

A WHERE clause to use to filter the related modules by. 

related_fields

array

An array of the fields to return for matching records. 

related_fields[]

string

The name of the field. 

related_module_link_name_to_fields_array

name_value_list

An array of related fields to return for matching records. 

related_module_link_name_to_fields_array[]

array

Details for a specific link.

related_module_link_name_to_fields_array[][name]

string

The name of the link to follow for matching records. 

related_module_link_name_to_fields_array[][value]

array

An array of fields to return for this link. 

related_module_link_name_to_fields_array[][value][]

string

The field name. 

deleted

bool

Whether to include deleted records. 

order_by

string

In theory for ordering results but this is unused. 

offset

int

The record offset to start with. 

limit

int

The maximum number of results to return. 

Response

Identical to the response by get_entries.

get_server_info

Returns information about the SuiteCRM server, including the SugarCRM compatibility flavor, version string, and current server time in UTC.

Arguments

No arguments.

Response

Name Type Desc

flavor

string

The SugarCRM flavor. For SuiteCRM will always be ‘CE’.

version

string

The SugarCRM version. Note that this is distinct from the SuiteCRM version

gmt_time

string

The server time in UTC.

get_upcoming_activities

Returns a list of the 10 upcoming activities (Meetings, Calls and Tasks - also includes Opportunities) for the currently logged in user.

Arguments

Name Type Desc

session

string

The session id. See login.

Response

Name Type Desc

result

array

An array of the upcoming activities.

result[]

array

The details of a single activity.

result[][id]

string

The id of this activity.

result[][module]

string

The module for this activity.

result[][date_due]

string

The due date for this activity.

result[][summary]

string

The summary of this activity. Usually simply it’s name.

get_user_id

Returns the id of the currently logged in user.

Arguments

Name Type Desc

session

string

The session id. See login.

Response

Name Type Desc

id

string

The id of the current user.

seamless_login

Marks a session as allowing a seamless login. If successful then the session id (see the login call) can be used in a URL (as MSID) to log the user into SuiteCRM in the browser seamlessly. For example if you have the session id 1234 then accessing the URL example.com/index.php?MSID=1234. The MSID parameter can be used in any valid SuiteCRM URL.

Arguments

Name Type Desc

session

string

The session id. See login.

Response

Name Type Desc

result

bool

Boolean indicating success

search_by_module

Allows searching for records that contain a specific search string.

Arguments

Name Type Desc

session

string

The session id. See login.

search_string

string

The string to search for.

modules

array

An array of the modules to include in the search.

modules[]

string

The modules name.

offset

int

The result offset. Useful for pagination.

max_results

int

The maximum number of results to return. Useful for pagination.

assigned_user_id

string

Filter by the given assigned user. Leave blank to do no user filtering.

select_fields

array

An array of the fields to return for the found records. An empty array will return all fields.

select_fields[]

string

The name of the field to return.

unified_search_only

bool

Whether to only return records for modules that participate in the global search.

favorites

bool

Unused. See note at top of page.

Response

Name Type Desc

entry_list

array

An array of the results for each module.

entry_list[]

array

Results for a specific module.

entry_list[][name]

string

The name of the module that this entry contains results for.

entry_list[][records]

array

An array of the record results.

entry_list[][records][]

name_value_list

A name value list of records id and name.

entry_list[][records][][id]

array

A name value pair containing the id of this record.

entry_list[][records][][name]

array

A name value pair containing the name of this record.

set_document_revision

Creates a new document revision for a document.

Arguments

Name Type Desc

session

string

The session id. See login.

note

array

An array containing the document revision details.

note[id]

string

The id of the document to add this revision to.

note[file]

binary string

The binary contents of the file, base 64 encoded.

note[filename]

string

The name of the file.

note[revision]

int

The revision number for this revision.

Response

Name Type Desc

id

string

The id of the newly created document revision.

set_entries

Creates or updates a list of records.

Arguments

Supplying a value for the id field will perform an update for that record.

Name Type Desc

session

string

The session id. See login.

module_name

string

The name of the module to create/update records for.

name_value_lists

name_value_list

An array of the details for each record to create/update.

name_value_lists[]

array

Details of an individual record.

name_value_lists[][]

array

A name value pair for each field value.

name_value_lists[][][name]

array

The name of the field.

name_value_lists[][][value]

array

The value for the field.

Response

Name Type Desc

ids

array

An array of the resulting ids. Returned in the same order as specified in the call to set_entries.

ids[]

array

The id for this record.

set_entry

Creates or updates a single record.

Arguments

Supplying a value for the id field will perform an update for that record.

Name Type Desc

session

string

The session id. See login.

module_name

string

The name of the module to create/update a record for.

name_value_list

name_value_list

An array of the fields for the new/updated record.

name_value_list[]

array

A name value pair for each field value.

name_value_list[][name]

string

The name of the field.

name_value_list[][value]

string

The value for the field.

Response

Name Type Desc

id

string

The id of the newly created or updated record.

get_note_attachment

Returns the details of a given note attachment.

Arguments

Name Type Desc

session

string

The session id. See login.

id

string

The id of the note to retrieve information for.

Response

Name Type Desc

note_attachment

array

The details for the note attachment.

note_attachment[id]

string

The id of the note to retrieve information for.

note_attachment[filename]

string

The filename of the file

note_attachment[file]

binary string

The full contents of the file

note_attachment[related_module_id]

string

The id of the record that this attachment is related to.

note_attachment[related_module_name]

string

The module of the record that this attachment is related to.

set_note_attachment

Creates a note attachment for a specified record.

Arguments

Name Type Desc

session

string

The session id. See login.

note

array

The details for the note attachment.

note[id]

string

The id of the note to add an attachment for.

note[filename]

string

The filename of the file

note[file]

binary string

The full contents of the file base 64 encoded.

Response

Name Type Desc

id

string

The id of the note for this attachment.

set_relationship

Sets a relationship between a record and other records.

Arguments

Name Type Desc

session

string

The session id. See login.

module_name

string

The name of the module to relate records to.

module_id

string

The id of the record to relate records to.

link_field_name

string

The name of the link field on the module through which records will be related.

related_ids

array

An array of record ids to relate.

related_ids[]

string

The id of a record to relate.

name_value_list

name_value_list

A name value list of additional relationship fields to set.

name_value_list[]

array

A name value pair for a relationship field to set.

name_value_list[][name]

string

The name of the field to set.

name_value_list[][value]

string

The value of the field to set.

delete

bool

Whether or not to delete the specified relationship instead of creating/updating it.

Response

Name Type Desc

created

int

The number of relationships created.

failed

int

The number of relationships that failed to be created/deleted.

deleted

int

The number of relationships deleted.

set_relationships

Sets relationships between multiple records.

Arguments

Name Type Desc  

session

string

The session id. See login.  

module_names

array

An array of modules to relate records to.

module_names[]

string

The name of the module to relate records to. 

module_ids

array

An array of the ids of records to relate records to.

module_ids[]

string

The id of the record to relate records to.

link_field_names

string

An array of the link names through which records will be related.

link_field_names[]

string

The name of the link field on the module through which records will be related.  

related_ids

array

An array of an array of record ids for each module specified.  

related_ids[]

array

An array of record ids for the corresponding module.

related_ids[][]

string

The record id.  

name_value_lists

array

An array of an array of name value list of additional relationship fields to set.

name_value_lists[]

name_value_list

An array of name value pairs for the relationship fields of the corresponding module.  

name_value_lists[][name]

string

The name of the field to set.  

name_value_lists[][value]

string

The value of the field to set.

delete_array

array

An array of booleans indicating whether or not the relationship should be deleted for each module.  

delete_array[]

bool

Whether or not to delete the specified relationship instead of creating/updating it.  

Response

Name Type Desc

created

int

The number of relationships created.

failed

int

The number of relationships that failed to be created/deleted.

deleted

int

The number of relationships deleted.

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.