Overview

SmartSimple's SmartConnect API offers a user-friendly approach to integrating SmartSimple data with other web services and systems. This API is RESTful in nature and adheres loosely to the principles of REST integration.

• The API utilizes industry-standard JSON syntax and constructs. If you are not familiar with JSON, it is advisable to review the following tutorial before proceeding further with this topic.
• This API is not intended for the export and import of large volumes of information.

• There are no metering restrictions imposed by this API regarding the number of records retrievable in a single API query. However, retrieving a substantial number of records (exceeding 1000 records) may adversely affect performance and could potentially lead to query failures.

Prerequisites

• This API is exclusively available for SmartSimple environments running on the November 2015 release or later. It is recommended to upgrade to the latest available release to access the most current API functionality.

Configuration - Essentials

Initial Setup

An active SmartSimple user account is required to execute any API calls. There are two operational modes for this API; if you intend to make remote calls, you must first create and activate a user account designated for API access.

• Active session: This mode allows a user who is already logged into SmartSimple with an active session to make an API call from their web browser, such as an AJAX call. The existing session is utilized to authenticate the API call.
• Remote call: This mode involves an external system making an API call. For this method, a user account of type API Access is necessary for the authentication of the API call.

  

   

  The roles and access settings for a user designated for remote calls.

Function Definition

To utilize the API, it is essential to first define the set of functions that you wish to make available within SmartSimple. This serves as an additional layer of security, allowing you to restrict the functions and field sets that you choose to expose through the API.

1. Within your SmartSimple instance, define an API function in the Global Settings -> Integrations -> SmartConnect API screen.
2. In this screen, you will encounter options for Record Type, Action Type, and Field List which define, respectively, the type of record, the action to be performed, and the field list that will be exposed for this function.
3. After saving your function, please take note of the API Token as it must be included in your API calls to identify this pre-defined function.

Field List Syntax

The Field List option within the function configuration is utilized to specify which fields are retrievable through the function call. This is a free-form text box in which you must construct your field list using the following syntax:

Usage

Ensure that SmartConnect API functions have been created in the instance prior to utilizing the API.

Posting Endpoints

To execute an API call, you will need to post to the appropriate endpoint, which will be determined by the Record Type of the API function. The general endpoint will follow the format:

/API/APIVersion/recordtype/

A comprehensive list of endpoints is provided below.

As of the August 2022 upgrade, APIVersion=2 is now available. This version has standardized the syntax and format of requests and responses.

Message Body

The message body that you post must include various parameters based on the Record Type and Action Type being utilized. The required and optional parameters will be outlined for each distinct function on the configuration page of each SmartConnect function.

At a minimum, the following parameters must always be included:

• url: A string containing the URL to which the request is directed.
• apitoken: An encrypted token generated and associated with each SmartConnect function.
• jsonrset (for update functions only): A JSON array containing one or more records to update. The top node should be labeled 'records', with each sub-node representing a record to be updated. Each record sub-node is identified by a 'recordid' value that corresponds to the unique SmartSimple ID for that record (e.g., userid for a user/contact record) and must include all fields defined in the field list of the SmartConnect function. If the field value is not being modified, it should be set to the current value.

If you are executing a remote call from an external system, you will also need to include:

• username: The email address associated with an active API type user account.
• password: The corresponding password for the aforementioned user account.
• companyid: The root companyid of your SmartSimple instance, representing the organization at the root of your instance.
• alias: The web alias of your SmartSimple instance, typically the leading portion of your instance URL, which can be found in your Global Settings -> Branding configuration. For example, for https://example.smartsimple.com, the alias would be 'example'.

Sample call within SmartSimple instance: 

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

POST Response

For every successful request, an HTTP status of 200 is returned along with a JSON response body containing the record set.

Sample response format for GET/LIST calls based on the configured field 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":{

   }
}

For record updates and creations, the response body will simply return the recordid along with a status of "Updated Successfully".

Sample response format for UPDATE calls:

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

   }
}

Important Notes

Utilizing Update Functions

The following are critical considerations to keep in mind when invoking update functions.

