Skip to main content

SmartConnect API Endpoints, Parameters, and Function Settings Reference

Updated

SmartConnect API function settings, field list syntax, endpoints, and parameters define how requests are built and what responses return.

NOTE  SmartSimple is transitioning from the classic syntax using "@" to a new syntax using curly braces. Both syntaxes are currently supported.

It is recommended that global administrators enable the new syntax. Locate the System Options section in Global Settings, and toggle Enable New Variable Syntax Set on.
IMPORTANT  The SmartConnect API is a legacy API, and the new REST API is intended to replace it. SmartSimple recommends the REST API instead of the SmartConnect API. For more information, see Use REST API.

Function Settings

Each SmartConnect API function includes the following settings:

Setting Description
Function Name The name used to call the function from code.
Description The function's purpose.
Object Type A list of all SmartSimple objects within the instance. See the Available Object Types section of this article.
Action Type Defines the action the function takes. The available actions depend on the object type. See the Action Types by Object Type section of this article for the actions available to each object type and the Available Action Types section of this article for descriptions of each action.
Field List Defines which fields are retrievable through the function call. It is recommended to limit the field list to approximately 50 standard or custom fields. Syntax is described in the Field List Syntax section of this article.
Allow Access Select the user roles that can access this function.
Return Key Format The three options are As Inputted, Custom Field Name, and Custom Field ID.
Numeric Data Format The two options are Raw Numeric Value and Formatted Numeric Value.
API Token Displays the token after the function is saved.
Required Parameters Lists any required parameters after the function is saved.
Optional Parameters Lists any optional parameters after the function is saved.
Created By / Date Details when the function was created.
Modified By / Date Details the last saved change.

Update Action Fields

When the Action Type is set to Update, the following additional fields appear:

Setting Description
Enable Input Filtering Applies input filtering for field values to prevent cross-site scripting.
Disable Field Change History Fields updated by this API call are not included in the field change history log.
Defer Post Update Process Runs post-update processes such as template formula and workflow asynchronously to improve performance.
Run in Background Queues records to run in the background to improve performance.
Bypass Field Type Validation Allows updates to certain problematic field types.

↑ Back to top

Action Types by Object Type

The following table lists the actions available to each object type. Descriptions of each action are in the Available Action Types section of this article.

Object Type Available Actions
Company, User, and universal tracking application (UTA)/module Delete, Get, Get Meta, List, Update, Associations - List, Associations - Update, Files - Delete, Files - Download, Files - List, Files - Search, Files - Upload, Multiple Addresses - List, Multiple Addresses - Update, Notes - List, and Variables Replace.
UTA/module Level 1 and Level 2 Includes the Provider/Consumer - List and Provider/Consumer - Update actions.
Company Transactions and User Transactions Includes an additional Link/Unlink action.
Report Includes the Report - Query action.
Roles Includes the Get Meta action.
System Variables Includes the Get, List, and Update actions.

↑ Back to top

Available Object Types

The standard fields available for reference vary based on the Object Type selected in the API call.

Object Type Description
Report Execute a report and retrieve the results.
Company Records pertaining to organizations.
User Records related to contacts.
System Variables Global system variables.
UTA/module records UTA/module records, encompassing Levels 1, 2, 3, and associated transactions.

↑ Back to top

Available Action Types

Not all actions are available for all object types.

