As an API first platform Syntaq Falcon platform offers developer teams a full suite of endpoints. This can be overwhelming when you first get started.

In this 10-minute introduction to integrating with SYNTAQ Falcon we will walk through authentication and authorisation and integrating Syntaq Forms and Documents into a Host Web platform.

Including:

Loading a List of Forms;
Selecting and Loading a Form;
Prefilling a form with data from the Host site;
Filling and submitting a Form; and
Configuring a webhook to receive notification when a document is completed; and
Saving an assembled document to the Host or external system.

Getting Started

To get started you will need to have a Tenant account with SYNTAQ, if you don't have one simply email help@syntaq.com and we can establish one for you.

With the account established you will need to make a couple of decisions. First of all, you will need to decide if:

You would like to manage and access data, forms and workflow from a single account i.e. a Service Account; or
You would like each user to have access to their own personal data, i.e. a Personal Account.

This is an important question because this will determine the best process for managing authorisation and authentication.

Create a Form

Have a look at our Forms articles here to help you get started with the creation of simple forms and how to share those forms with your users.

Authorisation and Authentication

Login method

This method will prompt the user to login using a username and password modal. This would be required for the Personal Account approach.

Auth Token

This is a user authentication token that can be set and is passed in the Authorization Bearer header when making requests. This means that when using this token the user is set as ‘logged on’. You will need this for both the Personal and Service Account approach.

Anon Token

Syntaq.Form.AnonAuthToken

This token is used by the system when there is no user context (user not logged in). This token is returned when a record is first saved. It is a token stored with the record and when passed can be used to access the record for anonymous edit/update etc.

For the purposes of this article we will be working through the implementation of a Service Account which has 2 users:

admin: this user account will be used to build forms, document templates and workflows. This account will have full permissions. Any forms or workflow created in this account will be shared to the public user.
public: this user account will have limited permissions, only allowing it to view and save/submit forms shared with them only. The public account will have limited permissions.

This would be classed as a Service to Service Integration.

Generating an Access Token for API Access

Syntaq dev team will be working on an improved Service to Service api, adopting OAuth2 principals. For now though, the following process is required.

The Access token is required when making API calls and is set in the Authorization Bearer header.

Logon to your Tenant Account as an admin,
Navigate to https://[TenancyName].syntaq.com/swagger/index.html, (where [TenancyName] should be replaced by the name of your tenancy)
Find the /api/TokenAuth/Authenticate method,
Click ‘Try it Out’,
Alter the JSON payload, enter the user name and password of the public user. The other parameters can be removed. Note, if you have two factor authentication turned on this will not work.
Click ‘Execute’,
Take note of the response. It should include the access token and the refresh token.
Access tokens are valid for 30 days, with the refresh token being be used to refresh the access token after its expiry. Refresh tokens have a 1 year expiry.

Using an online service like - https://jwt.io/ you can decode the token, which will contain the following pieces of information:

username
email address
role
tenant id
user id
expiry date, created as a number in seconds.

Now that we have successfully generated the Access token and authenticated a user, lets pull the list of available forms for the user.

Displaying a list of Forms to users in the Host System

The first step is to add some html to your webpage to allow Syntaq Forms to render on the page. To do this simply create a web page in the Host system with the prerequisites below.
- You will need to load both your tenancy css and jQuery 3.0.0 or higher, for forms to appear and run correctly
- The syntaq.js file is the core Syntaq JavaScript file that simplifies integration with the Syntaq API, and must also be present
- The ‘syntaq-content’ div is a default element where Syntaq content is loaded, you can replace this with your own element by setting the Syntaq.Form.ElementId property to your preferred options
- Remember to swap in your tenancy name
```
<link href="https://[tenancyname].syntaq.com/assets/syntaq/syntaq.bootstrap.min.css"type="text/css"rel="stylesheet">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<script id="syntaq-script"src="https://[tenancyname].syntaq.com/assets/Syntaq/Syntaq.js"></script>
<div id="syntaq-content"></div>
```

The next step is to create some UI to allow the user to select which form to load

Use the sample JavaScript below to return a list of Syntaq Forms. Then use the JSON response to build a UI for the user to select and load the Form. You can substitute any REST based script here to connect to the API. This API method will return a JSON response containing a list of Forms available to the user.

var xhttp = new XMLHttpRequest();   

xhttp.responseType = 'json';   
xhttp.onreadystatechange = function () {     
  if (this.readyState === 4 && this.status === 200) {              
    var jsonResponse = xhttp.response;              
    // Custom code here to load the JSON result into a table on the Host Site              
    // Code should build a list of forms similar to below example              
    // This example button uses the function from Loading Forms in the Host Website
    // <button type='button' onclick='loadForm(formId)'>Load Form ABC..</button>     
  }   
};   

xhttp.open("GET", 'https://[tenancyname].syntaq.com/api/services/app/Forms/GetAll');   
xhttp.setRequestHeader("Authorization", "Bearer [AuthToken]");

Use this response to build a UI for the user to select the forms from.

Each form displayed in the list should include a function that calls the ’loadForm(formId)' function (as shown in the Loading Form step, further below), and present the Form name to the user.
Optionally, you can also provide a folder ID. When you provide a folder ID you will only get a list of forms from that folder. Without a folder ID you will get a list of all forms accessible to the user whose Auth Token you have used in the header. In our example this is the public user's forms.

