Information for Software Developers


The ability to upload iXBRL Accounts documents to the SureFile Accounts service and retrieve assurance reports is not restricted to the upload panel on the Subscriber Account page. A simple interface is also provided for Accounts production software products and CT filing software products to permit the direct submission of iXBRL Accounts documents and the viewing of assurance reports from within a software product, using the same credentials that subscribers use to access the website.


The interface provides sufficient functionality for a third-party application to undertake submission, report presentation and the management of past attempts from within an Accounts production or CT filing product, providing a seamless experience for users and enhancing the functionality of the product. Product vendors can either leave their customers to subscribe to SureFile Accounts as and when they need to, or take up a bulk contract subscription on their users' behalf. If you're a product vendor and would like to know more about the interface, or if you'd like to arrange a bulk contract for your customers, please Contact us to discuss pricing. The description of the interface below should give you a flavour of what's required - when you contact us we'll send you full details of the interface definition.


Submission attempts made through this website or through an enabled software product are available to be viewed in either environment - they are all visible in the Submission history shown on the logged-in Subscriber's Account page, but equally they can be accessed externally through an enabled product with the subscriber's credentials. In this way, an enabled software product can incorporate as much or as little past submission management as the vendor wishes. In addition, the SureFile Accounts website is there to take care of account management, subscription requests and secondary user management for in-house teams.


Third-party Software Interface Description

The interface is designed to be as simple as possible to facilitate initial integration, but offers a range of capabilities for more enterprising and imaginative developers to exploit. In keeping with the interface to the online database of submission attempts and reports, RESTful techniques have been employed.


Whereas the interfaces to the HMRC and Companies House filing services are POST-based, RPC-style and asynchronous, the SureFile Accounts interface employs a similar HTTPS POST-based interface that is synchronous and follows REST principles.


There are two variants of this interface – one to suit standalone client applications and one to suit web-based form clients:


Standalone Client Application Interface

To make a submission attempt from a standalone client application the bare content of an Inline XBRL Accounts document (no need for XML wrappers or envelopes of any kind) is POSTed to the URI endpoint described below with parameters (represented by HTTP headers) including the organisation’s credentials (email address as user id, and a password), the validation level required, the entity’s identifier and PoA end date, and the industry sector for the entity (if known).


Web-based Forms Interface

To make a submission from a web-based form client a standard HTML form element can be employed, utilising the POST method and encoding the submission and all the associated parameters with the MIME type “multipart/form-data”. This variant uses HTTP basicAuth and expects user id and password to be supplied by the user’s browser (which requests these from the user via a separate dialog as and when necessary).


Common Aspects of the Interface

Both variants POST to a service endpoint URI (the service ‘resource’) for either the UK or Ireland:


https://library.surefileaccounts.com/{uk|ie}/accounts/

This follows REST principles in that the result of the POST is the creation of new subordinate resources “below” the resource that is the target of the POST . These subordinate resources once created (illustrated below) can then be the subject of a GET to retrieve them.


For example, a second attempt to validate a set of UK Accounts for an entity with the CRN ‘12345678’ with a Period-of-Accounts end date of 31st Dec 2011 would be POSTed to this endpoint URI and the entity identifier and PoA end-date parameters would be checked for consistency against the content of the Accounts - if they are inconsistent we reject the submission attempt without charge. Assuming consistency, this would result in the creation of two securely accessible ‘permalink’ resources at SureFile’s site:


https://library.surefileaccounts.com/uk/accounts/CRN-12345678/2011-12-31/2nd/document.html
and
https://library.surefileaccounts.com/uk/accounts/CRN-12345678/2011-12-31/2nd/report.html

The second of these URLs (the assurance report for this attempt) will be returned by the POST request as an HTTPS redirect. This can simply be handed off to a web browser to display the report content or extracted and used in a subsequent HTTPS GET request by the application itself to retrieve the report content.


Such URLs can be bookmarked and stored for future use or, because of their regular and logical structure, inferred and recreated as required. Access by web browser applies basic HTTP authentication, requiring the user’s (or any of their organisation’s) credentials to be supplied to gain access. These are usually cached by the browser during that session to facilitate access to other secured pages without further intervention.


Each attempt is secured with the credentials of the submitter (permitting anyone within the submitter’s organisation to access it, subject to the primary subscriber’s control over internal privacy settings) so even if an entity/PoA combination is the subject of validation attempts by more than one organisation (both preparer and reviewer, perhaps) each organisation can only gain access to their own attempts. This also protects access to historical Accounts documents and reports in the event of the transfer of representation for entities from one organisation to another over time.


The intention is for third-party software developers to incorporate, as a minimum, a means to instigate a submission validation attempt (e.g. via a UI button or pre-populated web form) with either prompted-for or cached credentials. Everything else necessary for the submission can be engineered by the application. This will permit the universal provision of the SureFile Accounts submission interface, which will only be operational when the end-user of the software package is a SureFile Accounts service subscriber.


To facilitate connection testing and to determine the status and availability of the services, STATUS resources are provided at:


https://library.surefileaccounts.com/{uk|ie}/accounts/STATUS

Performing a GET on this resource returns an HTML page with embedded status information which can easily be extracted for presentation in non-HTML environments.