Action Description
Get Retrieve a single record corresponding to the selected object type in the function.
List Retrieve multiple records corresponding to the selected object type in the function.
Update Update one or more fields for the specified record(s). The Update action is also used to create new records.
Get Meta Retrieve configuration settings for a UTA/module concerning Level 1/2/3 attributes such as types, statuses, and field definitions.
Update Meta Update the configuration settings for a UTA/module with respect to Level 1/2/3 attributes such as types, statuses, and field definitions.
Download File Download a single file from a specified record and field.
List Files Retrieve a list of files from a specified record and field.
Search Files Retrieve a list of files across a specific object type via keyword search of file contents. Upload fields searched are restricted based on the field list specified in the API call.
Update Associations Update one or more fields in the association table between two records. Also used to create new association records, such as contacts or organizations associated with a UTA/module Level 1 record.
List Associations Retrieve a list of associations for the specified record, such as contacts or organizations associated with a UTA/module Level 1 record.
List Multiple Addresses Retrieve a list of addresses for the specified contact or organization record.
Update Multiple Addresses Update one or more fields for the specified address for a contact or organization record. Also used to create new address records.
Variables Replace Return formatted content processed by the variable processor from a specified record. All variables in the content parameter are replaced with values from that record. For example, for a contact named John Smith, passing the following content returns Hello John.
New syntax Hello {{firstname}}
Old syntax Hello @firstname@

↑ Back to top

Field List Syntax

The field list in the function configuration specifies which fields are retrievable through the function call. The field list uses the following syntax:

Syntax Description Example
sf_StandardFieldName Standard fields use their name preceded by the prefix sf_. sf_First Name
cf_CustomFieldName
cf_CustomFieldID 		Custom fields use their field name preceded by the prefix cf_. Reference the field name or the field ID. cf_My Custom Field
cf_12345
;; Field separator. Separate multiple fields using ;;. sf_First Name;;cf_My Custom Field

↑ Back to top

SmartConnect API Endpoints

Post to the appropriate endpoint based on the Object Type of the API function. The general endpoint format is:

/API/APIVersion/recordtype/

The following table lists the endpoint and an example URL for each Object Type:

Object Type Endpoint Example
Report /API/1/report/ https://example.smartsimple.com/API/1/report/
Company /API/1/company/ https://example.smartsimple.com/API/1/company/
User /API/1/user/ https://example.smartsimple.com/API/1/user/
System Variables /API/1/sysvar/ https://example.smartsimple.com/API/1/sysvar/
UTA/module Level 1 /API/1/levelone/ https://example.smartsimple.com/API/1/levelone/
UTA/module Level 2 /API/1/leveltwo/ https://example.smartsimple.com/API/1/leveltwo/
UTA/module Level 3 /API/1/levelthree/ https://example.smartsimple.com/API/1/levelthree/
UTA/module Level Transaction /API/1/transactions/ https://example.smartsimple.com/API/1/transactions/

↑ Back to top

Message Body Parameters

The following parameters must always be included:

Parameter Description
url String containing the URL to which the request is directed.
apitoken Encrypted token generated and associated with each SmartConnect function.
jsonrset (update functions only) JSON array containing one or more records to update. The top node must be labeled records, with each sub-node representing a record. Each record is identified by a recordid value corresponding to the unique SmartSimple ID for that record (for example, userid for a user or contact record) and must include all fields defined in the function's field list. If a field value is not being modified, set it to the current value.

For remote calls from an external system, also include:

Parameter Description
username Email address associated with an active API type user account.
password Corresponding password for the user account.
companyid Root company ID of the SmartSimple instance, representing the organization at the root of the instance.
alias Web alias of the instance, typically the leading portion of the instance URL. To find it, click the System Administration gear in the upper navigation bar, select Global Settings from the drop-down menu, and click the Branding tab. For example, for https://example.smartsimple.com, the alias is example.

↑ Back to top

Sample Call and Responses

Sample Call for an Active Session

function api_call() {
  $.ajax({
    method: "POST",
    type: "POST",
    url: "/API/1/levelone/",
    data: {
      apitoken: "YOUR_API_TOKEN",
      recordid: 1234567,
    },
    dataType: "html"
  })
  .done(function(data) {
    json = JSON.parse(data);
  });
}

↑ Back to top

POST Response

For every successful request, SmartSimple returns HTTP status 200 with a JSON response body containing the record set. For response and error messages, see SmartConnect API Response Messages Reference.

Sample Response for GET and LIST

