Smartstaff
124
edits
Changes
→API User Access Tokens
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 [https://www.w3schools.com/js/js_json_intro.asp 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=
||<nowiki>https://example.smartsimple.com/API/1/transactions/</nowiki>
|}
<!--1136148 - SmartConnect API version 2-->
As of August 2022 upgrade, APIVersion=2 is now available. This version has standardized syntax and format of requests and responses.
===Message Body===
====Using List Functions====
<!--66823 - SmartConnect grouping criteria-->
<!--75675 - SmartConnect field name and format consistency-->
* 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:
: "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 = no (''' - to get display value), '''1 = yes (''' 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====
* 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"<br />"Number of API Calls within the hour have reached the maximum limit, please try again later"<br />"Invalid URL: URL should start with https://."<br />"Invalid API Request, request is empty or null"<br />"Encountered error while processing other setting parameters"<br />"Encountered error while processing record"<br />"Encountered error while processing list"<br />"Recordset does not exist"<br />"Requested record does not exist"<br />"No records"<br />"SmartConnect API function configuration error, association type missing from Field List of function"<br />"Invalid record id"<br />"No content or empty content argument provided."<br />"No objectid argument provided."<br />"No object type argument provided."<br />"Consumer Provider link not configured in SmartConnect API settings"<br />"Requested field does not match with the object type"<br />"Requested field not found"<br />"Requested list does not have field list defined"<br />"You do not have permission to view this report."<br />"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.
[[File:GenerateUserToken.png|thumb|none|1300px|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.
[[File:BearerUserToken.png|thumb|none|1000px|Example call in Postman.]]
=Appendix=
==Standard Field Names==
===Available Action Types===
<!--89304 - SmartConnect 'Update Meta' - should be removed from dropdown-->
The following is a full list of available actions. Please note that not all actions will be available for all record types.
{| class="wikitable"
|-
||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<br />-''' recordstart, recordend, recordsperpage, pagenum'''<br />*Note: othersettings parameter is also used for other settings introduced earlier, ie. getstorevalue and keyformat, so your othersettings json can look something like this:<br />{"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'''<br /><br />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):<br />- '''recordfrom''' (starts from record number xxx)<br />- '''recordto''' (last record number returned xxx)<br />- '''recordcount''' (number of records returned in this API call)<br />- '''allcount''' (number of records in total without the limit)<br />Returned Response:<br />e.g. "message":{"recordto":424,"recordcount":100,"allcount":460,"recordfrom":325}<br /><br />Priority of operations with the 4 new parameters:<br />1. when recordend > 0, only recordstart and recordend parameter will be taken into consideration, eg.<br />othersettings: {"recordend":35} - will return records from start up to and including 35th record, total records = 35<br />othersettings: {"recordstart":10,"recordend":35} - will return 10th to 35th record, total records = 26<br />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
<br />2. pagenum > 0 and recordsperpage > 0, (to use pagenum, recordsperpage has be to specified), will ignore recordstart and recordend<br />othersettings: {"recordsperpage":50,"pagenum":2} - return records 51-100<br />othersettings: {"recordsperpage":100,"recordstart":12,"pagenum":1} - will ignore recordstart, return records 1-100<br />othersettings: {"recordsperpage":100,"recordstart":12,"pagenum":3} - will ignore recordstart, return records 201-300
<br />3. recordsperpage > 0<br />othersettings: {"recordsperpage":100} - return record 1 to 100<br />othersettings: {"recordsperpage":100,"recordstart":1} - return record 1 to 100<br />othersettings: {"recordsperpage":100,"recordstart":101} - return record 101 to 200<br />othersettings: {"recordsperpage":100,"recordstart":325} - return record 325 to 424
<br />4. recordstart > 0<br />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"}]
===Hourly API Call Limit===
<!--125991 - Throttle API calls-->
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=