Open main menu

SmartConnect - RESTful API

(Redirected from JSON API (SmartConnect))

Contents

Overview

SmartSimple's SmartConnect API provides a relatively easy to use method of integrating SmartSimple information with other web services and systems. It is a RESTful API and loosely follows the principles of REST integration.

  • This API uses industry standard JSON syntax and constructs. If you are not familiar with JSON you should take a look at the following tutorial before venturing much further in this topic.
  • If you wish to export and import large amounts of information then this API should not be used.
  • This API does not place metering restrictions as to the number of records that can be retrieved by a single API query.  However retrieving a large number of records (greater than 1000 records) will have a negative impact on performance and may cause the query to fail. 

Prerequisites

  • This API is only available for SmartSimple environments on the November 2015 release or later. We recommend you upgrade to the latest available release for the most up to date API functionality.

Configuration - Essentials

Initial Setup

You will need an active SmartSimple user account in order to make any API calls. There are two modes of operation for this API, and if you are planning on making remote calls you will first need to create and activate an API type user.

  • Active session: Where a user is already logged into SmartSimple with an active session and makes an API call from their web browser, e.g. an AJAX call. The user's existing session is used to authenticate the API call.
  • Remote call: Where an external system makes an API call. For this method, a user account of type API Access is required to authenticate the API call.
    Roles and access setting of a user to be used for remote calls.

Function Definition

In order to use the API, you must first define the set of functions you wish to make available within SmartSimple. This is an added layer of security that lets you limit the available functions as well as field sets that you wish to expose through the API.

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

Here is a more detailed look at creating SmartConnect functions.

Field List Syntax

The Field List option within the function configuration is used to define which fields are retrievable through the function call. This is a free form text box in which you will need to construct your field list with the following syntax:

Syntax Description Example
sf_StandardFieldName

Standard fields are denoted by their name, preceded by a prefix of 'sf_'.

See Appendix for a list of Standard Field names for each object.

sf_First Name

cf_CustomFieldName

cf_CustomFieldID

Custom fields are denoted by their field name, preceded by a prefix of 'cf_'.

While it is best practice to reference the field name, you may also reference the field ID.

cf_My Custom Field

cf_12345

;; Field Separator. Multiple fields are separated using the literal characters ';;' sf_First Name;;cf_My Custom Field

Usage

Make sure that SmartConnect API functions were created in the instance before proceeding to using the API.

Posting Endpoints

To make an API call you will need to post to the appropriate endpoint which will simply be based on the Record Type of the API function. The general endpoint will be in the form of: 

/API/APIVersion/recordtype/

The full list of endpoints is below.

Record 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 Level 1 /API/1/levelone/ https://example.smartsimple.com/API/1/levelone/
UTA Level 2 /API/1/leveltwo/ tps://example.smartsimple.com/API/1/leveltwo/
UTA Level 3 /API/1/levelthree/ https://example.smartsimple.com/API/1/levelthree/
UTA Level Transaction /API/1/transactions/ https://example.smartsimple.com/API/1/transactions/

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

Message Body

The message body that you post will need to include various parameters depending on the Record Type and Action Type being used. The required and optional parameters will be listed for each different function on the configuration page of each SmartConnect function.

At minimum, you will always need to include the following parameters:

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

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

  • username: The email address of an active API type user account.
  • password: The corresponding password to the above user account.
  • companyid: The root companyid of your SmartSimple instance. This is the companyid of the organization at the root of your instance.
  • alias: The web alias of your SmartSimple instance. This will typically be the leading portion of your instance URL, and can be found in your Global Settings -> Branding configuration. E.g. 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

With every successful request an HTTP status of 200 is returned along with a JSON response body that contains the recordset. 

Sample response format for GET/LIST call based on 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 creation, the response body will simply return the recordid and a status of "Updated Successfully". 

Sample response format for UPDATE call:<br />
{
   "records":[
      {
         "recordid":"6048788",
         "recordindex":1,
         "status":"updated successfully"
      }
   ],
   "message":{

   }
}

Important Notes

Using Update Functions