• Date field values must be formatted as YYYY-MM-DD.
• Field types with predefined options, such as Select One and Select Many fields, should be assigned their stored value options instead of their display captions. For instance, if a field has defined options like "1=Yes;2=No," it should be set using the values "1" or "2."
• Update functions may also be utilized to create new records. This can be achieved by setting the recordid to 0. The response will return the recordid of the newly created record.

Update Behavior

Please be advised that when executing updates, the system behavior will resemble that of saving a record through the standard browser interface. Specifically, the following actions will occur:

• Any existing and applicable template formulas will be activated and executed post-record update.
• Any existing and applicable workflows will be initiated and executed following a record update.
• Any existing and applicable status triggers will be engaged for any status changes subsequent to a record update.

Utilizing List Functions

• The maximum number of records returned by a single SmartSimple API call is limited to 10,000 records. If the criteria of your API call matches more than 10,000 records, pagination parameters must be employed to facilitate multiple calls, allowing you to navigate through the results and obtain the complete data set.

Custom parameters for List Functions include:

• criteria - an optional JSON array containing the following nodes: "andor," "field," "operator," and "value."

Node values:

"andor" - either "and" or "or"

"field" - the name of the standard or custom field to which the condition applies

"operator" - can utilize the following: =, =, , !=, like, not like

"value" - the filter value

Example 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"}

Example 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"}

Example 3:

An example query utilizing brackets: ( (cf_somefield1 like '%whatever%' or cf_somefield2 like '%whatever%' or cf_somefield3 like '%whatever%' or cf_somefield4 like '%whatever%' ) and (cf_someotherfield1='whatever' or cf_someotherfield2='whatever else'))

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" }]

sortby: 

othersettings : {"getstorevalue":"0","keyformat":"0"}

• sortby - an optional JSON array containing the following nodes: "field" and "direction"

"field" - the name of the standard or custom field by which records will be sorted

"direction" - either "asc" (for ascending) or "desc" (for descending)

• othersettings
  • getstorevalue - an optional setting for the JSON array. Options include: integer type: 0 - to retrieve display value, 1 to obtain stored value (value from the database, e.g., $25,000 vs 25000)
  • keyformat - an optional setting for the JSON array. Options are: 0 - to utilize what is configured in the Field List from the SmartConnect Function, 1 - to employ custom field names or standard field names, and 2 - to utilize the custom field ID

Report Permissions Using the API Report Function

By default, the users permitted to view any reports through the API Function are users with Manager permission – reports.
It is essential to ensure that the role of the active SmartSimple user account possesses the necessary permissions to access the reports.
For guidance on enabling report sharing with users in the API Report Function, please refer to the following link: Sharing Reports with People.

Error Messages

In the event of failed requests, SmartSimple returns HTTP 4xx status codes.

The most frequently encountered case is HTTP 401 Unauthorized, which may indicate one of the following issues:

• Invalid authentication credentials have been supplied.
• The user account type is not designated as "API User."
• If executing remote calls, please verify that the companyid parameter is accurate.

If the request is successful but the response is empty, please review the following troubleshooting steps:

• Confirm that the apitoken parameter is correct.
• If updating, ensure that the recordid is accurate.
• Verify that the post endpoint URL is directed to the correct resource.

Error and status messages may vary across different API calls and are contingent upon the records involved in the API requests.

Additional generic error messages for failed API requests include:

"Invalid API Token"
"The number of API calls within the hour has reached the maximum limit; please try again later."
"Invalid URL: URL must begin with https://."
"Invalid API Request; the request is empty or null."
"An error occurred while processing other setting parameters."
"An error occurred while processing the record."
"An error occurred while processing the list."
"Recordset does not exist."
"The requested record does not exist."
"No records found."
"SmartConnect API function configuration error; association type is missing from the Field List of the function."
"Invalid record ID."
"No content or empty content argument provided."
"No objectid argument provided."
"No object type argument provided."
"Consumer Provider link not configured in SmartConnect API settings."
"The requested field does not correspond with the object type."
"The requested field was not found."
"The requested list does not have a field list defined."
"You do not have permission to view this report."
"Search keywords cannot be empty."

Configuration - Advanced

API User Access Tokens

