Smartstaff, administrator
686
edits
Changes
no edit summary
# 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 functionsSmartConnect Functions|creating SmartConnect functions]].
===Field List Syntax===
||sf_First Name
|-
||cf_''CustomFieldName'' cf_''CustomFieldID''
||
Custom fields are denoted by their field name, preceded by a prefix of 'cf_'.
cf_My Custom Field
|-
==Usage==
Make sure [[Creating JSON functions|JSON sure that SmartConnect API functions]] were functions were created in the instance before you can use them. First, here are some rules proceeding to be aware of when calling using the API functions. * All update functions have a jsonrset parameter. When updating a record, the jsonrset must include all fields in the field list to ensure it works properly. If the value is not being changed, set it to the current value.* If updating a new field, that field must also be added to the field list within the function configuration.* Date fields in the jsonrset should be formatted as yyyy-mm-dd.* Fields with pre-defined options (eg. drop down, check box, etc.) can be set by giving the stored value of the desired option, not the display caption* The update functions are also used to create new records. This can be done by setting the recordid to 0. The response will then display the recordid of the record created.
===Posting Endpoints===
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 includethe 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:
* '''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]].
<pre>Sample call within SmartSimple instance:
}
</pre>
===POST Response===
With every successful request a an HTTP status of 200 is returned along with a JSON response body that contains the record field data. For record updates and creation, the response body will return the Record ID and a status of "Updated Successfully"recordset. <pre>Sample Response format for Update:<br />{ "records":[ { "recordid":"6048788", "recordindex":1, "status":"updated successfully" } ], "message":{ }}</pre>
<pre>Sample Response response format for GET/LIST call based on configured field list:
{
</pre>
===Important Notes===
* 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 status-triggers will run for any status change after a record update.
=Configuration - Advanced==Appendix==Error Messages=Creating SmartConnect functions==SmartConnect functions are created for each individual instance of For failed requests, SmartSimplereturns HTTP 4xx status codes. You can create multiple functions The most common case is HTTP 401 Unauthorized which could indicate one of the same action if neededfollowing: * Invalid authentication credentials provided.* User Account type is not of "API User".* If performing remote calls, depending on make sure the field list returnedcompanyid parameter is correct. If the request is successful and the response is blank, review the following troubleshooting steps:
=Configuration - Advanced=
=Appendix=
==Standard Field Names==
The standard fields available for reference varies on the Record Type selected in the API call.
==Options and Settings==
===Available Record Types===
{| class="wikitable"
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.
