NAV Navbar
  • Receive Reports
  • Receive Reports

    This tutorial shows you how to receive reports using the Form3 API. We provide an overview of how reports work in FPS and Bacs, followed by a step by step guide on how to be notified when new reports are available and how to download them.

    Reports Overview

    FPS and Bacs offer a variety of reports on various topics for download. Depending on your status, different reports may be available to you. Depending on scheme rules, you may even be required to download some types of reports.

    Payment schemes regularly provide reports listing events that have occured between you and the scheme. Examples are failed and successful transactions, as well as returns or listings of issued indemnity claims. Reports are ususally distributed as a file and made available for download.

    Scheme Reports in FPS

    FPS issues the following reports for download:

    The Sponsored Participant Report will only be available to if you are sponsoring other FPS entities.

    For more information on reports, see the FPS scheme user guide "IPL00114 FPS Reference data maintenance Member, Agency and Scheme Guide" available from FPS. The document is also available for download from our customer portal.

    Scheme Reports in Bacs

    Bacs scheme reports provide information about files and transactions processed by Bacs and highlight any payment instructions that were amended, rejected or returned. There can be multiple formats for a report. You are required by scheme rules to download certain Bacs reports.

    For more information on reports in Bacs, take a look at the "Messaging Paying Banks Guide" and "Bacstel-IP Service User Guide" documents available for members at https://www.bacs.co.uk.

    Reports in the Form3 API

    Form3 downloads the reports from the scheme on your behalf and makes them available for download through the Reports API. Downloading report files is protected using the same access protection technology that controls access to all other parts of the API. A notification feature allows to be notified upon arrival of new reports.

    A report is represented in the Form3 API by the Report resource. The arrival of a new report is represented by the Report Admission resource. Subscribing to the creation of new Report Admission resources will enable you to receive notifications whenever a new report arrives.

    Example Report resource

    {
       "data": { 
          "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
          "type": "reports",
          "version": 1,    
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "created_on": "2019-01-16T16:04:31.486Z",
          "modified_on": "2019-01-16T16:05:45.984Z",    
          "attributes": {
              "report_type": "2013",
              "report_type_description": "AUDDIS Input",
              "generation_time": "2019-01-16T16:04:31.194Z",
              "processing_date": "2019-01-16",
              "report_source": "BACS",
              "formats": [
                  "pdf"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "pdf": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/pdf"
            }
          }
       }   
    }
    


    The Report resource contains information about the report it represents, the file types it is available in, as well as a download link to access the report file. The most important attributes in the Report resource are:

    Step by Step Guide

    In this section, we'll walk you through each step of receiving a report. You will:

    The code example is written in Python using the requests package to access the Form3 API. Each code snippet is a standalone Python program, but make sure to paste the required data for each program at the top. The snippets are tested with Python 3.5, but most likely will also work with other Python versions.

    Prerequisites

    Before getting started, make sure you have the following things ready to follow along:

    Subscribe to Report Admissions

    You can use Form3's Notification service to be notified when a new report arrives. Create a subscription for the creation of Report Admission resources to be notified through a webhook or SQS queue when this happens. Create a Subscription resource with these parameters:

    See this tutorial to learn how to create a subscription and receive notifications.

    Receive a Report Notification

    With the subscription in place, a notification is sent to your callback URL when a new report arrives.

    The notification will look similar to this:

    Report notification

    {  
      "id": "9d7b6d0a-21cb-4de2-b8a4-f189635d6fc9",
      "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
      "event_type": "created",
      "record_type": "report_admissions",
      "data": {  
          "data": {  
            "id": "8850dfe8-9b51-4cc8-869c-cb97ec21e3df",
            "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
            "type": "report_admissions",
            "version": 0,
            "attributes": {  
              "admission_datetime": "2019-04-02T13:57:59.689Z",
              "status": "delivery_confirmed"
            },
            "relationships": {  
              "report": {  
                "data": [  
                  {
                    "id": "9bff8014-8a35-4244-92c2-f22362bec8df",
                    "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
                    "type": "reports",
                    "version": 1,  
                      "attributes": {
                        "formats": [
                        "xml",
                        "zipped_xhtml"
                        ],
                        "generation_time": "2019-04-02T13:57:58.000Z",
                        "report_source": "BACS_SERVICE_USER",
                        "report_type": "2013",
                        "report_type_description": "AUDDIS Input"
                    }
                  }
                ]
              }
            }
        }
      }
    }
    


    The notification contains the Reports Admission resource and, in its relationships section, the Report resource with the report details. To fetch the Report resource and get the download link, you will need the content of the id attribute of the Report resource, which is 9bff8014-8a35-4244-92c2-f22362bec8df in this example.

    Fetch the Report Resource

    To get the required information for downloading the report, fetch the Report resource:

    GET v1/notification/reports/{report_id}

    Note that report_id is the ID of the Reports resource from the notification in the previous section. The call will respond with the Report resource that will look similar to this:

    Report resource

    {
      "id": "9bff8014-8a35-4244-92c2-f22362bec8df",
      "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
      "type": "reports",
      "version": 1,
      "attributes": {
        "formats": [
          "xml",
          "zipped_xhtml"
        ],
        "generation_time": "2019-04-02T13:57:58.000Z",
        "report_source": "BACS_SERVICE_USER",
        "report_type": "2013",
        "report_type_description": "AUDDIS Input"
      },
      "relationships": {
        "report_admission": {
          "data": [
            {
              "id": "8850dfe8-9b51-4cc8-869c-cb97ec21e3df",
              "organisation_id": "75198a6a-a4a5-430b-9098-b2d0678c6bf0",
              "type": "report_admissions",
              "version": 0,
              "attributes": {
                "admission_datetime": "2019-04-02T13:57:59.689Z",
                      "status": "delivery_confirmed"
              },
            }
          ]
        }
      },
        "links": {
          "self": {
            "href": "/v1/notification/reports/9bff8014-8a35-4244-92c2-f22362bec8df"
          },
          "xml": {
            "href": "/v1/notification/reports/9bff8014-8a35-4244-92c2-f22362bec8df",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/9bff8014-8a35-4244-92c2-f22362bec8df",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
        }
    }
    


    From the report_type and report_type_description attributes, you can see that the type of the report is "2013", which is an "AUDDIS Input" report.

    The formats attribute shows that the report is available as an XML file and a zipped XHTML file. The download links for the files are located in the links section in the href attribute. The meta.content-type attribute contains the content type for the download request.

    Download Report Files

    To download the reports file, you need the download link and the content type from the Reports resource. Perform a GET request on the download URL and add the content type to the Accept header of the request to get the desired format.

    Note that you also need to add the access token to the header like for any other API request:

    Report download request header

    GET /v1/notification/reports/9bff8014-8a35-4244-92c2-f22362bec8df HTTP/1.1
    Accept: application/xml
    Authorization: bearer eyJ0eXAiOiJKV1QiLCJ...
    Host: api.form3.tech
    


    The API will answer with a (200) OK status code and the download will start.

    The following Python script fetches a Report resource and then downloads all available report files based on the information in the resource:

    Python script for downloading report files

    import json, requests
    
    ### Replace these variables with your own data! ###
    client_id = 'YOUR CLIENT ID HERE'
    client_secret = 'YOUR CLIENT SECRET HERE'
    report_id = 'ID OF THE REPORT RESOURCE HERE'
    
    base_url = 'https://api.test.form3.tech'
    
    # Obtain authentication token
    print("Obtaining bearer token...")
    auth_payload = "grant_type=client_credentials"
    auth_url = '%s/v1/oauth2/token' % base_url
    auth_headers = {'Content-Type': 'application/x-www-form-urlencoded'}
    auth_request = requests.auth.HTTPBasicAuth(client_id, client_secret)
    
    auth = requests.request('post', auth_url, data=auth_payload, auth=auth_request, headers=auth_headers)
    auth_token = auth.json().get('access_token')
    
    
    # Get report resource
    print("Fetching Report resource..")
    report_url =  "%s/v1/notification/reports/%s" % (base_url, report_id)
    report_header = {
        'authorization': "bearer " + auth_token,
        'accept': "application/json",
        'content-type': "application/json",
        'cache-control': "no-cache"
        }
    
    report_resource = requests.get(report_url, headers=report_header)
    report_resource_content = json.loads(report_resource.text)
    print("Report type: %s" % report_resource_content['data']['attributes']['report_type'])
    print("Report description: %s" % report_resource_content['data']['attributes']['report_type_description'])
    print("Available report formats: %s" % ', '.join(report_resource_content['data']['attributes']['formats']))
    
    # Download report files
    for filetype, data in report_resource_content['links'].items():
        if filetype == 'self':
            continue
        print("Downloading report file in %s format..." % filetype)
        download_header = {
            'authorization': "bearer " + auth_token,
            'accept': data['meta']['content-type'],
            'cache-control': "no-cache"
        }
        download_url = base_url + data['href']
    
        report = requests.get(download_url, headers=download_header)
        filename = "report_file.%s" % filetype
        open(filename, 'wb').write(report.content)
        print("Saved report file to %s" % filename)