Here are some important notes to be aware of when calling update functions.

  • Date field values should be written in the format of YYYY-MM-DD.
  • Field types with pre-defined options, e.g. Select One, and Select Many type fields, need to be set with their stored value options, rather than their display captions. For example, a field where you have defined options like "1=Yes;2=No" needs to be set by the values "1" or "2".
  • The update functions can also be used to create new records. This can be done by setting the recordid to 0. The response will then return the recordid of the new record created.

Update Behaviour

Please note when performing updates that the system behaviour will be similar to that of saving the record in the regular browser interface. Namely, the following will occur:

  • Any existing and applicable template formulas will be triggered and run after a record update.
  • Any existing and applicable workflows will be triggered and run after a record update.
  • Any existing and applicable status-triggers will run for any status change after a record update.

Using List Functions

  • The number of records returned by a single SmartSimple API call is capped to 10000 records. If the criteria of your API call matches more than 10000 records, you will need to leverage the pagination parameters in order to make multiple calls to page through the results and return the full data set.

Custom parameters for List Functions are:

  • criteria - this is an optional json array. This contains the following nodes: "andor", "field", "operator" and "value"
Values of each nodes:
"andor" - either "and" or "or"
"field" - name of the standard/custom field to set the condition to
"operator" - can use the following: =,>,>=,<=,<,<>,!=,like,not like
"value" - value for the filter
sample1:
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"}
sample2:
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"}
sample3:
An example query with brackets: ( (cf_somefield1 like '%whatever%' or cf_somefield2 like  '%whatever%'  or cf_somefield3 like  '%whatever%'  or cf_somefield4like  '%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 - this is an optional json array. This contains the following nodes: "field" and "direction"
"field" - name of the standard/custom field to sort records by
"direction" - either "asc" (for ascending) or "desc" (for descending)
  • othersettings
    • getstorevalue - this is an optional settings for the json array. Options are: int type: 0 - to get display value, 1 to get stored value (value from the database eg. $25,000 vs 25000)
    • keyformat - this is an optional settings for the json array. Options are: 0 - to use what is configured in the Field List form the SmartConnect Function, 1 - to use the custom field names / standard field names and 2 - to use the custom field ID

Report Permission using API Report Function

By default, the users that are able to see any reports thru the API Function are users with the Manager permission – reports.
Please make sure that the role of the active SmartSimple user account has the permission to view the reports.
Here is the link on how to allow reports to be shared with users in the API Report Function: Sharing Reports with People

Error Messages

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

The most common case is HTTP 401 Unauthorized which could indicate one of the following:

  • Invalid authentication credentials provided.
  • User Account type is not of "API User".
  • If performing remote calls, make sure the companyid parameter is correct.

If the request is successful and the response is blank, review the following troubleshooting steps:

  • Ensure the apitoken parameter is correct.
  • If updating, ensure the recordid is correct.
  • Ensure the post endpoint URL is pointing to the correct resource.


Error and status messages vary from different API calls and are based on the records in the API calls. 

Other generic error messages on failed API request:

"Invalid API Token"
"Number of API Calls within the hour have reached the maximum limit, please try again later"
"Invalid URL: URL should start with https://."
"Invalid API Request, request is empty or null"
"Encountered error while processing other setting parameters"
"Encountered error while processing record"
"Encountered error while processing list"
"Recordset does not exist"
"Requested record does not exist"
"No records"
"SmartConnect API function configuration error, association type missing from Field List of 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"
"Requested field does not match with the object type"
"Requested field not found"
"Requested list does not have field list defined"
"You do not have permission to view this report."
"Search keywords can not be empty"

Configuration - Advanced

API User Access Tokens

You can use user access tokens for authentication instead of providing username + password in your API call. To create user access tokens for API users, got to SmartConnect API - API Users (tab), click into an API user in the list and click the Generate New Token button.

Generate user access token for API user.


Use the token in Authorization header as: Bearer xxxxxxxxxxxx in your API call. This will replace the username and password in your API call.

Example call in Postman.

Appendix

Standard Field Names

See SmartConnect Standard Field Names for a list of all available Standard Fields that you can reference along with update restrictions.

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

Options and Settings

Available Record Types

Record Description
Report Run a report and retrieve the results.
Company Organization records.
User Contact records.
System Variables Global System Variables.
UTA Records UTA records, including Level 1, 2, 3, and transactions.

Available Action Types

The following is a full list of available actions. Please note that not all actions will be available for all record types.

Action Description
Get Retrieve a single record for the record type you have selected in the function.
List Retrieve multiple records for the record type you have selected in the function.
Update Update one or more fields for the specified record/s. Update is also used to create new records.
Get Meta Retrieve the configuration settings for a UTA with respect to Level 1/2/3 attributes such as types, statuses, field definitions.
Update Meta Update the configuration settings for a UTA with respect to Level 1/2/3 attributes such as types, statuses, field definitions.
Download File Download a single file from a specified record and field. 
List Files Retrieves 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 the file contents. Upload fields searched are restricted based on the field list specified in the api call. See Indexing Multiple and Single File fields.
Update Associations Update one or more fields in the association table between two records. Update is also used to create new association records. E.g. The contacts or organizations associated to a UTA Level 1 record.
List Associations Retrieves a list of associations for the specified record. E.g. The contacts or organizations associated to a UTA Level 1 record.
List Multiple Addresses Retrieves 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. Update is also used to create new address records.
Variables Replace Returns formatted content processed by the variable processor from a specified record.  The system will replace all variables within the content parameter with variable values from that record.  E.g. Passing in "Hello @firstname@" as content for a contact named John Smith will return "Hello John".

Pagination

4 new parameters are introduced and should be put inside the "othersettings" in json object for the API call
- recordstart, recordend, recordsperpage, pagenum
*Note: othersettings parameter is also used for other settings introduced earlier, ie. getstorevalue and keyformat, so your othersettings json can look something like this:
{"getstorevalue":"1","keyformat":"1","recordsperpage":100,"recordstart":1000}

Note: only up to 10000 records will be returned for each API call, so multiple API calls will be required to display all records with respective pagination parameters

Returned json response will include the following (in the message json node) for all records, despite the above parameters have been set or not, results are based on the order by (sortby declared in API call or by default order by, eg. order by L1 ID asc):
- recordfrom (starts from record number xxx)
- recordto (last record number returned xxx)
- recordcount (number of records returned in this API call)
- allcount (number of records in total without the limit)
Returned Response:
e.g. "message":{"recordto":424,"recordcount":100,"allcount":460,"recordfrom":325}

Priority of operations with the 4 new parameters:
1. when recordend > 0, only recordstart and recordend parameter will be taken into consideration, eg.
othersettings: {"recordend":35} - will return records from start up to and including 35th record, total records = 35
othersettings: {"recordstart":10,"recordend":35} - will return 10th to 35th record, total records = 26
othersettings: {"recordstart":10,"recordend":350,"recordsperpage":100} - will ignore recordsperpage because you have specified the start and end, return record 10 to 350, total 341 records


2. pagenum > 0 and recordsperpage > 0, (to use pagenum, recordsperpage has be to specified), will ignore recordstart and recordend
othersettings: {"recordsperpage":50,"pagenum":2} - return records 51-100
othersettings: {"recordsperpage":100,"recordstart":12,"pagenum":1} - will ignore recordstart, return records 1-100
othersettings: {"recordsperpage":100,"recordstart":12,"pagenum":3} - will ignore recordstart, return records 201-300


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


4. recordstart > 0
othersettings: {"recordstart":12}, return all records starting from record 12, up to only 10000 number of records


Searching of Empty or Non-empty Values

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

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


Exclude (or include) archived UTA Records

New parameters introduced to exclude archived UTA records and should be put inside the "othersettings" in json object for the API call
includearchive - if you don't put this node or use {"includearchive":1} , it will include everything in the search, to exclude archived records, set the parameter to 0
e.g. if you want to set pagination for 100 per page and exclude archived UTA records:
othersettings: {"recordsperpage":100,"includearchive":0}


Hourly API Call Limit

API calls in excess of 1000 per instance within the past hour will receive an error and blocked from using API until the total API calls count in the last hour drops below the limit.

SmartConnect Examples

See our interactive demonstration page for a demo and live sample of how the API works. This page is connected to a specific demonstration instance containing sample data.

We strongly encourage you to review this page in order to gain a better understanding of the syntax and functionality of the API.

See API examples for a sample list of SmartConnect calls.

Retrieved from ‘https://wiki.smartsimple.com/index.php?title=SmartConnect_-_RESTful_API&oldid=43124’
Last modified on 20 August 2024, at 11:20