{
  "records":[
    {
      "sf_Description":"0959-3985",
      "sf_Transaction ID":"6048788",
      "sf_Created Date":"2015-07-23 11:03:17",
      "sf_End Date":"2015-07-23 11:03:17",
      "sf_Subject":"API Test",
      "sf_Object ID":"0",
      "sf_Start Date":"2015-07-22 00:00:00",
      "sf_Modified Date":"2018-05-09 11:14:58",
      "sf_Type":"Publications",
      "sf_Created By":"SmartSimple Support"
    }
  ],
  "message":{}
}

Sample Response for UPDATE

For record updates and creations, the response returns the recordid and a status of updated successfully.

{
  "records":[
    {
      "recordid":"6048788",
      "recordindex":1,
      "status":"updated successfully"
    }
  ],
  "message":{}
}

↑ Back to top

Update Function Behavior

Update Function Field Values and New Records

  • Date field values require the format YYYY-MM-DD.
  • It is recommended to set Select One and Select Many fields using stored values, not display captions. For example, if a field has options 1=Yes;2=No, use 1 or 2.
  • To create a new record, set the recordid to 0. The response returns the recordid of the newly created record.

↑ Back to top

System Behavior After an Update

When updates are executed, the system behaves as it would when saving a record through the browser interface:

  • The system executes applicable template formulas after the record updates.
  • The system initiates applicable workflows after the record updates.
  • The system engages applicable status triggers for any status change that follows a record update.

↑ Back to top

List Function Parameters

The maximum number of records returned per API call is 10,000. If a query matches more than 10,000 records, use pagination parameters to retrieve all results across multiple calls.

criteria Parameter

Optional JSON array with the following nodes: andor, field, operator, and value.

Node Description
andor Valid values are and or or.
field Name of the standard or custom field to which the condition applies.
operator Valid values are =, !=, like, not like, and isempty.
value The filter value.

Sample syntax 1:

criteria: [{"andor":"and","field":"FIELDNAME","operator":"like","value":"PATTERN"},
{"andor":"and","field":"FIELDNAME2","operator":"isempty","value":"true"}]
sortby: [{"field":"FIELDNAME","direction":"asc"}]
othersettings: {"getstorevalue":"1","keyformat":"0"}

Sample syntax 2:

criteria: [{"andor":"and","field":"FIELDNAME1","operator":"=","value":"100"},
{"andor":"or","field":"FIELDNAME2","operator":"like","value":"PATTERN"},
{"andor":"and","field":"FIELDNAME3","operator":"isempty","value":"false"}]
sortby: [{"field":"FIELDNAME","direction":"desc"}]
othersettings: {"getstorevalue":"0","keyformat":"0"}

Sample syntax 3, using brackets:

criteria: [{"andor":"(","field":"cf_somefield1","operator":"like","value":"whatever"},
{"andor":"or","field":"cf_somefield2","operator":"like","value":"whatever"},
{"andor":"or","field":"cf_somefield3","operator":"like","value":"whatever"},
{"andor":"or","field":"cf_somefield4","operator":"like","value":"whatever"},
{"andor":") and (","field":"cf_someotherfield1","operator":"=","value":"whatever"},
{"andor":"or","field":"cf_someotherfield2","operator":"=","value":"whatever else"}]
othersettings: {"getstorevalue":"0","keyformat":"0"}

↑ Back to top

sortby Parameter

Optional JSON array with the following nodes: field and direction.

Node Description
field Name of the standard or custom field by which to sort records.
direction Valid values are asc ascending or desc descending.

↑ Back to top

othersettings Parameter

The following table describes the optional settings available in the othersettings parameter:

Setting Description
getstorevalue Optional. Set to 0 to retrieve the display value or 1 to obtain the stored value: for example, $25,000.00 versus 25000.
keyformat Optional. Set to 0 to use what is configured in the Field List from the SmartConnect function, 1 to use custom field names or standard field names, or 2 to use the custom field ID.

