SmartSYNC: Real-time API security and requests

SmartSYNC: Real-time API security and requests

SmartSYNC provides an API interface to run data flows in real-time and return the results to an external system.

Using the API

Enabling the API

To enable the API you need to go to the Admin > Account page within your SmartSYNC account. Toggle the API Access > Enable? checkbox to be ticked.

You will also see your API Key and Secret on this page, please note those for future reference. You will use them to secure your requests.

Making a simple GET request

There will be cases where you will wish to run the data flow in SmartSYNC without passing in any further information. Examples could be that you have changed data in an external system and want SmartSYNC to check immediately for the change. To send such a request you need the Flow ID which you can find on the Flows page under the flow (Flow ID: ...):


You will then construct the request as a URL:
  1. https://[domain_of_your_SmartSYNC_installation]/apis/execute.php?flow=69&key=...&ts=9348579834&check=...
  2. i.e. https://smartsync.org/apis/execute.php?flow=69&key=sdfjh435hh345454&ts=9348579834&check=f9094fca352acbf08fac376875f445fb
In this URL there are could of arguments to note:
  1. ts: the current timestamp (number of seconds since midnight on the 1 Jan 1970)
  2. key: your API Key (found in the Admin > Account page in your SmartSYNC account)
  3. check: a checksum to secure your request.
    1. Sort your request parameters in alphabetical order (but exclude check) i.e. flow, key, ts
    2. Make a string from the parameter values in this same sorted order separated by '|' i.e. 69|sdfjh435hh345454|9348579834
    3. Append your API Secret after another '|' character (found in the Admin > Account page in your SmartSYNC account) i.e. 69|sdfjh435hh345454|9348579834|dfhfdjsghs
    4. Take the MD5 value of this string and supply it as the check value so md5('69|sdfjh435hh345454|9348579834|dfhfdjsghs') i.e. f9094fca352acbf08fac376875f445fb

Making a POST request (with data)

Most of the time you use the API you will want to supply data to the SmartSYNC flow. To enable this your flow must start with a compatible event i.e. a Webhook > Incoming Webhook event step with default settings. 

You will send data as JSON content (application/json content type) within the body of the POST request. You will also include the post body in your md5 calculation when creating the 'check' argument for your request by appending it before step 3 of the above check calculation. In the above example this would mean check would be the value of: md5('69|sdfjh435hh345454|9348579834|[YOUR JSON]|dfhfdjsghs') 

Returned data

The data returned is also in JSON format. The response code will indicate the status:
  1. 200: Successful run
  2. 400: Error occurred during run
  3. 500: An unexpected server error
The returned data will provide further information:
  1. success: true/false
  2. error:
    1. code: the response code
    2. msg: details of the error
  3. output: array of return objects (output of final step of flow)

Example:

{
  "success": true,
  "output": [
    {
      "id": "280",
      "address": {
        "id": "757",
        "address_lines": "410 17th Street",
        "city": "Denver",
        "constituent_id": "280",
        "country": "United States",
        "county": "Denver",
        "do_not_mail": false,
        "formatted_address": "410 17th Street\r\nDenver, CO  80202-4402",
        "postal_code": "80202-4402",
        "preferred": true,
        "state": "CO",
        "type": "Home"
      },
      "age": 54,
      "birthdate": {
        "d": 14,
        "m": 3,
        "y": 1961
      },
      "date_added": "1999-05-20T18:57:55Z",
      "date_modified": "2016-07-14T04:13:51.2167803Z",
      "deceased": false,
      "email": {
        "id": "283",
        "address": "robertcarloshernandez@gmail.com",
        "do_not_email": false,
        "inactive": false,
        "primary": false,
        "type": "Email"
      },
      "first": "Robert",
      "fundraiser_status": "Active",
      "gender": "Male",
      "gives_anonymously": false,
      "inactive": false,
      "is_constituent": true,
      "last": "Hernandez",
      "lookup_id": "96",
      "middle": "Carlos",
      "name": "Dr. Robert C. Hernandez",
      "online_presence": {
        "id": "811",
        "inactive": false,
        "primary": false,
        "type": "Web address"
      },
      "phone": {
        "id": "95",
        "do_not_call": false,
        "inactive": false,
        "number": "(303)-997-3301",
        "primary": false,
        "type": "Home"
      },
      "preferred_name": "Bob",
      "spouse": {
        "id": "410",
        "first": "Wendy",
        "last": "Hernandez",
        "is_head_of_household": false
      },
      "title": "Dr.",
      "type": "Individual",
      "import_id": "1234-56-789101"
    }
  ]
}

Notes

  1. Execution time is limited to 60 seconds. To use this fully though you may need to ensure your calling system does not timeout by extending the timeout settings on the GET or POST request.
  2. If an error occurs examine the returned 'error' object to find details
  3. The output is an array as you may have more than one output from the final step
  4. When calculating a POST based checksum ensure the JSON has any leading or trailing whitespace and ALL return and newline characters removed
  5. The SmartSYNC flow used does not need to be enabled within SmartSYNC. This allows you to have the flow run ONLY when called via the API


    • Related Articles

    • SmartSYNC: Zoom application set-up

      To connect your Zoom account to SmartSYNC you need to set up your own Zoom application. This is a fairly easy process which we guide you through below. Step 1. Create an application We will create an application and then, for our SmartZOOM product, ...

    • SmartSYNC: Remember, it's a transactional sync...

      One way loop protection SmartSYNC has built in loop protection to prevent changes in one system bouncing back and forward - it puts a 1 hour block to ensure data only flows one way after a change is made. So if you have a flow from Raiser's Edge to ...

    • SmartSYNC: Connecting SalesForce

      Salesforce provide very robust API services to allow SmartSYNC to work with data held within their systems. Within SmartSYNC you can create a new app connection to Salesforce but require a couple of settings to allow this connection. Instructions ...

    • SmartSYNC: iSAMS Pupil monitoring system

      SmartSYNC allows you to monitor iSAMS for new and graduating pupils along with their applicant address. We also monitor their registered parents and their contact addresses. To achieve this you need to register for a new API Key. A brief outline of ...

    • SmartSYNC: Using a tenant app with Dynamics, Outlook, Excel and other Microsoft app connectors

      When creating connections to Microsoft products your IT environment admins may have restricted access to only locally created client apps. These are referred to as single tenant apps. This is not an issue as we can create an app for your environment ...