Complyfile is a secure web-based platform that assists an organisation in managing the legal requirements surrounding the on-boarding, and continued administration, of individuals that represent that organisation in a supervisory or public-orientated capacity. It is particularly suited to voluntary or charitable organisations that place their representatives in a supervisory capacity over young or vulnerable individuals.
The Complyfile platform is comprised of three distinct components:
This document outlines the purpose of the web service API component, provides an overview of the functions available and offers some suggestions on the types of service the API can offer to organisations that already subscribe to the Complyfile platform. The document does not include any information on the website or the database that supports the website and web service API.
The document is intended for individuals with a technical understanding of IT systems, and in particular those with a knowledge of integrating disparate systems using web services, but does not provide sufficient information to allow developers to integrate with the API. Information for developers wishing to use the services provided by the API is provided in our systems integration guide.
The following diagram outlines the structure of the Complyfile platform, indicating the use and interoperability of the different components used in the operation of the platform.
The web service API acts as a conduit between the Complyfile application and the platform’s database. All transactions requested by end users, executed using the web application, are routed through the web service API.
The web service API can offer services to third party applications that wish to engage in the activities offered by the Complyfile platform. The web service API is a two-way conduit. It can receive inbound requests from external applications to perform specific actions and it can perform outbound requests to external client web services whenever an action occurs on the platform.
There are numerous security authentication mechanisms available to secure external web services to ensure that only the data applicable to a registered organisation can be obtained or updated by that organisation. These mechanisms include:
Numerous articles have been written about securing websites and web services. One such article, providing a concise and clearly written overview, can be found at:
The Complyfile web services employ a token based authentication approach using the JSON Web Token (JWT) token structure, implemented using the standard Microsoft implementation for .NET and secured using HTTPS. Tokens are returned from registration and login requests and remain valid for the period of time stipulated by the web service client during those initial requests. This token must be provided with all further web service requests for the duration of the session. Any web service requests containing an invalid or expired token will be refused by the server. The following scenario provides an overview of the communication between client and server during a single session:
Implementing security in this manner ensures that the client’s credentials are only provided during the initial authorisation handshake and are not required, and cannot therefore be compromised, during any further requests during that session. Session security is further strengthened through the use of application keys, which can be generated whenever required by the client, and can be revoked just as easily.
A webhook is a HTTP callback request, a process in which a web service or other process can invoke external web services provided by other third parties. For Complyfile, webhooks can be available for a number of processes, including:
Individual organisations can specify webhooks for each of the available Complyfile processes that offer support for callbacks. These webhooks will then trigger whenever those processes occur, allowing the third party service to respond to the webhook and perform additional tasks.
The following workflow provides an example of a webhook in operation:
Webhooks provide a powerful mechanism for extending an application and allowing it to integrate with internal and external applications. Webhooks operate asynchronously, and do not need to wait until the callback operation completes. Complyfile webhooks operate using standard REST operations, and follow the usual GET/PUT/POST/DELETE verb rules required by that standard.
Webhooks, once configured, will operate when events occur in the web application or the API. In the above example, the same webhook would be executed if the invite was created by an end-user performing the operation in the application.