↑ Back to top

Pagination

Include the following parameters within the othersettings JSON object to control pagination: recordstart, recordend, recordsperpage, pagenum.

Example

Pagination combined with other settings:

{"getstorevalue":"1","keyformat":"1","recordsperpage":100,"recordstart":1000}

The response includes the following values in the message node:

Value Description
recordfrom Starting record number.
recordto Last record number returned.
recordcount Number of records returned in this call.
allcount Total number of records without the limit.

Example

A message node from a paginated response:

"message":{"recordto":424,"recordcount":100,"allcount":460,"recordfrom":325}

↑ Back to top

Pagination Priority

When multiple parameters are set, the following priority applies:

Priority Condition Behavior Example
1 recordend > 0 Only recordstart and recordend are considered.
othersettings: {"recordend":35}
Returns records 1 to 35.
othersettings: {"recordstart":10,"recordend":35}
Returns records 10 to 35.
othersettings: {"recordstart":10,"recordend":350,"recordsperpage":100}
recordsperpage is ignored; returns records 10 to 350.
2 pagenum > 0 and recordsperpage > 0 recordstart and recordend are ignored.
othersettings: {"recordsperpage":50,"pagenum":2}
Returns records 51 to 100.
othersettings: {"recordsperpage":100,"recordstart":12,"pagenum":1}
recordstart is ignored; returns records 1 to 100.
othersettings: {"recordsperpage":100,"recordstart":12,"pagenum":3}
recordstart is ignored; returns records 201 to 300.
3 recordsperpage > 0 Returns records based on page size.
othersettings: {"recordsperpage":100}
Returns records 1 to 100.
othersettings: {"recordsperpage":100,"recordstart":1}
Returns records 1 to 100.
othersettings: {"recordsperpage":100,"recordstart":101}
Returns records 101 to 200.
othersettings: {"recordsperpage":100,"recordstart":325}
Returns records 325 to 424.
4 recordstart > 0 Returns all records from the specified starting point, up to the 10,000-record maximum.
othersettings: {"recordstart":12}
Returns all records from record 12.

↑ Back to top

Search for Empty or Non-empty Values

Use the isempty operator in a criteria node to search for records where a field is empty or non-empty. Set the value to true or false.

Example

Return records where the field cf_123456 is empty:

criteria:[{"andor":"and","field":"cf_123456","operator":"isempty","value":"true"}]

↑ Back to top

Exclude or Include Archived UTA/module Records

Use the includearchive parameter within the othersettings JSON object to control whether archived UTA/module records are included. If this parameter is omitted or set to 1, all records are included. Set to 0 to exclude archived records.

Example

100 records per page with archived records excluded:

othersettings: {"recordsperpage":100,"includearchive":0}

↑ Back to top

Report Permissions

By default, only users with Manager permission - reports can view reports through the API Report Function. The role of the active SmartSimple user account must have the necessary permissions to access reports. 

↑ Back to top

Error Messages

For failed requests, SmartSimple returns HTTP 4xx status codes.

The following table lists common symptoms and the causes or items to check:

Symptom Cause or Item to Check
HTTP 401 Unauthorized Invalid authentication credentials.
HTTP 401 Unauthorized The user account type is not designated as API User.
HTTP 401 Unauthorized The companyid parameter is inaccurate for remote calls.
Request succeeds but the response is empty Check that the apitoken parameter is correct.
Request succeeds but the response is empty Check that the recordid is accurate for updates.
Request succeeds but the response is empty Check that the post endpoint URL points to the correct resource.

Error and status messages vary across API calls depending on the records involved. For the full list of response messages, see SmartConnect API Response Messages Reference.

↑ Back to top

Hourly API Call Limit

API calls exceeding 1,000 per instance within the past hour result in an error. Calls are blocked until the total number of API calls in the past hour falls below the limit. Calls over the limit return HTTP 429. 

↑ Back to top

Helpful Links