Changes

SmartSimple's SmartConnect * This API provides uses industry standard JSON syntax and constructs. If you are not familiar with JSON you should take a relatively easy 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 use method export and import large amounts of integrating SmartSimple information with other web services and systemsthen this API should not be used.

* This API uses industry standard JSON syntax and constructs. If you are does not familiar with JSON you should take a look at place metering restrictions as to the [https://www.w3schools.com/js/js_json_intro.asp following tutorial] before venturing much further in this topic. ==Interactive Demonstration Page== For number of records that can be retrieved by a demo of how the single API works, you can test some sample functions on our [https://api.smartsimple.com/devtools/dev_api.html interactive demonstration page]query. This page is connected to   However retrieving a specific demonstration instance containing sample data. We strongly encourage you to review this page in order to gain large number of records (greater than 1000 records) will have a better understanding of the syntax negative impact on performance and functionality of may cause the APIquery to fail. 

* '''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. [[File:Access_type_API.png|thumb|none|middle|200px|Roles and access setting of a user to be used for remote calls.]]

# In this screen you will find options for ''Object 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.

Here is a more detailed look at [[Creating JSON functionsSmartConnect Functions|creating SmartConnect functions]].

!| 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

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

!| Object Record Type!| Endpoint!| Example

|| Report|| /API/1/report/| |<nowiki>https://example.smartsimple.com/API/1/report/</nowiki>

|| Company|| /API/1/company/| |<nowiki>https://example.smartsimple.com/API/1/company/</nowiki>

|| User|| /API/1/user/| |<nowiki>https://example.smartsimple.com/API/1/user/</nowiki>

|| System Variables| |/API/1/sysvar/| |<nowiki>https://example.smartsimple.com/API/1/sysvar/</nowiki>

|| UTA Level 1|| /API/1/levelone/| |<nowiki>https://example.smartsimple.com/API/1/levelone/</nowiki>

|| UTA Level 2|| /API/1/leveltwo/| https|<nowiki>tps://example.smartsimple.com/API/1/leveltwo/</nowiki>

|| UTA Level 3|| /API/1/levelthree/| |<nowiki>https://example.smartsimple.com/API/1/levelthree/</nowiki>

|| UTA Level Transaction| |/API/1/transactions/| |<nowiki>https://example.smartsimple.com/API/1/transactions/</nowiki>

The message body that At minimum, you post will always need to include various the following parameters depending on the : * ''Object Type'url' and ''Action Type'' being used. The required and optional parameters will be listed for each different function on : String containing the configuration page of each SmartConnect function. At minimum though, you will always need URL to include:which the request is sent* '''urlapitoken''': The URL to post  Encrypted token generated and associated toeach SmartConnect function.* '''apitokenjsonrset'''(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 generated for that record (e.g. userid for a user/contact record), and must include every field and associated to each 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.

* '''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 <nowiki>https://example.smartsimple.com </nowiki> the alias would be 'example'.

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

=Configuration ===Using List Functions====<!--66823 - SmartConnect grouping criteria- Advanced-><!--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: * 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 [[User|users]] that are able to see any reports thru the API Function are [[User|users]] with the '''[[Manager Permission – Reports and Dashboards|Manager permission]]''' – '''reports'''. <br/>Please make sure that the role of the active SmartSimple user account has the permission to view the reports. <br/>Here is the link on how to allow reports to be shared with [[User|users]] in the API Report Function: [[Sharing_Reports_with_People_-_Overview|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. 

<!=Configuration -Advanced==Appendix===Standard Field Names==See [[SmartConnect -Explain Appendix: Standard Field Names|SmartConnect Standard Field Names]] for a list of all applicable misc options and settings available Standard Fields that shouldn't be explained above hereyou can reference along with update restrictions...-->

!|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.

<!--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 object typesrecord types. 

!| GetAction!| Retrieve a single record for the record type you have selected in the function.Description

| List|Get|| Retrieve multiple records a single record for the record type you have selected in the function.

| Update|List| Update one or more fields |Retrieve multiple records for the specified record/s. Update is also used to create new recordstype you have selected in the function.

| Get Meta|Update| Retrieve |Update one or more fields for the configuration settings for a UTA with respect specified record/s. Update is also used to Level 1/2/3 attributes such as types, statuses, field definitionscreate new records.

| Update |Get Meta| Update |Retrieve the configuration settings for a UTA with respect to Level 1/2/3 attributes such as types, statuses, field definitions.

| Download File|Update Meta| Download a single file from |Update the configuration settings for a specified record and UTA with respect to Level 1/2/3 attributes such as types, statuses, fielddefinitions.

| List Files|Download File| Retrieves |Download a list of files single file from a specified record and field. 

| Search |List Files| Retrieve |Retrieves a list of files containing from a specified string valuesrecord and field.

| Update Associations|Search Files| Update one or more fields |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 association table between two recordsapi call. Update is also used to create new association records. E.g. The contacts or organizations associated to a UTA Level 1 recordSee [[Indexing Multiple and Single File Fields|Indexing Multiple and Single File fields.]]

| List |Update Associations| Retrieves a list of associations for |Update one or more fields in the specified recordassociation 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 Multiple AddressesAssociations|| Retrieves a list of addresses associations for the specified contact record. E.g. The contacts or organization 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".

'''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=See our [https://api.smartsimple.com/devtools/api.html 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 Sample Code|API examples]] for a sample list of SmartConnect calls.