The input DTO below can be used to filter the Form/GetAll method.

string Filter      
string Id      
string Type      
string DescriptionFilter      
int DocPDFFilter      
int DocUserCanSaveFilter      
int DocWordFilter      
int DocWordPaidFilter      
string NameFilter      
decimal? MaxPaymentAmountFilter      
decimal? MinPaymentAmountFilter      
string PaymentCurrFilter      
int PaymentEnabledFilter      
string FormsFolderNameFilter      
Guid FormsFolderId

Example of the JSON response

{
"items": [      
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"description": "string",
"version": 0,
"currentVersion": 0,
"originalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"lastModified": "2023-01-20T00:48:38.863Z",
"type": "string",
"userACLPermission": "string",
"enabled": true,
"accepted": true,
"tenancyName": "string",
"shared": true      
}     
],
"totalCount": 0     
}

Loading Forms in the Host Website

To load the form into the page at Step 2 of the Display Forms stage (above), you will need to call the Syntaq.Form.createForm function provided by the Syntaq.js library. The only required parameter is the formId. You can configure a number of parameters that control how the user is required to log in, which version of the form is loaded, which record to load (if any). However, only the uncommented lines in the below example are required.

loadForm = function (formid) {              
  Syntaq.TenantName = '[TenantName]';              
  // Syntaq.Form.Anonymous = true; // Default: false
  Syntaq.Form.FormId = formid;
  Syntaq.Form.Version = 'Live';
  // Syntaq.Form.ShowProgressTicks = true; // Default: false
  // Syntaq.Form.ElementId = '[ElementId]'; // Default: syntaq-content         
  Syntaq.Form.createForm();
}

Below is a full list of Syntaq.Form parameters. These can be added to the above function, should you need them.

AnonAuthToken: '',
Anonymous: false,     
ElementId: 'syntaq-content',     
FormId: null,     
FormName: 'Form name not set',     
Version: null,     
HasDocuments: false,     
FormData: null,     
FormType: 'default',     
PopName: null,     
PopKey: null,     
PopRequired: null,     
RecordId: null,     
LoadFromRecord: false,     
RecordMatterId: null,     
RecordMatterItemId: null,     
SubmissionId: null,     
ShowSubmissionDialog: true,     
IsPaid: false,     
Schema: '',     
ShowProgressTicks: true,     
ShowProgressElement: ' <i class="fa fa-check pull-right syntaq-ticks"></i>',     
ShowProgressClass: '',     
SummaryViews: [],     
SummaryView: '',     
ImportantViews: [],     
ImportantView: '',     
SubmitFunction: null,        
SaveFunction: null,        
ProjectId: null,        
ContinueSession: false,

Integrate data from the Host Site

If you have data available to logged in users of your Host site, you can have that data pre-populate into selected form fields using an on-load system function in your Syntaq Form.

Using the Syntaq Form custom script editor, you can query data from your Host platform and inject into the Syntaq formdata. To view the Script editor:

open the form in build mode
then select Script Editor from the from ‘Logic’ button In the toolbar.

You can learn more about adding data on Form Load here, or other system events here.

// Returns form data from Host Site     
window.InitFormData = function(formdata) {              
  // Call each Host AJAX query here and modify Syntaq Form Data                 
  formdata.FieldABC = “Hello World” // result of Host data query            
  return formdata;     
};

Using the Document Creation Webhook

When a user submits a Form, the developer can subscribe to a webhook on completion of a Document assembly.

To subscribe to a webhook event navigate to Administration > Webhook Subscriptions.

Click on + Add New Webhook Subscription.
Add your Webhook Endpoint
Select the Webhook event you want to subscribe to. Currently this is limited to App.DocumentGenerated.
Set the Additional Webhook Headers key and values.
Click Save.

You can read more about configuring the webhook here Webhooks

Save the Documents to your Host Site

Once you have been notified by the webhook that the documents are available for download, use the /api/services/app/RecordMatterItems/GetDocumentForDownload method to extract the file from your records and save it in your Host sites database.

The webhook will provide you with the document Id, and you will need to provide the format (pdf/ word) in which you want to save it. A logged in user won't need to authenticate again, but if you are not logged in you will need to provide the anonaccess token.

The input DTO below can be used to filter the /api/services/app/RecordMatterItems/GetDocumentForDownload method.

string Filter      
string Id      
string Type      
string DescriptionFilter      
int DocPDFFilter      
int DocUserCanSaveFilter      
int DocWordFilter      
int DocWordPaidFilter      
string NameFilter      
decimal? MaxPaymentAmountFilter      
decimal? MinPaymentAmountFilter      
string PaymentCurrFilter      
int PaymentEnabledFilter      
string FormsFolderNameFilter      
Guid FormsFolderId

FAQ's

Q: What is the best method to authorise a user to get access to a user account, form or data record?
Q: How do I get access to a folder ID for the root folders or forms, document templates and records?
Q: What is causing the CORS issues when I imbed the embed the form in my application
Q: When using the POST method, can a user see the auth token in my submission?
A: No. Form POSTS are encrypted by SSL.

Integrate with your Host Site and Data