User access tokens can be utilized for authentication purposes in lieu of providing a username and password within your API call. To generate user access tokens for API users, navigate to the SmartConnect API - API Users tab, select an API user from the list, and click the Generate New Token button.

Utilize the token in the Authorization header formatted as: Bearer xxxxxxxxxxxx in your API call. This will supplant the username and password in your API call.

Appendix

Standard Field Names

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

Options and Settings

Available Record Types

Available Action Types

The following is a comprehensive list of available actions. Please be advised that not all actions will be accessible for all record types.

Pagination

Four new parameters have been introduced and should be included within the "othersettings" JSON object for the API call:
- recordstart, recordend, recordsperpage, pagenum
*Note: The othersettings parameter is also utilized for other settings introduced previously, such as getstorevalue and keyformat. Therefore, your othersettings JSON may resemble the following:
{"getstorevalue":"1","keyformat":"1","recordsperpage":100,"recordstart":1000}

Note: A maximum of 10,000 records will be returned for each API call; thus, multiple API calls will be necessary to display all records with the corresponding pagination parameters.

The returned JSON response will include the following (in the message JSON node) for all records, regardless of whether the aforementioned parameters have been set, with results based on the order specified (sortby declared in the API call or by default order by, e.g., order by L1 ID ascending):
- recordfrom (starting from record number xxx)
- recordto (last record number returned xxx)
- recordcount (number of records returned in this API call)
- allcount (total number of records without the limit)
Returned Response:
e.g. "message":{"recordto":424,"recordcount":100,"allcount":460,"recordfrom":325}

Priority of operations with the four new parameters:
1. When recordend > 0, only the recordstart and recordend parameters will be considered, for example:
othersettings: {"recordend":35} - will return records from the start up to and including the 35th record, total records = 35
othersettings: {"recordstart":10,"recordend":35} - will return the 10th to the 35th record, total records = 26
othersettings: {"recordstart":10,"recordend":350,"recordsperpage":100} - will disregard recordsperpage because you have specified the start and end, returning records 10 to 350, total 341 records.

2. When pagenum > 0 and recordsperpage > 0 (to utilize pagenum, recordsperpage must be specified), recordstart and recordend will be disregarded:
othersettings: {"recordsperpage":50,"pagenum":2} - will return records 51-100
othersettings: {"recordsperpage":100,"recordstart":12,"pagenum":1} - will disregard recordstart, returning records 1-100
othersettings: {"recordsperpage":100,"recordstart":12,"pagenum":3} - will disregard recordstart, returning records 201-300.

3. When recordsperpage > 0:
othersettings: {"recordsperpage":100} - will return records 1 to 100
othersettings: {"recordsperpage":100,"recordstart":1} - will return records 1 to 100
othersettings: {"recordsperpage":100,"recordstart":101} - will return records 101 to 200
othersettings: {"recordsperpage":100,"recordstart":325} - will return records 325 to 424.

4. When recordstart > 0:
othersettings: {"recordstart":12} - will return all records starting from record 12, up to a maximum of 10,000 records.

Searching for Empty or Non-empty Values

Criteria can now be added to search for records where a field is either empty or not. You may include an operator of isempty, with a corresponding value of either true or false, within a criteria to search for records based on empty or non-empty values.

For example:

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

Exclusion (or Inclusion) of Archived UTA Records

New parameters have been introduced to exclude archived UTA records, which should be included within the "othersettings" JSON object for the API call:
includearchive - if this node is omitted or set to {"includearchive":1}, all records will be included in the search. To exclude archived records, set the parameter to 0.
For example, if you wish to set pagination for 100 records per page and exclude archived UTA records:
othersettings: {"recordsperpage":100,"includearchive":0}

Hourly API Call Limit

API calls exceeding 1,000 per instance within the past hour will result in an error and will be blocked from using the API until the total number of API calls in the last hour falls below the specified limit.

SmartConnect Examples

Please refer to our interactive demonstration page for a demonstration and live sample of the API functionality. This page is connected to a specific demonstration instance containing sample data.

We highly recommend reviewing this page to enhance your understanding of the syntax and functionality of the API.