Smartstaff, administrator
687
edits
Changes
Created page with "{{Banner-UnderConstruction}} =Overview= SmartSimple's SmartConnect API provides a relatively easy to use method of integrating SmartSimple information with other web servic..."
{{Banner-UnderConstruction}}
=Overview=
SmartSimple's SmartConnect API provides a relatively easy to use method of integrating SmartSimple information with other web services and systems.
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.
==Interactive Demonstration Page==
For a demo of how the API works, you can test some sample functions on our [https://api.smartsimple.com/devtools/dev_api.html interactive demonstration page]. 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.
=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. [[File:Access_type_API.png|thumb|none|middle|200px|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.
# Within your SmartSimple instance, define an API function within the Global Settings -> Integrations -> SmartConnect API screen.
# In this screen you will find options for ''Object 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.
# 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 JSON functions|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:
{| class="wikitable"
|-
!| Syntax
!| Description
!| Example
|-
| sf_''StandardFieldName''
| Standard fields are denoted by their name, preceded by a prefix of 'sf_'
| sf_First Name
|-
| cf_''CustomFieldName''
| Custom fields are denoted by their name, preceded by a prefix of 'cf_'
| cf_My Custom Field
|-
| ;;
| Field Separator. Multiple fields are separated using the literal characters ';;'
| sf_First Name;;cf_My Custom Field
|}
==Usage==
===Posting Endpoints===
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''/''objecttype''/
The full list of endpoints is below.
{| class="wikitable"
|-
!| 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
|
|
|-
| UTA Level 1
| /API/1/levelone/
| https://example.smartsimple.com/API/1/levelone/
|-
| UTA Level 2
| /API/1/leveltwo/
| https://example.smartsimple.com/API/1/leveltwo/
|-
| UTA Level 3
| /API/1/levelthree/
| https://example.smartsimple.com/API/1/levelthree/
|-
| UTA Level Transaction
|
|
|}
===Message Body===
The message body that you post will need to include various parameters depending on the ''Object 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 though, you will always need to include:
* '''url''': The URL to post to.
* '''apitoken''': The unique ID generated and associated to each SmartConnect function.
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'.
Here is a more detailed look at [[Using JSON functions|using SmartConnect functions]].
==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.
=Configuration - Advanced=
=Appendix=
==Options and Settings==
<!--Explain all applicable misc options and settings that shouldn't be explained above here...-->
===Available Object Types===
{| class="wikitable"
!| 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 object types.
{| class="wikitable"
!| 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 containing specified string values.
|-
| 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.
|}
=Examples=
<!--
Sample Image Format:
[[File:xmlSample.png|thumb|none|middle|500px|Example field configured as a budget sheet.]]
Sample Table Format:
{| class="wikitable"
| Option
| Description
| Example
|-
|
|
|
|}
Sample Syntax Format:
Empty space at start of line to highlight the row, italicize any variables that the user would fill in (as opposed to literal words that need to be used in syntax)
@section.''SectionNodeName''@
Sample Code Block:
When you want to write an example block of code, you should highlight it and also escape any special characters that might be construed as HTML formatting and outputted incorrectly by the Wiki by using a pre (pre-formatted text) tag
<pre>
<?xml version="1.0"?>
<Company>
<Name>Oranges Inc.</Name>
<Description>Peel.
Eat.
Repeat.</Description>
</Company>
<Company>
<Name>Bananas Ltd.</Name>
<Description>You're going to go "bananas" over our product!</Description>
</Company>
</pre>
-->
[[Category:Integration]][[Category:API]][[Category:SmartConnect RESTful API]]
=Overview=
SmartSimple's SmartConnect API provides a relatively easy to use method of integrating SmartSimple information with other web services and systems.
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.
==Interactive Demonstration Page==
For a demo of how the API works, you can test some sample functions on our [https://api.smartsimple.com/devtools/dev_api.html interactive demonstration page]. 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.
=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. [[File:Access_type_API.png|thumb|none|middle|200px|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.
# Within your SmartSimple instance, define an API function within the Global Settings -> Integrations -> SmartConnect API screen.
# In this screen you will find options for ''Object 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.
# 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 JSON functions|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:
{| class="wikitable"
|-
!| Syntax
!| Description
!| Example
|-
| sf_''StandardFieldName''
| Standard fields are denoted by their name, preceded by a prefix of 'sf_'
| sf_First Name
|-
| cf_''CustomFieldName''
| Custom fields are denoted by their name, preceded by a prefix of 'cf_'
| cf_My Custom Field
|-
| ;;
| Field Separator. Multiple fields are separated using the literal characters ';;'
| sf_First Name;;cf_My Custom Field
|}
==Usage==
===Posting Endpoints===
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''/''objecttype''/
The full list of endpoints is below.
{| class="wikitable"
|-
!| 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
|
|
|-
| UTA Level 1
| /API/1/levelone/
| https://example.smartsimple.com/API/1/levelone/
|-
| UTA Level 2
| /API/1/leveltwo/
| https://example.smartsimple.com/API/1/leveltwo/
|-
| UTA Level 3
| /API/1/levelthree/
| https://example.smartsimple.com/API/1/levelthree/
|-
| UTA Level Transaction
|
|
|}
===Message Body===
The message body that you post will need to include various parameters depending on the ''Object 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 though, you will always need to include:
* '''url''': The URL to post to.
* '''apitoken''': The unique ID generated and associated to each SmartConnect function.
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'.
Here is a more detailed look at [[Using JSON functions|using SmartConnect functions]].
==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.
=Configuration - Advanced=
=Appendix=
==Options and Settings==
<!--Explain all applicable misc options and settings that shouldn't be explained above here...-->
===Available Object Types===
{| class="wikitable"
!| 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 object types.
{| class="wikitable"
!| 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 containing specified string values.
|-
| 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.
|}
=Examples=
<!--
Sample Image Format:
[[File:xmlSample.png|thumb|none|middle|500px|Example field configured as a budget sheet.]]
Sample Table Format:
{| class="wikitable"
| Option
| Description
| Example
|-
|
|
|
|}
Sample Syntax Format:
Empty space at start of line to highlight the row, italicize any variables that the user would fill in (as opposed to literal words that need to be used in syntax)
@section.''SectionNodeName''@
Sample Code Block:
When you want to write an example block of code, you should highlight it and also escape any special characters that might be construed as HTML formatting and outputted incorrectly by the Wiki by using a pre (pre-formatted text) tag
<pre>
<?xml version="1.0"?>
<Company>
<Name>Oranges Inc.</Name>
<Description>Peel.
Eat.
Repeat.</Description>
</Company>
<Company>
<Name>Bananas Ltd.</Name>
<Description>You're going to go "bananas" over our product!</Description>
</Company>
</pre>
-->
[[Category:Integration]][[Category:API]][[Category:SmartConnect RESTful API]]