NAV Navbar
http shell python
  • Introduction and API Conventions
  • Authentication
  • Audits
  • Notifications
  • Reports
  • Scheme Messages
  • Organisation
  • Security
  • Validation
  • Payments
  • Direct Debits
  • Mandates
  • Claims
  • Transaction Simulator
  • Enumerations
  • Release Log
  • Introduction and API Conventions

    Welcome to the Form3 API documentation. Our API is based on the principle of REST. The API is resource-based and calls are idempotent through unique resource IDs.

    This introduction contains information about general rules and conventions that apply throughout the entire API. We also offer links to further resources to get you started with Form3 as fast and easy as possible.

    See the following chapters for an in-depth description of each resource our API offers.

    Swagger specification

    The Form3 API is defined using the Swagger or OpenAPI v2 specification. The definition allows you generate code for client application in variety of programming languages. You can download our Swagger file here:

    Form3 Financial Cloud OpenAPI specification / Swagger

    Postman

    Postman is a useful tool to explore REST APIs such as ours. Use our Postman collection to make calls to API endpoints and understand how it works. See here for our Postman collection:

    Form3 Financial Cloud Postman collection

    Endpoint connection

    The base URL for our production environment is https://api.form3.tech. You have to use TLS 1.2 or greater to connect to any of our API endpoints.

    We're also offering sandbox environments for testing and development purposes. Get in touch to obtain access to our sandbox environments!

    Actions and HTTP methods

    The Form3 API allows you to make and receive transactions. As a general rule, we keep the data of a transaction separate from the action of sending or receiving it.

    For example, for making a payment you would provide the details of the payment (amount, sender, receiver, etc.) by creating a Payment resource. In order to send the payment, you have to create a Payment Submission resource.

    The table below gives an overview of the actions the API supports:

    Action HTTP Method Description
    Create transaction POST Create a transaction resource (e.g. a Payment or Return) to provide transaction details like amount
    Send a transaction POST Create a transaction submission resource to send the transaction (e.g. a Payment Submission)
    Receive a transaction GET Fetch a transaction admission resource notifies you that a transaction has been received
    Fetch GET Fetch a specific resource, e.g. to read transaction details
    List GET List all resources of one type with the ability to filter for characteristics like date ranges, status, etc.
    Delete DELETE Remove a resource
    Edit PATCH Edit attributes of a resource

    Headers

    All requests to the Form3 API must contain three header HTTP headers:

    Authorization: bearer YOUR_TOKEN_HERE
    Accept: application/vnd.api+json
    Content-Type: application/vnd.api+json

    When downloading a reports via the Reports API, the Accept header must be adjusted to the format of the report.

    Note that YOUR_TOKEN_HERE needs to be replaced with an access token obtained via OAuth 2.

    URL Parameters

    Many endpoints require URL parameters such as IDs. In the API documentation, these IDs are written in curly brackets like this: {some_id}. For example, when creating a return for a payment, the create return endpoint requires the ID of the Payment resource that a return should be created for: POST v1/transaction/payments/{payment_id}/returns

    List endpoints further support query strings to allow for pagination and filtering when returning large numbers of resources. Query strings are indicated by a leading ? and have the format query_title=query_string. Multiple queries are connected using &.

    Message body structure

    All endpoint request and response bodies are formatted as JSON. Every resource that is created or returned through the API contains a standard set of JSON objects.

    On the highest level, every message has an object called data. It contains the resource that is the subject of the call. List calls can return multiple resources, in this case the data object contains a list of resources.

    Each resource has the following attributes (note that attributes marked required have to be provided with every resource when creating it):

    Example resource object

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "type": "payment_submissions",
            "id": "a1d76869-2baf-48eb-80f5-139da36db2a8",
            "version": 0,
            "organisation_id": "f8f4f58a-e2e2-4e45-b62b-e812e28dc70a",
            "created_on": "2019-03-19T11:22:32.936Z",
            "modified_on": "2019-03-19T11:22:32.936Z",
            "attributes": {
                (...)
            },
            "relationships": {
                "payment": {
                    "data": [
                        {
                            "type": "payments",
                            "id": "0ad80ecb-82c8-49dd-9dd2-a3d9be2ec529"
                        }
                    ]
                }
            }
        },
        "links": {
            "self": "https://api.form3.tech/v1/transactions/payments"
        }
    }
    
    {
        "data": {
            "type": "payment_submissions",
            "id": "a1d76869-2baf-48eb-80f5-139da36db2a8",
            "version": 0,
            "organisation_id": "f8f4f58a-e2e2-4e45-b62b-e812e28dc70a",
            "created_on": "2019-03-19T11:22:32.936Z",
            "modified_on": "2019-03-19T11:22:32.936Z",
            "attributes": {
                (...)
            },
            "relationships": {
                "payment": {
                    "data": [
                        {
                            "type": "payments",
                            "id": "0ad80ecb-82c8-49dd-9dd2-a3d9be2ec529"
                        }
                    ]
                }
            }
        },
        "links": {
            "self": "https://api.form3.tech/v1/transactions/payments"
        }
    }
    
    {
        "data": {
            "type": "payment_submissions",
            "id": "a1d76869-2baf-48eb-80f5-139da36db2a8",
            "version": 0,
            "organisation_id": "f8f4f58a-e2e2-4e45-b62b-e812e28dc70a",
            "created_on": "2019-03-19T11:22:32.936Z",
            "modified_on": "2019-03-19T11:22:32.936Z",
            "attributes": {
                (...)
            },
            "relationships": {
                "payment": {
                    "data": [
                        {
                            "type": "payments",
                            "id": "0ad80ecb-82c8-49dd-9dd2-a3d9be2ec529"
                        }
                    ]
                }
            }
        },
        "links": {
            "self": "https://api.form3.tech/v1/transactions/payments"
        }
    }
    
    Attribute Description
    id string, unique identifier (UUID) required always The unique ID of the resource in UUID 4 format. It identifies the resource within the system.
    organisation_id string, unique identifier (UUID) required always The organisation ID of the organisation by which this resource has been created. This is usually the organisation ID of your organisation.
    type string optional always The type of resource. This name is used in the record_type attribute of notification and audit calls to identify a type of resource. Note that you don't need to supply this object when creating a resource, it is automatically added by Form3
    version integer read-only always A read-only counter indicating how many times this resource has been modified. When you create a resource, it is automatically set to 0. Whenever the content of the resource changes, the version attribute is increased.
    created_on date-time read-only sometimes Time and date on which the resource was created. Currently rolled out across the API, not all resources might have this attribute yet.
    modified_on date-time read-only sometimes Time and date on which the resource was last modified. Corresponds the to the time the version attribute was last updated. Currently rolled out across the API, not all resources might have this attribute yet.
    attributes object optional sometimes The specific attributes for each type of resource. See the resource descriptions in this documentation for the attributes of each resource.
    relationships object read-only always IDs of related resources. For example, a Payment Submission resource would list the ID of the Payment resource it is submitting here.

    Response messages further have an object called links. It contains one or more links to related endpoints, including self, which links to the endpoint the message came from.

    Errors and Status Codes

    The Form3 API supports a number of different HTTP status codes and provides error messages to help you find out why something went wrong when it does.

    Form3 uses the following HTTP status codes:

    Status Code Description
    200 OK. Request was accepted. Used when requesting data using GET.
    201 Created. A resource was created successfully.
    204 No Content. Used to indicate a DELETE operation was successful.
    400 Bad Request. Returned when the message contains invalid syntax. error_code and error_message attribute provide information to help identify the problem.
    401 Unauthorized. Returned when trying to access API endpoints with an invalid or expired access token.
    403 Forbidden. Returned when trying to obtain an access token with incorrect client credentials.
    404 Not Found. Returned when trying to access a non-existent endpoint or resource. Returned in the Validation API when a queried sort code cannot be found.
    405 Method Not Allowed. Returned when trying to access an endpoint that exists using a method that is not supported by the target resource.
    406 Not Acceptable. Returned when trying to access content with an incorrect content type specific in the request header.
    409 Conflict. The resource has already been created. It is safe ignore this error message and continue processing. Returned for DELETE calls when an incorrect version has been specified.
    429 Too Many Requests. Returned when the rate limit for requests per second has been exceeded, please back-off immediately, then retry later.
    500 Server Error. Returned when an internal error occurs or the request times out. This is safe to retry after waiting a short amount of time.
    502 Bad Gateway. Returned when there is a temporary internal networking problem. This is safe to retry after waiting a short amount of time.
    503 Service Unavailable. Returned when a service is temporarily overloaded. This is safe to retry after waiting a short amount of time.

    Errors can also occur on higher levels, for example when a payment submission fails. See our tutorial on error handling for an overview of high-level errors.

    Timeouts, rate limiting and retry strategy

    Exponential back-off retry algorithm

    DEFAULT_TIMEOUT = 60 seconds
    MAX_RETRIES = 3
    retries = 0
    
    
    DO
        TRY
    
          IF retries > 0
            WAIT for (1.5^retries * 500) milliseconds +- some jitter
    
          status = makeCallToForm3(timeout:DEFAULT_TIMEOUT)
    
          IF status = SUCCESS (2xx) or CONFLICT (409)
              retry = false
          ELSE IF status = THROTTLED (429) # You have reached your request limit and are being throttled
              retry = true
          ELSE IF status >= 500 # A temporary issue has occured, all requests are idempotent and safe to retry
              retry = true
          ELSE # Another http reponse such as 400 bad request, client must fix request before retrying
              retry = false
          END IF
        CATCH EXCEPTION
          retry = true # connection timeout, connection dropped etc...
        END TRY
    
        retries = retries + 1    
    WHILE (retry AND (retries <= MAX_RETRIES))
    

    Should a request to the Form3 API respond with a status code indicating a temporary error (429, 500, or 503, see above) or no response is received at all, wait and retry the request using an exponential back-off algorithm. See the code panel on the right for a simple example implementation in pseudo code. Note that you may have to adapt the provided example values to fit your own specific requirements.

    We recommend using more sophisticated implementations of the back-off algorithm. See these links for examples in the programming language you are using:

    Rate limiting

    Rate limiting is enforced when exceeding a critical number of requests per second. This is done to protect the platform and ensure its integrity. If you exceed the rate limit, your request will fail and you will receive a 429 HTTP status code. It is recommended to implement an exponential backoff algorithm to retry the failed request, see above for examples.

    Retry strategy

    In case a timeout occurs or you are receiving an unexpected error response, follow the actions below. The Processed column indicates if a request has been processed by Form3 as intended.

    Received Response Recommended Action Processed
    Success (2xx status code) Continue with the normal process flow. Yes
    Duplicate ID (409 status code) Continue with the normal process flow as this means a previous request was successful. Yes
    Unauthorised (401) Retrieve a new access token, then retry the request. No
    Permanent error (400, 403, 404, 406 status codes) Contact Form3 for assistance. No
    Request throttled error (429) Wait and retry the request. The use of an exponential back-off algorithm is recommended. No
    Temporary error (500, 502, 503 status codes) Retry the request. The use of an exponential back-off algorithm is recommended. Not guaranteed
    Other network related errors: connection closed, timeout etc... Retry the request. The use of an exponential back-off algorithm is recommended. Not guaranteed

    Receiving Notifications

    Form3 events notifications are sent to either AWS SQS or a webhook.

    If the webhook or queue does not acknowledge the receipt of a notification with an HTTP success status (2XX), Form3 will retry delivering the notification 10 times with increasing wait times. After the final unsuccessful retry, the subscription for this event is deactivated and the notification is stored.

    Deactivated subscriptions can be re-activated through an API call. See our section on handling notification delivery errors for more information.

    Service health

    Example health request

    GET /v1/transaction/payments/health HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/transaction/payments/health \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/transaction/payments/health', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "status": "up"
    }
    
    
    {
        "status": "up"
    }
    
    
    {
        "status": "up"
    }
    
    

    Every service in the Form3 API provides a health check endpoint to determine its availability. Status availability can be queried using a GET {service_path}/health HTTP request.

    The health check returns a JSON response body with the status attribute which can either be up if the service is available, or down if the service is not available.

    Below is a list of services and the health call for them:

    Service Health endpoint
    Audits GET /v1/audit/entries/health
    Notifications GET /v1/notification/subscriptions/health
    Scheme Messages GET /v1/notification/schememessages/health
    Reports GET /v1/notification/reports/health
    Organisations GET /v1/organisation/units/health
    Accounts GET /v1/organisation/accounts/health
    Security GET /v1/security/users/health
    Payments GET /v1/transaction/payments/health
    Direct Debits GET /v1/transaction/directdebits/health
    Mandates GET /v1/transaction/mandates/health
    Claims GET /v1/transaction/claims/health
    Validations GET /v1/validations/gbdsc/health

    In addition, service availability of our production environment can be viewed on our status page: https://form3.statuspage.io/

    Change policy

    Form3 is constantly improving its services and API. To ensure users are not negatively affected by improvements, Form3 adheres to a no breaking change policy. This means that no change to the API will remove or change existing resources or their attributes.

    Non-breaking changes to the API include: adding new attributes to existing resources, new values for attributes, creating new resources and launching new services. These changes are made without prior notification to users. Check the change log for a list of previous such changes.

    In case a change should affect existing user implementations, Form3 will notify users in advance and give them sufficient time to adapt their implementation before applying the change to the production environment.

    Authentication

    The Form3 API uses HTTP Message Signing to authenticate users and messages that are sent to the API. A private and public key pair is generated before accessing the API for the first time. The user then signs all messages sent to the API with the private key while Form3 uses the public key to verify the authenticity of the message.

    Tutorial: Our request signing step-by-step guide describes how to create your keys and sign messages.

    Description of the Form3 authentication scheme

    For more information on the process for exchanging, rotating and deactivating public keys, see the request signing user guide available in the Form3 Portal.

    Signed Message Signature

    Signature example

    GET / HTTP/1.1
    Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256",
    headers="(request-target) host date accept content-type",
    signature="dGVzdGVzdGVzdHNldHQ="
    
    GET / HTTP/1.1
    Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256",
    headers="(request-target) host date accept content-type",
    signature="dGVzdGVzdGVzdHNldHQ="
    
    GET / HTTP/1.1
    Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256",
    headers="(request-target) host date accept content-type",
    signature="dGVzdGVzdGVzdHNldHQ="
    

    Example GET request

    GET /v1/audit/entries/health HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    Accept: application/vnd.api+json
    Host: api.form3.tech
    Date: Fri, 29 Feb 2019 14:00:00 GMT
    Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256",
    headers="(request-target) host date accept",
    signature="dGVzdHNldHNldHNldHNldHNhZGFkYXNkIGkgdGFraWUgdGFt"
    
    GET /v1/audit/entries/health HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    Accept: application/vnd.api+json
    Host: api.form3.tech
    Date: Fri, 29 Feb 2019 14:00:00 GMT
    Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256",
    headers="(request-target) host date accept",
    signature="dGVzdHNldHNldHNldHNldHNhZGFkYXNkIGkgdGFraWUgdGFt"
    
    GET /v1/audit/entries/health HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    Accept: application/vnd.api+json
    Host: api.form3.tech
    Date: Fri, 29 Feb 2019 14:00:00 GMT
    Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256",
    headers="(request-target) host date accept",
    signature="dGVzdHNldHNldHNldHNldHNhZGFkYXNkIGkgdGFraWUgdGFt"
    

    Example POST request

    POST /v1/transaction/payments/ HTTP/1.1
    Host: api.form3.tech
    Date: Fri, 29 Feb 2019 14:00:00 GMT
    Accept: application/vnd.api+json
    Content-Type: application/vnd.api+json
    Content-Length: 8
    Digest: SHA256=XtSlsJ6FNvDG3LemJ/IFxpkmopLKwwSsUGJebLIiZH0=
    Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256",
    headers="(request-target) host date accept digest content-length content-type",
    signature="dGVzdHNldHNldHNldHNldHNhZGFkYXNkIGkgdGFraWUgdGFt"
    
    { body }
    
    POST /v1/transaction/payments/ HTTP/1.1
    Host: api.form3.tech
    Date: Fri, 29 Feb 2019 14:00:00 GMT
    Accept: application/vnd.api+json
    Content-Type: application/vnd.api+json
    Content-Length: 8
    Digest: SHA256=XtSlsJ6FNvDG3LemJ/IFxpkmopLKwwSsUGJebLIiZH0=
    Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256",
    headers="(request-target) host date accept digest content-length content-type",
    signature="dGVzdHNldHNldHNldHNldHNhZGFkYXNkIGkgdGFraWUgdGFt"
    
    { body }
    
    POST /v1/transaction/payments/ HTTP/1.1
    Host: api.form3.tech
    Date: Fri, 29 Feb 2019 14:00:00 GMT
    Accept: application/vnd.api+json
    Content-Type: application/vnd.api+json
    Content-Length: 8
    Digest: SHA256=XtSlsJ6FNvDG3LemJ/IFxpkmopLKwwSsUGJebLIiZH0=
    Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256",
    headers="(request-target) host date accept digest content-length content-type",
    signature="dGVzdHNldHNldHNldHNldHNhZGFkYXNkIGkgdGFraWUgdGFt"
    
    { body }
    

    Response (401 Unauthorized)

    HTTP/1.1 401 Unauthorized
    
    <html>
    
    <head>
        <title>401 Authorization Required</title>
    </head>
    
    <body bgcolor="white">
        <center>
            <h1>401 Authorization Required</h1>
        </center>
        <hr>
        <center>openresty/1.13.6.2</center>
    </body>
    
    </html>
    

    A signed message carries the signature in its Authorization header. All requests also need a Date and a Host header. In addition, requests that contain a body, such as POST, PATCH and PUT, require a Digest header that is generated by hashing the body content using SHA256 (see example POST request on the right).

    For requests that contain a body such as POST, PATCH and PUT:

    Header Description
    Host API host domain, api.form3.tech for the production environment
    Date Current date in format ddd, DD MMM YYYY, h:mm:ss ZZ, example: Tue, 07 Jun 2014 20:51:35 GMT
    Authorization Signature header (see below)
    Digest SHA-256=<digest_value> digest value
    Content-Length The size of the body
    Content-Type The content type of the body

    For requests without a body such as GET and DELETE:

    Header Description
    Host API host domain, api.form3.tech for the production environment
    Date Current date in format ddd, DD MMM YYYY, h:mm:ss ZZ, example: Tue, 07 Jun 2014 20:51:35 GMT
    Authorization Signature header (see below)

    In case any part of the header is incorrect and doesn't match the credentials stored at Form3, the API responds with a 401 "Unauthorized" error.

    Authorization Header

    The Authorization header requires the following header parameters:

    Parameter Description
    keyId Unique identifier, UUID The public key ID
    algorithm string The algorithm used to sign the signature. Has to be rsa-sha256
    headers string A List of headers used to generate the signature
    signature hash The hashed signature using base64 encoding

    Deprecated: OAuth-based Authentication

    The Form3 API offers authentication via OAuth 2 Client Credentials Grant. The diagram below shows how to authenticate and use the API.

    Description of the Form3 authentication scheme

    Authenticate your account when using the API by using your Client ID and Client Secret to obtain an access token.

    For a complete code example see using an access token.

    Creating an access token

    Example request

    POST /v1/oauth2/token HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    Accept: application/vnd.api+json
    Host: api.form3.tech
    Authorization: Basic WktJQUpDRjVVSENaQkNLTENXNVE6ZGEyZjNmOTdhNTAxNGVjZWI1NzQ1MzZlOTc2NTJjNTY=
    
    curl -X POST https://api.form3.tech/v1/oauth2/token \
       -d grant_type=client_credentials \
       -u 'ZKIAJCF5UHCZBCKLCW5Q:da2f3f97a5014eceb574536e97652c56'
    
    import logging
    import requests
    # Python 2
    import httplib as http_client
    
    # Python 3
    #import http.client as http_client
    http_client.HTTPConnection.debuglevel = 1
    
    logging.basicConfig()
    logging.getLogger().setLevel(logging.DEBUG)
    requests_log = logging.getLogger("requests.packages.urllib3")
    requests_log.setLevel(logging.DEBUG)
    requests_log.propagate = True
    
    
    from requests.auth import HTTPBasicAuth
    payload = "grant_type=client_credentials"
    
    client_id = 'a796ee2d4b54407fbcce3b59d1a18812'
    client_secret = '2a591c94943c4f0ba7bfa1244f81ad7d'
    request = requests.request('post', 'https://api.form3.tech/v1/oauth2/token', data=payload, auth=HTTPBasicAuth(client_id, client_secret))
    print request.content
    

    Response (200 OK)

    HTTP/1.1 200 OK
    
    {
      "token_type": "bearer",
      "access_token": "4f08057f3bfe4f4e99a16446b44822d7",
      "expires_in": 7200
    }
    
    HTTP/1.1 200 OK
    
    {
      "token_type": "bearer",
      "access_token": "4f08057f3bfe4f4e99a16446b44822d7",
      "expires_in": 7200
    }
    
    {
      "token_type": "bearer",
      "access_token": "4f08057f3bfe4f4e99a16446b44822d7",
      "expires_in": 7200
    }
    

    Response (403 Invalid)

    HTTP/1.1 200 OK
    
    {
        "error": "invalid_grant",
        "error_description": "Wrong email or password."
    }
    
    HTTP/1.1 200 OK
    
    {
        "error": "invalid_grant",
        "error_description": "Wrong email or password."
    }
    
    {
        "error": "invalid_grant",
        "error_description": "Wrong email or password."
    }
    

    HTTP Request

    POST /v1/oauth2/token

    Headers Description Example
    Authorization: Basic Base 64 encoding of client id:client secret Authorization: Basic
    WktJQUpDRjVVSENaQkNLTENXNVE6ZGEyZjNmOTdhNTAxNGVjZWI1NzQ1MzZlOTc2NTJjNTY=
    Form Data Description
    grant_type The grant type which should be issued. Has to be client_credentials.

    HTTP Response

    Code Description
    200 Authentication successful, token issued
    403 Authentication failed
    Attribute Description
    access_token string always The token issued to be used in subsequent requests to the API
    token_type string always The type of token issued. Is always bearer.
    expires_in int always The time this token is valid for in seconds

    Using an access token

    Example request using an access token

    GET /v1/audit/entries/health HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    Accept: application/vnd.api+json
    Host: api.form3.tech
    Authorization: bearer 4f08057f3bfe4f4e99a16446b44822d7
    
    curl -X GET https://api.form3.tech/v1/audit/entries/health \
       -H Authorization=bearer 4f08057f3bfe4f4e99a16446b44822d7 \
       -H Apikey=6407992d81594c9db63a32ad3d2d5721
    
    import logging
    import requests
    # Python 2
    import httplib as http_client
    
    # Python 3
    #import http.client as http_client
    http_client.HTTPConnection.debuglevel = 1
    
    logging.basicConfig()
    logging.getLogger().setLevel(logging.DEBUG)
    requests_log = logging.getLogger("requests.packages.urllib3")
    requests_log.setLevel(logging.DEBUG)
    requests_log.propagate = True
    
    
    from requests.auth import HTTPBasicAuth
    payload = "grant_type=client_credentials"
    
    client_id = 'a796ee2d4b54407fbcce3b59d1a18812'
    client_secret = '2a591c94943c4f0ba7bfa1244f81ad7d'
    api_key = '0f5cd25972c747d0bde7459fb574272b'
    request = requests.request('post', 'https://api.form3.tech/audit/oauth2/token', data=payload, auth=HTTPBasicAuth(client_id, client_secret))
    request.raise_for_status();
    
    access_token = request.json()['access_token']
    
    
    headers = {
        'Accept': 'vnd.api+json',
        'Content-Type': 'application/vnd.api+json',
        'Authorization': 'bearer {}'.format(access_token),
        'Apikey': api_key
    }
    
    request = requests.request('get', 'https://api.form3.tech/audit/entries/health', headers=headers)
    request.raise_for_status()
    
    
    print request.content
    

    Response (200 OK)

    HTTP/1.1 200 OK
    
    {
      "status": "UP"
    }
    
    HTTP/1.1 200 OK
    
    {
      "status": "UP"
    }
    
    {
      "status": "UP"
    }
    

    Once an access token has been acquired it can be used to make API calls to protected endpoints. Following the OAuth specification, the token is placed in the Authorisation header.

    Audits

    The complete change history of every resource in the system is stored by the audit service. Each audit entry represents the complete state of a resource at a specific point in time. Querying the audit trail can be used to retrace past changes.

    Because audit trails store every version of a resource, they can quickly grow large. It is recommended to use filters (for organisation ID and/or time range) to limit the size of the response message and optimise response times.

    Entries

    Resource

    Example audit entry resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data" : {
            "type" : "AuditEntry",
            "id" : "8f730548-0e11-4489-a057-d930501347b8",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:41.308Z",
                "description" : "Record insert request - pending approval",
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "type" : "user",
                    "locked" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    }
                }
                "before_data": {}
            }
        }
    }
    
    {
        "data" : {
            "type" : "AuditEntry",
            "id" : "8f730548-0e11-4489-a057-d930501347b8",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:41.308Z",
                "description" : "Record insert request - pending approval",
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "type" : "user",
                    "locked" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    }
                }
                "before_data": {}
            }
        }
    }
    
    {
        "data" : {
            "type" : "AuditEntry",
            "id" : "8f730548-0e11-4489-a057-d930501347b8",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:41.308Z",
                "description" : "Record insert request - pending approval",
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "type" : "user",
                    "locked" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    }
                }
                "before_data": {}
            }
        }
    }
    
    Attribute Description
    record_type string Type of the resource that is being changed. See audit record types.
    record_id string, unique identifier (UUID) ID of the resource that is being changed
    actioned_by string, unique identifier (UUID) User ID of the user who requested the change
    action_time string, datetime Timestamp when the change was requested
    description string Textual description of the change being made
    before_data Snapshot of the data before the change (empty if the request was to CREATE a new record)
    after_data Snapshot of what the data would be after the change (empty if the request was to DELETE a record)

    Fetch

    Example request

    GET v1/audit/entries/users/e90c3385-e299-4d1c-95f3-fc1075e047a4 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/audit/entries/users/e90c3385-e299-4d1c-95f3-fc1075e047a4 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/audit/entries/users/e90c3385-e299-4d1c-95f3-fc1075e047a4', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data" : [ {
            "type" : "AuditEntry",
            "id" : "8f730548-0e11-4489-a057-d930501347b8",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:41.308Z",
                "description" : "Record insert request - pending approval",
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "type" : "user",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "40930113-5ac4-4be3-9b8b-26f70c0a4208",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "67559d77-d4f3-45e6-96c3-2eca727cb0f8",
                "action_time" : "2017-03-20T17:13:41.583Z",
                "description" : "Action approved",
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "type" : "user",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "473d04b0-4ccf-4e7c-8883-f2c2be05243d",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:41.788Z",
                "description" : "Record update requested - pending approval",
                "before_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                },
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank.updated"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "c804bda1-e876-498e-ac1c-0121081bc6f8",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "67559d77-d4f3-45e6-96c3-2eca727cb0f8",
                "action_time" : "2017-03-20T17:13:42.071Z",
                "description" : "Action approved",
                "before_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    },
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank.updated"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "437aef2c-a632-464e-9482-d44239784112",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:42.259Z",
                "description" : "Record delete requested - pending approval",
                "before_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                    "email" : "newuser.testbank@form3.tech",
                    "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                    "username" : "newuser.testbank.updated"
                    },
                    "deleted" : false,
                    "version" : 1,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                }
            }
        } ],
        "links" : {
            "self" : "http://api.form3.tech/v1/audit/entries/user/e90c3385-e299-4d1c-95f3-fc1075e047a4"
        }
    }
    
    {
        "data" : [ {
            "type" : "AuditEntry",
            "id" : "8f730548-0e11-4489-a057-d930501347b8",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:41.308Z",
                "description" : "Record insert request - pending approval",
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "type" : "user",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "40930113-5ac4-4be3-9b8b-26f70c0a4208",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "67559d77-d4f3-45e6-96c3-2eca727cb0f8",
                "action_time" : "2017-03-20T17:13:41.583Z",
                "description" : "Action approved",
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "type" : "user",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "473d04b0-4ccf-4e7c-8883-f2c2be05243d",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:41.788Z",
                "description" : "Record update requested - pending approval",
                "before_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                },
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank.updated"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "c804bda1-e876-498e-ac1c-0121081bc6f8",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "67559d77-d4f3-45e6-96c3-2eca727cb0f8",
                "action_time" : "2017-03-20T17:13:42.071Z",
                "description" : "Action approved",
                "before_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    },
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank.updated"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "437aef2c-a632-464e-9482-d44239784112",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:42.259Z",
                "description" : "Record delete requested - pending approval",
                "before_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                    "email" : "newuser.testbank@form3.tech",
                    "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                    "username" : "newuser.testbank.updated"
                    },
                    "deleted" : false,
                    "version" : 1,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                }
            }
        } ],
        "links" : {
            "self" : "http://api.form3.tech/v1/audit/entries/user/e90c3385-e299-4d1c-95f3-fc1075e047a4"
        }
    }
    
    {
        "data" : [ {
            "type" : "AuditEntry",
            "id" : "8f730548-0e11-4489-a057-d930501347b8",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:41.308Z",
                "description" : "Record insert request - pending approval",
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "type" : "user",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "40930113-5ac4-4be3-9b8b-26f70c0a4208",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "67559d77-d4f3-45e6-96c3-2eca727cb0f8",
                "action_time" : "2017-03-20T17:13:41.583Z",
                "description" : "Action approved",
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "type" : "user",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "473d04b0-4ccf-4e7c-8883-f2c2be05243d",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:41.788Z",
                "description" : "Record update requested - pending approval",
                "before_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                },
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank.updated"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "c804bda1-e876-498e-ac1c-0121081bc6f8",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "67559d77-d4f3-45e6-96c3-2eca727cb0f8",
                "action_time" : "2017-03-20T17:13:42.071Z",
                "description" : "Action approved",
                "before_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    },
                "after_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                        "email" : "newuser.testbank@form3.tech",
                        "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                        "username" : "newuser.testbank.updated"
                    },
                    "deleted" : false,
                    "version" : 0,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                    }
                }
            }, {
            "type" : "AuditEntry",
            "id" : "437aef2c-a632-464e-9482-d44239784112",
            "version" : 0,
            "organisation_id" : "38f4f718-1e5b-4164-89df-9e3555972eb2",
            "attributes" : {
                "record_type" : "User",
                "record_id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                "actioned_by" : "9a120694-2308-4044-9a6b-b667a9fc3e48",
                "action_time" : "2017-03-20T17:13:42.259Z",
                "description" : "Record delete requested - pending approval",
                "before_data" : {
                    "id" : "e90c3385-e299-4d1c-95f3-fc1075e047a4",
                    "locked" : false,
                    "record" : {
                    "email" : "newuser.testbank@form3.tech",
                    "role_ids" : [ "350df4b9-2ab6-486d-b36f-07012c293630" ],
                    "username" : "newuser.testbank.updated"
                    },
                    "deleted" : false,
                    "version" : 1,
                    "organisationId" : "38f4f718-1e5b-4164-89df-9e3555972eb2"
                }
            }
        } ],
        "links" : {
            "self" : "http://api.form3.tech/v1/audit/entries/user/e90c3385-e299-4d1c-95f3-fc1075e047a4"
        }
    }
    

    Get the audit history for a specific record using the record name and the record ID.

    HTTP Request GET /v1/audit/entries/{record_type}/{id}

    Parameter Description
    record_type string required Type of resource the record is requested for. See audit record types for supported types.
    id string, unique identifier (UUID) required ID of the resource the record is requested for

    List

    Example request

    GET /v1/audit/entry/users?page[number]=0&page[size]=2 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/audit/entry/users?page[number]=0&page[size]=2 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/audit/entry/users?page[number]=0&page[size]=2', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
                "type": "AuditEntry",
                "id": "37d8143b-4eba-4c2e-8869-c407dbdabb53",
                "version": 0,
                "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b",
                "attributes": {
                    "record_type": "User",
                    "record_id": "e0a67bd7-c466-4201-928d-556018c4f1d2",
                    "actioned_by": "51284b8e-d951-44bc-8373-7c16945f6d5d",
                    "action_time": "2018-02-16T13:40:02.632Z",
                    "description": "Record inserted",
                    "after_data": {
                        "id": "857a6c0c-0697-4120-9b8e-b33a64e22fc8",
                        "type": "User",
                        "locked": false,
                        "record": {
                            "email": "exampleuser1@form3.tech}",
                            "role_ids": [
                                "e2344ef5-14a3-6c6b-18fb-c2c35b9d23f5"
                            ],
                            "username": "exampleuser1",
                            "client_credential_ids": []
                        },
                        "deleted": false,
                        "version": 0,
                        "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b"
                    }
                }
            },
            {
                "type": "AuditEntry",
                "id": "7664c455-3e41-414e-b857-d3f01bfdb155",
                "version": 0,
                "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b",
                "attributes": {
                    "record_type": "User",
                    "record_id": "78b82f96-4326-4aaa-ad09-3fec79a28439",
                    "actioned_by": "51284b8e-d951-44bc-8373-7c16945f6d5d",
                    "action_time": "2018-02-16T13:40:02.928Z",
                    "description": "Record inserted",
                    "after_data": {
                        "id": "3bc83a76-c374-4650-af8f-2341ea58913b",
                        "type": "User",
                        "locked": false,
                        "record": {
                            "email": "exampleuser2@form3.tech}",
                            "role_ids": [
                                "17751893-01d7-28a3-bf37-4d4dbd9d9e25"
                            ],
                            "username": "exampleuser2",
                            "client_credential_ids": []
                        },
                        "deleted": false,
                        "version": 0,
                        "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b"
                    }
                }
            }
        ],
        "links": {
            "self": "https://api.form3.tech/v1/audit/entries?page%5Bnumber%5D=0&page%5Bsize%5D=2"
        }
    }
    
    {
        "data": [
            {
                "type": "AuditEntry",
                "id": "37d8143b-4eba-4c2e-8869-c407dbdabb53",
                "version": 0,
                "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b",
                "attributes": {
                    "record_type": "User",
                    "record_id": "e0a67bd7-c466-4201-928d-556018c4f1d2",
                    "actioned_by": "51284b8e-d951-44bc-8373-7c16945f6d5d",
                    "action_time": "2018-02-16T13:40:02.632Z",
                    "description": "Record inserted",
                    "after_data": {
                        "id": "857a6c0c-0697-4120-9b8e-b33a64e22fc8",
                        "type": "User",
                        "locked": false,
                        "record": {
                            "email": "exampleuser1@form3.tech}",
                            "role_ids": [
                                "e2344ef5-14a3-6c6b-18fb-c2c35b9d23f5"
                            ],
                            "username": "exampleuser1",
                            "client_credential_ids": []
                        },
                        "deleted": false,
                        "version": 0,
                        "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b"
                    }
                }
            },
            {
                "type": "AuditEntry",
                "id": "7664c455-3e41-414e-b857-d3f01bfdb155",
                "version": 0,
                "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b",
                "attributes": {
                    "record_type": "User",
                    "record_id": "78b82f96-4326-4aaa-ad09-3fec79a28439",
                    "actioned_by": "51284b8e-d951-44bc-8373-7c16945f6d5d",
                    "action_time": "2018-02-16T13:40:02.928Z",
                    "description": "Record inserted",
                    "after_data": {
                        "id": "3bc83a76-c374-4650-af8f-2341ea58913b",
                        "type": "User",
                        "locked": false,
                        "record": {
                            "email": "exampleuser2@form3.tech}",
                            "role_ids": [
                                "17751893-01d7-28a3-bf37-4d4dbd9d9e25"
                            ],
                            "username": "exampleuser2",
                            "client_credential_ids": []
                        },
                        "deleted": false,
                        "version": 0,
                        "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b"
                    }
                }
            }
        ],
        "links": {
            "self": "https://api.form3.tech/v1/audit/entries?page%5Bnumber%5D=0&page%5Bsize%5D=2"
        }
    }
    
    {
        "data": [
            {
                "type": "AuditEntry",
                "id": "37d8143b-4eba-4c2e-8869-c407dbdabb53",
                "version": 0,
                "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b",
                "attributes": {
                    "record_type": "User",
                    "record_id": "e0a67bd7-c466-4201-928d-556018c4f1d2",
                    "actioned_by": "51284b8e-d951-44bc-8373-7c16945f6d5d",
                    "action_time": "2018-02-16T13:40:02.632Z",
                    "description": "Record inserted",
                    "after_data": {
                        "id": "857a6c0c-0697-4120-9b8e-b33a64e22fc8",
                        "type": "User",
                        "locked": false,
                        "record": {
                            "email": "exampleuser1@form3.tech}",
                            "role_ids": [
                                "e2344ef5-14a3-6c6b-18fb-c2c35b9d23f5"
                            ],
                            "username": "exampleuser1",
                            "client_credential_ids": []
                        },
                        "deleted": false,
                        "version": 0,
                        "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b"
                    }
                }
            },
            {
                "type": "AuditEntry",
                "id": "7664c455-3e41-414e-b857-d3f01bfdb155",
                "version": 0,
                "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b",
                "attributes": {
                    "record_type": "User",
                    "record_id": "78b82f96-4326-4aaa-ad09-3fec79a28439",
                    "actioned_by": "51284b8e-d951-44bc-8373-7c16945f6d5d",
                    "action_time": "2018-02-16T13:40:02.928Z",
                    "description": "Record inserted",
                    "after_data": {
                        "id": "3bc83a76-c374-4650-af8f-2341ea58913b",
                        "type": "User",
                        "locked": false,
                        "record": {
                            "email": "exampleuser2@form3.tech}",
                            "role_ids": [
                                "17751893-01d7-28a3-bf37-4d4dbd9d9e25"
                            ],
                            "username": "exampleuser2",
                            "client_credential_ids": []
                        },
                        "deleted": false,
                        "version": 0,
                        "organisation_id": "e7da2a9d-6b9c-4883-b0a0-77f2ac84548b"
                    }
                }
            }
        ],
        "links": {
            "self": "https://api.form3.tech/v1/audit/entries?page%5Bnumber%5D=0&page%5Bsize%5D=2"
        }
    }
    

    List all audit entries of a specific type using the record ID with ability to paginate and filter.

    HTTP Request GET /v1/audit/entries/{record_type}?page[number]={page_number}&page[size]={page_size}&filter[{attribute}]={filter_value}

    Parameter Default Description
    record_type string required Type of resource the record is requested for. See here for supported types.
    page[number] integer optional 0 Page number being requested (starting from zero)
    page[size] integer optional 1000 Size of the page being requested
    filter integer optional Used to filter audit entries being returned. See: filter parameters below

    Filter parameters

    Value Description
    filter[organisation_id] Find all audit entries for a given organisation ID
    filter[action_time_from] Find all audit entries after a given timestamp
    filter[action_time_to] Find all audit entries until a given timestamp

    Record types

    When requesting an audit entry, you need to provide the type of resource you'd like to query. Below is a list with supported record types:

    Value Description
    User A user in the system
    Organisation An organisation in the system
    Role A role to control access to functions in the system
    subscriptions Notification subscriptions for events
    accounts A bank account registered by an organisation
    payments Details of incoming and outgoing payments or certain Bacs contra records
    payment_admissions Admission of incoming payments
    payment_submissions Submission of outgoing payments
    returns Details of incoming and outgoing returns
    return_admissions Admission of incoming returns
    return_submissions Submission of outgoing returns
    return_reversals Details of incoming and outgoing return reversals
    return_reversal_admissions Admission of incoming return reversals
    reversals Details of incoming or outgoing reversals
    reversal_admissions Admission of incoming reversals
    reversal_submissions Submission of outgoing reversals
    recalls Details of incoming or outgoing recalls
    recall_submissions Submission of outgoing recalls
    recall_admissions Admission of incoming recalls
    recall_decisions Details of incoming or outgoing recall decisions
    recall_decision_admissions Admission of incoming recall decisions
    recall_decision_submissions Submission of outgoing recall decisions
    recall_reversals Details of incoming or outgoing recall reversals
    recall_reversal_admissions Admission of incoming recall reversals
    direct_debits Details of incoming or outgoing direct debits or Bacs contra
    direct_debit_admissions Admission on incoming direct debits
    direct_debit_submissions Submission of outgoing direct debits
    direct_debit_reversals Details of incoming direct debit reversal
    direct_debit_reversal_admissions Admission on incoming direct debit reversals
    direct_debit_returns Details of incoming or outgoing direct debit returns
    direct_debit_return_submissions Submission of outgoing direct debit returns
    direct_debit_return_admissions Admission of incoming direct debit returns
    mandates Details of incoming or outgoing mandates
    mandate_admissions Admission of incoming mandates
    mandate_submissions Submission of outgoing mandates
    claims Details of outgoing indemnity claims
    claim_submissions Submission of outgoing indemnity claims
    claim_reversals Details of outgoing indemnity claim reversals
    claim_reversal_submissions Submission of outgoing indemnity claim reversals
    scheme_messages Details of incoming scheme messages
    scheme_message_admissions Admission of incoming scheme messages
    reports Details of incoming reports
    report_admissions Admission of incoming reports

    Notifications

    In order to notify you of incoming payments and other asynchronous events, we use a notification mechanism that allows you to specify your own Amazon SQS queue or a webhook URL and register them for specific types of events.

    Whenever a corresponding event occurs in the system, we will post to the queue or call the webhook.

    The subscription resource allows you to manage these notification endpoints and subscribe, cancel and query existing subscriptions.

    Note that you can set up any number of notification endpoints of either type (queue or http), and filter across a number of different events

    We generally recommend the SQS option over a webhook as this is a managed, highly-available, high-throughput and persistent message bus that eliminates any delays or issues you may face if your webhook endpoint is not reachable.

    Setup

    SQS

    You can either use the AWS console or the awscli tool.

    1. Using your AWS account, create a SQS queue:

    aws sqs create-queue --queue-name acme-co --region eu-west-1

    Note that the command above sets the message size limit to the default maximum value. We do not recommend using a smaller message size limit than the maximum.

    2. Add the required permission to the queue:

    For a test environment

    aws sqs add-permission --aws-account-ids 288840537196 --actions SendMessage --queue-url https://eu-west-1.queue.amazonaws.com/288840537196/acme-co --label foo --region eu-west-1

    For a production environment

    aws sqs add-permission --aws-account-ids 124201431238 --actions SendMessage --queue-url https://eu-west-1.queue.amazonaws.com/288840537196/acme-co --label foo --region eu-west-1

    For more information about AWS permissions, see here.

    SQS with SSE (Server Side Encryption)

    1. Additionally to the steps above, when you create the SQS queue set it to use an AWS KMS Customer Master Key (CMK)

    2. Log into the AWS console, navigate to KMS, select Customer Managed Keys, select the encryption key that your notification queue is using, go to the Key Policy tab and select edit. Append the following statement block (based on the Form3 environment) into existing policy AWS created for you:

    For the staging environment:

    { "Sid": "Enable Form3", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::288840537196:root" }, "Action": [ "kms:Decrypt", "kms:GenerateDataKey*" ], "Resource": "*" }

    For the production environment:

    { "Sid": "Enable Form3", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::124201431238:root" }, "Action": [ "kms:Decrypt", "kms:GenerateDataKey*" ], "Resource": "*" }

    This enables the Form3 notification service to send messages to the encrypted SQS queue.

    3. Your service that consumes the SQS queue will also need the same KMS permissions to read the messages.

    Webhooks

    The notification service uses uses mutual TLS authentication to ensure that the notifications you receive are from Form3. The diagram below shows the authentication process between Form3 and the webhook.

    Description of the Form3 webhook scheme

    When hosting your own webhook service for us to call, we require that you use a valid certificate signed by a reputable certification authority.

    Form3 validates the certificate based on the following criteria:

    Reputable certificate providers include:

    See here for a full list of certification authorities that we trust.

    Our client certificate details

    Staging environment
    X509 Attribute Value
    Subject
    C=GB, L=London, O=Back Office Technology Limited, OU=Back Office Technology Web Services, CN=api.staging-form3.tech
    Subject (nginx format)
    CN=api.staging-form3.tech,OU=Back Office Technology Web Services,O=Back Office Technology Limited,L=London,C=GB
    Production environment
    X509 Attribute Value
    Subject
    C=GB, L=London, O=Back Office Technology Limited, OU=Back Office Technology Web Services, CN=api.form3.tech
    Subject (nginx format)
    CN=api.form3.tech,OU=Back Office Technology Web Services,O=Back Office Technology Limited,L=London,C=GB

    We have published our full certificate bundle for your convenience, should you require it: Form3 client certificate CA chain file.

    Here are a list of code examples that shows you how to validate certificates:

    Handling delivery errors

    In case a notification cannot be successfully delivered to a webhook or queue, Form3 will retry delivery using an exponential backoff algorithm that increases the delay between retries with every failed delivery. Webhooks must respond with an HTTP success status (2XX) to indicate successful receipt of the notification.

     Exponential backoff

    Notification delivery is retried 10 times. The maximum delay time before the 10th attempt is 15 minutes. The table below lists the time delays before each retry:

    Number of retry Time delay before retry
    1 1.75s
    2 3.5s
    3 7.0s
    4 14s
    5 28s
    6 56s
    7 1m 52s
    8 3m 44s
    9 7m 28s
    10 14m 56s

    The delay is calculated based on the following formula:

    delay = 2^retryCount * 900 / 2^(9)

    with retryCount being the number of the current try (0 <= retryCount <= 9).

    After the 10th unsuccessful retry, the subscription is deactivated and the deactivated attribute of the Subscription resource is set to true. All notifications for a deactivated subscription are stored for future delivery.

    Reactivate subscriptions

    To re-activate a subscription, update the Subscription resource and set the deactivated attribute to false. Once a subscription becomes active again, all notifications that have been stored for it are sent to the callback endpoint.

    Subscriptions

    Resource

    Example subscription

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "callback_uri": "https://example.com/webhook/inbound_credit_callback",
          "callback_transport": "http",
          "user_id": "ab57e61b-1df4-46d3-8432-6eac5098a9c3",
          "event_type": "created",
          "record_type": "payments",
          "deactivated": false,
          "filter": "data.attributes.payment_scheme: BACS"
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "callback_uri": "https://example.com/webhook/inbound_credit_callback",
          "callback_transport": "http",
          "user_id": "ab57e61b-1df4-46d3-8432-6eac5098a9c3",
          "event_type": "created",
          "record_type": "payments",
          "deactivated": false,
          "filter": "data.attributes.payment_scheme: BACS"
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "callback_uri": "https://example.com/webhook/inbound_credit_callback",
          "callback_transport": "http",
          "user_id": "ab57e61b-1df4-46d3-8432-6eac5098a9c3",
          "event_type": "created",
          "record_type": "payments",
          "deactivated": false,
          "filter": "data.attributes.payment_scheme: BACS"
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    

    A Subscription is used be get notified of a specific type of event (create, delete, etc.) happening to a type of resource (Payment Admission, Payment Return Admission, etc.).

    Attribute Description
    callback_uri string, URL URI on the platform that is called when an event occurs, e.g. https://example.com/webhook/event_callback. If callback_transport is queue, this needs to be a valid Amazon SQS queue URL.
    callback_transport string, callback type Type of callback channel used. Either http or queue.
    user_id string, unique identifier (UUID), read only User ID of the user this subscription is mapped to
    event_type string The type of event the subscription is for. See: event types
    record_type string The type of resource the subscription is for. See: record types
    deactivated boolean Indicator if subscription is active or not. false when active, true when deactivated.
    filter string The filter to be applied when publishing notifications to subscription endpoints. See: filters

    Create

    Example request

    POST /v1/notification/subscriptions HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
          "callback_transport" : "http",
          "event_type": "created",
          "record_type" : "payment_admissions"
        }
      }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/notification/subscriptions
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
          "callback_transport" : "http",
          "event_type": "created",
          "record_type" : "payment_admissions"
        }
      }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'type': 'Subscription',
        'id': '5c5e70d1-052b-4ad4-8463-1153ba9b03c3',
        'organisation_id': '743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb',
        'attributes': {
          'callback_uri' : 'https://example.com/webhook/inbound_credit_callback',
          'callback_transport' : 'http',
          'event_type': 'created',
          'record_type' : 'payment_admissions'
        }
      }
    }
    """
    req = requests.post('https://api.form3.tech/v1/notification/subscriptions', json=json, headers=headers)
    print(req.json())
    

    Example response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "version": 0
        "attributes": {
          "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
          "callback_transport" : "http",
          "event_type": "created",
          "record_type" : "payment_admissions",
          "deactivated": false
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "version": 0
        "attributes": {
          "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
          "callback_transport" : "http",
          "event_type": "created",
          "record_type" : "payment_admissions",
          "deactivated": false
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "version": 0
        "attributes": {
          "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
          "callback_transport" : "http",
          "event_type": "created",
          "record_type" : "payment_admissions",
          "deactivated": false
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    

    Create a new subscription. You can create multiple subscriptions per event type or resource type.

    HTTP Request

    POST /v1/notification/subscriptions

    Request Body

    Attribute Description
    callback_uri string, URL required URI on the platform that will be called when an event occurs, e.g. https://example.com/webhook/event_callback. If callback_transport is queue, this needs to be a valid Amazon SQS queue URL.
    callback_transport string required Type of callback channel used. Either http or queue.
    event_type string required The type of event the subscription is for. See: event types
    record_type string required The type of resource the subscription is for. See: record types
    filter string optional The filter to be applied when publishing notifications to subscription endpoints. See: filters

    Response Body

    See Fetch call for a list of response body attributes.

    Fetch

    Example request

    GET v1/notification/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/notification/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/notification/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3', headers=headers)
    print(req.json())
    

    Example response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "callback_uri": "https://example.com/webhook/inbound_credit_callback",
          "callback_transport": "http",
          "user_id": "ab57e61b-1df4-46d3-8432-6eac5098a9c3",
          "event_type": "created",
          "record_type": "payments",
          "deactivated": false,
          "filter": "data.attributes.payment_scheme: BACS"
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "callback_uri": "https://example.com/webhook/inbound_credit_callback",
          "callback_transport": "http",
          "user_id": "ab57e61b-1df4-46d3-8432-6eac5098a9c3",
          "event_type": "created",
          "record_type": "payments",
          "deactivated": false,
          "filter": "data.attributes.payment_scheme: BACS"
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "callback_uri": "https://example.com/webhook/inbound_credit_callback",
          "callback_transport": "http",
          "user_id": "ab57e61b-1df4-46d3-8432-6eac5098a9c3",
          "event_type": "created",
          "record_type": "payments",
          "deactivated": false,
          "filter": "data.attributes.payment_scheme: BACS"
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    

    Get a single subscription using the subscription ID.

    HTTP Request

    GET /v1/notification/subscriptions/{id}

    URL Parameter Description
    id string, unique identifier (UUID) required Subscription ID of subscription to fetch

    Response Body

    Attribute Description
    callback_uri string, URL always URI on the platform that is called when an event occurs, e.g. https://example.com/webhook/event_callback
    callback_transport string, callback type always Type of callback channel used. Either http or queue.
    user_id string, unique identifier (UUID) ID of the user this subscription is mapped to
    event_type string always The type of event the subscription is for. See: event types
    record_type string always The type of resource the subscription is for. See: record types
    deactivated boolean always Indicator if subscription is active. false when active, true when deactivated.
    filter string sometimes The filter to be applied when publishing notifications to subscription endpoints. See: filters

    List

    Example request

    GET /v1/notification/subscriptions?page[number]=3&page[size]=2 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/notification/subscriptions?page[number]=3&page[size]=2 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/notification/subscriptions?page[number]=3&page[size]=2', headers=headers)
    print(req.json())
    

    Example response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": [
        {
          "type": "Subscription",
          "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
          "attributes": {
            "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
            "callback_transport" : "http",
            "event_type": "created",
            "record_type" : "payment_admissions",
            "deactivated": false
          }
        },
        {
          "type": "Subscription",
          "id": "12c82520-3ae8-47d4-9e85-20f8a2c58c0a",
          "attributes": {
            "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
            "callback_transport" : "http",
            "event_type": "updated",
            "record_type" : "payment_admissions"
            "deactivated": true
          }
        }
      ],
      "links": {
        "self": "/subscriptions?page[number]=3&page[size]=2",
        "first": "/subscriptions?page[number]=1&page[size]=2",
        "prev": "/subscriptions?page[number]=2&page[size]=2",
        "next": "/subscriptions?page[number]=4&page[size]=2",
        "last": "/subscriptions?page[number]=13&page[size]=2"
      }
    }
    
    {
      "data": [
        {
          "type": "Subscription",
          "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
          "attributes": {
            "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
            "callback_transport" : "http",
            "event_type": "created",
            "record_type" : "payment_admissions",
            "deactivated": false
          }
        },
        {
          "type": "Subscription",
          "id": "12c82520-3ae8-47d4-9e85-20f8a2c58c0a",
          "attributes": {
            "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
            "callback_transport" : "http",
            "event_type": "updated",
            "record_type" : "payment_admissions"
            "deactivated": true
          }
        }
      ],
      "links": {
        "self": "/subscriptions?page[number]=3&page[size]=2",
        "first": "/subscriptions?page[number]=1&page[size]=2",
        "prev": "/subscriptions?page[number]=2&page[size]=2",
        "next": "/subscriptions?page[number]=4&page[size]=2",
        "last": "/subscriptions?page[number]=13&page[size]=2"
      }
    }
    
    {
      "data": [
        {
          "type": "Subscription",
          "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
          "attributes": {
            "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
            "callback_transport" : "http",
            "event_type": "created",
            "record_type" : "payment_admissions",
            "deactivated": false
          }
        },
        {
          "type": "Subscription",
          "id": "12c82520-3ae8-47d4-9e85-20f8a2c58c0a",
          "attributes": {
            "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
            "callback_transport" : "http",
            "event_type": "updated",
            "record_type" : "payment_admissions"
            "deactivated": true
          }
        }
      ],
      "links": {
        "self": "/subscriptions?page[number]=3&page[size]=2",
        "first": "/subscriptions?page[number]=1&page[size]=2",
        "prev": "/subscriptions?page[number]=2&page[size]=2",
        "next": "/subscriptions?page[number]=4&page[size]=2",
        "last": "/subscriptions?page[number]=13&page[size]=2"
      }
    }
    

    List subscriptions with the ability to filter and page.

    HTTP Request

    GET /v1/notification/subscriptions?page[number]={page_number}&page[size]={page_size}&filter[{attribute}]={filter_value}

    Page parameters

    All parameters are optional.

    Parameter Default Description
    page[number] 0 Page number being requested
    page[size] 100 Size of the page being requested
    filter Filter subscriptions returned. See: filter parameters

    Filter parameters

    Attribute Description
    filter[event_type] Find all subscriptions for a particular event type

    Response Body

    Attribute Description
    data array of resources Subscription resources matching the paging and filter terms. See Fetch call for a list of resource attributes.
    always

    Patch

    Modify an existing Subscription resource. Can be used to re-activate a deactivated subscription after a timeout for notification delivery occured.

    Example request

    PATCH /v1/notification/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3 HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "version": 2,
        "attributes": {
          "deactivated": false
        }
      }
    }
    
    curl -X PATCH -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/notification/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "version": 2,
        "attributes": {
          "deactivated": false
        }
      }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'type': 'Subscription',
        'id': '5c5e70d1-052b-4ad4-8463-1153ba9b03c3',
        'organisation_id': '743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb',
        'version': 2,
        'attributes': {
          'deactivated': false
        }
      }
    }
    """
    req = requests.patch('https://api.form3.tech/v1/notification/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "version": 3
        "attributes": {
          "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
          "callback_transport" : "http",
          "event_type": "created",
          "record_type" : "payment_admissions",
          "deactivated": false
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "version": 3
        "attributes": {
          "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
          "callback_transport" : "http",
          "event_type": "created",
          "record_type" : "payment_admissions",
          "deactivated": false
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    
    {
      "data": {
        "type": "Subscription",
        "id": "5c5e70d1-052b-4ad4-8463-1153ba9b03c3",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "version": 3
        "attributes": {
          "callback_uri" : "https://example.com/webhook/inbound_credit_callback",
          "callback_transport" : "http",
          "event_type": "created",
          "record_type" : "payment_admissions",
          "deactivated": false
        }
      },
      "links": {
        "self": "/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3"
      }
    }
    

    HTTP Request

    PATCH /v1/notification/subscriptions/{subscription_id}

    URL Parameter Description
    subscription_id string, unique identifier (UUID) required ID of the subscription to be patched

    Request Body

    Attribute Description
    version integer required Version number of the resource to patch. Has to be the latest version of the resource.
    Note that the attribute is located on the top level of the resource, not on the attributes sub level (see code example).
    callback_uri string, URL optional URI on the platform that will be called when an event occurs, e.g. https://example.com/webhook/event_callback. If callback_transport is queue, this needs to be a valid Amazon SQS queue URL.
    callback_transport string optional Type of callback channel used. Either http or queue.
    event_type string optional The type of event the subscription is for. See: event types
    record_type string optional The type of resource the subscription is for. See: record types
    deactivated boolean optional Indicator if subscription is active. Change to false to reactivate a deactivated subscription.
    filter string optional The filter to be applied when publishing notifications to subscription endpoints. See: filters

    Response Body

    See Fetch call for a list of response body attributes.

    Delete

    Delete a subcription. Note that all queued notifications associated with that subscription will also be deleted.

    Example request

    DELETE /v1/notification/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3?version=0 HTTP/1.1
    
    curl -X DELETE https://api.form3.tech//v1/notification/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3?version=0
    
    import requests
    requests.delete('https://api.form3.tech//v1/notification/subscriptions/5c5e70d1-052b-4ad4-8463-1153ba9b03c3?version=0')
    

    Response (204 No Content)

    HTTP Request

    DELETE /v1/notification/subscriptions/{subscription_id}?version={version}

    URL Parameter Description
    subscription_id string, unique identifier (UUID) required ID of the subscription to be deleted
    version integer required Version number of record

    HTTP Response

    Code Meaning Description
    204 No Content Resource has been successfully deleted
    404 Not Found Specified resource does not exist
    409 Conflict Specified version incorrect

    Events

    Whenever an event occurs, Form3 sends out a notification to subscribers for the specific event_type and record_type. All resources publish a set of standard events on certain actions such as resource creation and deletion. See below for a complete list of event types and record types.

    Event types

    Below is a list of event types that you can subscribe to be notified about.

    Value Description
    created A resource has been created
    updated A resource has been updated
    deleted A resource has been deleted

    Record types

    Record types define the type of resource that is triggering an event and are the same as the type property of a resource. You also have to provide a record type when subscribing for an event. Below is a list of record types that you can subscribe for.

    Value Description
    payments Details of incoming and outgoing payments or certain Bacs contra records
    payment_admissions Admission of incoming payments
    payment_submissions Submission of outgoing payments
    returns Details of incoming and outgoing returns
    return_admissions Admission of incoming returns
    return_submissions Submission of outgoing returns
    return_reversals Details of incoming and outgoing return reversals
    return_reversal_admissions Admission of incoming return reversals
    reversals Details of incoming or outgoing reversals
    reversal_admissions Admission of incoming reversals
    reversal_submissions Submission of outgoing reversals
    recalls Details of incoming or outgoing recalls
    recall_submissions Submission of outgoing recalls
    recall_admissions Admission of incoming recalls
    recall_decisions Details of incoming or outgoing recall decisions
    recall_decision_admissions Admission of incoming recall decisions
    recall_decision_submissions Submission of outgoing recall decisions
    recall_reversals Details of incoming or outgoing recall reversals
    recall_reversal_admissions Admission of incoming recall reversals
    direct_debits Details of incoming or outgoing direct debits or Bacs contra
    direct_debit_admissions Admission on incoming direct debits
    direct_debit_submissions Submission of outgoing direct debits
    direct_debit_reversals Details of incoming direct debit reversal
    direct_debit_reversal_admissions Admission on incoming direct debit reversals
    direct_debit_returns Details of incoming or outgoing direct debit returns
    direct_debit_return_submissions Submission of outgoing direct debit returns
    direct_debit_return_admissions Admission of incoming direct debit returns
    mandates Details of incoming or outgoing mandates
    mandate_admissions Admission of incoming mandates
    mandate_submissions Submission of outgoing mandates
    claims Details of outgoing indemnity claims
    claim_submissions Submission of outgoing indemnity claims
    claim_reversals Details of outgoing indemnity claim reversals
    claim_reversal_submissions Submission of outgoing indemnity claim reversals
    scheme_messages Details of incoming scheme messages
    scheme_message_admissions Admission of incoming scheme messages
    reports Details of incoming reports
    report_admissions Admission of incoming reports

    Filters

    Subscription for updating Payment Admissions to failed only

    {
      "type": "Subscription",
        "id": "d2e7b28a-e55f-4ebc-96e5-eb76638641bd",
        "version": 0,
        "organisation_id": "f9cba008-2637-41e9-bce4-1957aa8db422",
        "attributes": {
          "callback_uri": "https://example.com/webhook/failed_inbound_failed_callback",
          "callback_transport": "http",
          "user_id": "8052596b-c08a-45f2-8084-413d0d1401bf",
          "event_type": "updated",
          "record_type": "payment_admissions",
          "deactivated": false,
          "filter": "data.attributes.status: failed"
        }
    }
    

    Notification that matches the filter for failed Payment Admissions

    {
      "id": "5e6dcda7-1915-4d14-a7c4-db1392935d87",
      "organisation_id": "814cacf5-82ec-4387-ad70-7c961f481ac0",
      "event_type": "created",
      "record_type": "payment_admissions",
      "data_record_type": "PaymentAdmission",
      "data": {
        "data": {
          (...)
          "attributes": {
            "status": "failed",
            (...)
          }
        }
      }
    }
    

    Subscription for FPS Admissions only

    {
      "type": "Subscription",
        "id": "7891dea3-f954-4455-8545-a2c5d938ea24",
        "version": 0,
        "organisation_id": "0a3a6dd2-152d-4916-a5c4-729817dcc618",
        "attributes": {
          "callback_uri": "https://example.com/webhook/fps_admissions",
          "callback_transport": "http",
          "user_id": "c8f8cce9-5b61-4a75-ac12-7ed28c26bbe0",
          "event_type": "updated",
          "record_type": "payment_admissions",
          "deactivated": false,
          "filter": "data.relationships.payment.data.attributes.payment_scheme: FPS"
        }
    }
    

    Notification matching filter for FPS-only Admissions

    {
      "id": "a09202fc-ac79-4a08-9cd9-76af90247a96",
      "organisation_id": "814cacf5-82ec-4387-ad70-7c961f481ac0",
      "event_type": "created",
      "record_type": "payment_admissions",
      "data_record_type": "PaymentAdmission",
      "data": {
        "data": {
          "type": "payment_admissions",
          "id": "5fae9019-6668-4849-9dac-e40e72aba25c",
          "version": 0,
          "organisation_id": "814cacf5-82ec-4387-ad70-7c961f481ac0",
          "attributes": {
            (...)
          },
          "relationships": {
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "c64dba05-ef1e-4912-821e-efb8178bdbf4",
                  "version": 0,
                  "organisation_id": "814cacf5-82ec-4387-ad70-7c961f481ac0",
                  "attributes": {
                    (...)
                    "payment_scheme": "FPS",
                  }
                }
              ]
            }
          }
        }
      }
    }
    

    The filter attribute in the Subscription resource allows to add additional conditions for when a notification is sent.

    If the filter attribute is set, the notification is only sent if the attribute-value pair defined in the filter is present in the notification.

    Filters can be set for any attribute of the resource the notification message is sent for. This includes linked resources listed in the relationships section of a resource.

    The syntax for using the filter attribute is as follows:
    "filter": "path.to.attribute: value_to_match"

    For example, a filter value of data.attributes.status: validation_passed will only allow notifications of events that have a status of validation_passed in the data.attributes.status field to be sent.

    Nested arrays

    Filters can also be used to access fields that are located inside arrays of nested resources. This is particularly useful for filtering on the payment_scheme field for a record of type of payment_admissions and an event type of updated which is located in the relationships section of the notification (see example).

    Common use cases

    Using multiple subscriptions for the same record_type and event_type in combination with filters is a useful way to route the flow of notifications into topic-based channels.

    Common subscription routings include:

    All filter queries are case insensitive, thus these two filter expressions are equivalent: data.attributes.payment_scheme: bacs and data.attributes.payment_scheme: BACS.

    To filter on fields containing multiple words, the value to match must be provided in escaped quotes: path.to.attribute.value: \"some value\"

    Event notification format

    Example event payment admission with payment in relationship section

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "id": "9c2e4b09-0405-483d-92d6-6a37af9a5e4b",
      "organisation_id": "a95c9c69-a4ab-49bc-bfc4-ad78d3a3d178",
      "event_type": "created",
      "record_type": "payment_admissions",
      "data_record_type": "PaymentAdmission",
      "version": 0,
      "data": {
        "data": {
          "type": "payment_admissions",
          "id": "14048b5a-88f5-4586-aec7-603703ada3ae",
          "version": 0,
          "organisation_id": "a95c9c69-a4ab-49bc-bfc4-ad78d3a3d178",
          "attributes": {
            "status": "confirmed",
            "status_reason": "accepted",
            "admission_datetime": "2019-07-30T16:35:57.421Z",
            "settlement_date": "2019-07-30",
            "settlement_cycle": 1
          },
          "relationships": {
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "107812e8-955e-4eec-9f1f-dfbe4e391482",
                  "version": 0,
                  "organisation_id": "a95c9c69-a4ab-49bc-bfc4-ad78d3a3d178",
                  "created_on": "2019-07-30T16:35:57.380Z",
                  "modified_on": "2019-07-30T16:35:57.380Z",
                  "attributes": {
                    "amount": "600.00",
                    "beneficiary_party": {
                      "account_name": "Mr Sending Test",
                      "account_number": "20621803",
                      "account_number_code": "BBAN",
                      "account_type": 1,
                      "account_with": {
                        "bank_id": "112233",
                        "bank_id_code": "GBDSC"
                      }
                    },
                    "charges_information": {
                      "bearer_code": "SHAR"
                    },
                    "currency": "GBP",
                    "debtor_party": {
                      "account_name": "Mrs Receiving Test",
                      "account_number": "71268996",
                      "account_number_code": "BBAN",
                      "account_with": {
                        "bank_id": "400302",
                        "bank_id_code": "GBDSC"
                      }
                    },
                    "end_to_end_reference": "NOREF",
                    "numeric_reference": "0001",
                    "scheme_transaction_id": "00865465238980327",
                    "unique_scheme_id": "00865465238980327 1020190730826400302",
                    "payment_purpose": "X",
                    "payment_scheme": "FPS",
                    "payment_type": "Credit",
                    "processing_date": "2019-07-30",
                    "reference": "1112223330",
                    "scheme_payment_sub_type": "TelephoneBanking",
                    "scheme_payment_type": "ImmediatePayment"
                  }
                }
              ]
            }
          }
        }
      }
    }
    
    {
      "id": "9c2e4b09-0405-483d-92d6-6a37af9a5e4b",
      "organisation_id": "a95c9c69-a4ab-49bc-bfc4-ad78d3a3d178",
      "event_type": "created",
      "record_type": "payment_admissions",
      "data_record_type": "PaymentAdmission",
      "version": 0,
      "data": {
        "data": {
          "type": "payment_admissions",
          "id": "14048b5a-88f5-4586-aec7-603703ada3ae",
          "version": 0,
          "organisation_id": "a95c9c69-a4ab-49bc-bfc4-ad78d3a3d178",
          "attributes": {
            "status": "confirmed",
            "status_reason": "accepted",
            "admission_datetime": "2019-07-30T16:35:57.421Z",
            "settlement_date": "2019-07-30",
            "settlement_cycle": 1
          },
          "relationships": {
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "107812e8-955e-4eec-9f1f-dfbe4e391482",
                  "version": 0,
                  "organisation_id": "a95c9c69-a4ab-49bc-bfc4-ad78d3a3d178",
                  "created_on": "2019-07-30T16:35:57.380Z",
                  "modified_on": "2019-07-30T16:35:57.380Z",
                  "attributes": {
                    "amount": "600.00",
                    "beneficiary_party": {
                      "account_name": "Mr Sending Test",
                      "account_number": "20621803",
                      "account_number_code": "BBAN",
                      "account_type": 1,
                      "account_with": {
                        "bank_id": "112233",
                        "bank_id_code": "GBDSC"
                      }
                    },
                    "charges_information": {
                      "bearer_code": "SHAR"
                    },
                    "currency": "GBP",
                    "debtor_party": {
                      "account_name": "Mrs Receiving Test",
                      "account_number": "71268996",
                      "account_number_code": "BBAN",
                      "account_with": {
                        "bank_id": "400302",
                        "bank_id_code": "GBDSC"
                      }
                    },
                    "end_to_end_reference": "NOREF",
                    "numeric_reference": "0001",
                    "scheme_transaction_id": "00865465238980327",
                    "unique_scheme_id": "00865465238980327 1020190730826400302",
                    "payment_purpose": "X",
                    "payment_scheme": "FPS",
                    "payment_type": "Credit",
                    "processing_date": "2019-07-30",
                    "reference": "1112223330",
                    "scheme_payment_sub_type": "TelephoneBanking",
                    "scheme_payment_type": "ImmediatePayment"
                  }
                }
              ]
            }
          }
        }
      }
    }
    
    {
      "id": "9c2e4b09-0405-483d-92d6-6a37af9a5e4b",
      "organisation_id": "a95c9c69-a4ab-49bc-bfc4-ad78d3a3d178",
      "event_type": "created",
      "record_type": "payment_admissions",
      "data_record_type": "PaymentAdmission",
      "version": 0,
      "data": {
        "data": {
          "type": "payment_admissions",
          "id": "14048b5a-88f5-4586-aec7-603703ada3ae",
          "version": 0,
          "organisation_id": "a95c9c69-a4ab-49bc-bfc4-ad78d3a3d178",
          "attributes": {
            "status": "confirmed",
            "status_reason": "accepted",
            "admission_datetime": "2019-07-30T16:35:57.421Z",
            "settlement_date": "2019-07-30",
            "settlement_cycle": 1
          },
          "relationships": {
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "107812e8-955e-4eec-9f1f-dfbe4e391482",
                  "version": 0,
                  "organisation_id": "a95c9c69-a4ab-49bc-bfc4-ad78d3a3d178",
                  "created_on": "2019-07-30T16:35:57.380Z",
                  "modified_on": "2019-07-30T16:35:57.380Z",
                  "attributes": {
                    "amount": "600.00",
                    "beneficiary_party": {
                      "account_name": "Mr Sending Test",
                      "account_number": "20621803",
                      "account_number_code": "BBAN",
                      "account_type": 1,
                      "account_with": {
                        "bank_id": "112233",
                        "bank_id_code": "GBDSC"
                      }
                    },
                    "charges_information": {
                      "bearer_code": "SHAR"
                    },
                    "currency": "GBP",
                    "debtor_party": {
                      "account_name": "Mrs Receiving Test",
                      "account_number": "71268996",
                      "account_number_code": "BBAN",
                      "account_with": {
                        "bank_id": "400302",
                        "bank_id_code": "GBDSC"
                      }
                    },
                    "end_to_end_reference": "NOREF",
                    "numeric_reference": "0001",
                    "scheme_transaction_id": "00865465238980327",
                    "unique_scheme_id": "00865465238980327 1020190730826400302",
                    "payment_purpose": "X",
                    "payment_scheme": "FPS",
                    "payment_type": "Credit",
                    "processing_date": "2019-07-30",
                    "reference": "1112223330",
                    "scheme_payment_sub_type": "TelephoneBanking",
                    "scheme_payment_type": "ImmediatePayment"
                  }
                }
              ]
            }
          }
        }
      }
    }
    

    Event notifications contain information about the event type and record type, as well as the resource that has changed.

    Attribute Description
    id string, unique identifier (UUID) always The ID of the notification
    organisation_id string, unique identifier (UUID) always The ID of the organisation that this notification belongs to. This is usually the organisation ID of your organisation.
    event_type string always The type of event, e.g. created, updated
    record_type string always The type of resource that has changed, e.g. payments, payment_admissions
    data_record_type string always Internal representation of the record type. Field values are subject to frequent change, evaluation of this field is discouraged.
    data resource always The resource this notification is for.

    For Submission and Admission resources, the relationships section links the full related resource, not only the type and id as in some GET requests.

    Common event subscriptions

    The table below lists the most common actions and the corresponding event_type and record_type combinations to subscribe to them. Note that you will most likely only need to subscribe to a subset of the events listed below, depending on the scheme you're implementing and the type of scheme access you use.

    Action Event Type Record Type
    Receive updates on the status of outbound payments updated payment_submissions
    Receive updates on payment attributes assigned by the scheme (e.g. unique_scheme_id for FPS) updated payments
    Get notified upon arrival of inbound payments or receipt of money (such as Bacs contra records) created payment_admissions
    Receive updates on the status of outbound payment returns updated return_submissions
    Get notified upon arrival of inbound returns of payments sent created return_admissions
    Receive updates on the status of outbound payment reversals (Bacs only) updated reversal_submissions
    Get notified upon arrival of inbound reversals of payments you have previously received created reversal_admissions
    Get notified upon arrival of inbound return reversals of a returned payment you have previously received created return_reversal_admissions
    Get notified upon arrival of inbound scheme messages (FPS only) created scheme_message_admissions
    Receive updates on the status of payments you have recalled (SEPA only) updated recall_submissions
    Get notified upon arrival of inbound recalls for payments you have received (SEPA only) created recall_admissions
    Receive updates on the status of recall decisions you have sent (SEPA only) updated recall_decision_submissions
    Get notified upon arrival of inbound decisions to recalls you have made (SEPA only) created recall_decision_admissions
    Receive updates on the status on outbound AWACS advides (Bacs only) updated payment_advice_submissions
    Get notified upon arrival of inbound direct debits and contra records for failed outbound direct debits (Bacs only) created direct_debit_admissions
    Get notified upon arrival of inbound direct debit reversals (Bacs only) created direct_debit_reversal_admissions
    Receive updates on the status on outbound direct debit reversal returns (Bacs only) updated direct_debit_reversal_submissions
    Get notified upon arrival of inbound direct debit returns (ARUDDs) (Bacs only) created direct_debit_return_admissions
    Receive updates on the status of outbound direct debit returns (ARUDD) (Bacs only) updated direct_debit_return_submissions
    Receive updates on whether mandate requests have been successfully submitted to the scheme (Bacs only) updated mandate_submissions
    Get notified upon arrival of inbound mandate requests (Bacs only) created mandate_admissions
    Receive updates on the status of a mandate request returned to the scheme (Bacs only) updated mandate_return_submissions
    Receive updates on the status on outbound indemnity claims (Bacs only) updated claim_submissions
    Receive updates on the status on outbound indemnity claim reversals (Bacs only) updated claim_reversal_submissions

    Note that some payment events also include additional metadata to link between different resources. For example, a Payment Admission resource will link to the Payment resource it refers to.

    Likewise, a Reversal Admission will include a link to both a Payment resource as well as a Reversal resource if the event is the reversal of a return. See the respective resource definitions for more information.

    Reports

    Reports are used to provide summaries of a variety of events such as sent or received transaction, as well as payment instructions that were amended, rejected or returned. They can be provided by the scheme, Form3, or other entities.

    There can be multiple formats for a report. These formats are listed in the formats attribute of the Reports resource.

    Download a report

    Example download request

    GET /v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a HTTP/1.1
    Accept: application/pdf
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a \
       -H "Accept: application/pdf" --output report.pdf
    
    import requests
    headers = {
        'authorization': "bearer YOUR_TOKEN_HERE",
        'accept': "application/pdf",
        }
    req = requests.get('https://api.form3.tech/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a', headers=headers)
    open('report.pdf', 'wb').write(req.content)
    

    Response (200 OK)

    To download a report in a given format, perform a GET request on the URL provided in the links.{format}.href attribute of the Reports resource. Use the value from links.{format}.meta.content-type in the Accept header of the request to get the desired format.

    Reports

    Resource

    Example report resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
       "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_SERVICE_USER",
              "formats": [
                  "xml",
                  "zipped_xhtml"
              ]
          },    
          "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"
          },
          "xml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
       }   
    }
    
    
    {
       "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_SERVICE_USER",
              "formats": [
                  "xml",
                  "zipped_xhtml"
              ]
          },    
          "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"
          },
          "xml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
       }   
    }
    
    
    {
       "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_SERVICE_USER",
              "formats": [
                  "xml",
                  "zipped_xhtml"
              ]
          },    
          "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"
          },
          "xml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
       }   
    }
    
    
    Attribute Description
    report_type string The type of report, usually a scheme-specific code

    FPS: The FPS report type, see the tables for Settling Participants or Non-Settling Participants for possible values.

    FPS MIDEP: The MIDEP report direction. See the table for MIDEP reports for more information.

    Bacs: The Bacs report type, see the list of Bacs reports for possible values.

    SEPA Instant & SCT: The SEPA report type, see the list of SEPA Instant or SCT reports for possible values.
    report_type_description string Description of the type of report

    FPS: The name of the report, see the tables for Settling Participants or Non-Settling Participants for possible values.

    FPS MIDEP: Scheme-compatible name for this part of the report in format DIRECTION-ID-DATE-TIME-x-of-y where DIRECTION is either SENT or RECEIVED, ID is the FPS Participant ID, DATE is in format yyyymmdd, TIME is in format hhmm and x and y denote which part of the report this particular entry represents.

    Bacs: The name of the Bacs report, see the list of Bacs reports for possible values.

    SEPA Instant & SCT: Description of the type of report, see the list of SEPA Instant or SCT reports for possible values.
    generation_time datetime Datetime on which the report file was generated
    processing_date date Date of the business day on which the report was processed
    report_source string Scheme source responsible for generating the report

    FPS: Always FPS

    FPS MIDEP: Always FPS_MIDEP

    Bacs: Always BACS_SERVICE_USER

    SEPA Instant & SCT: Always SEPA Instant for Instant, SEPA SCT for Credit Transfer
    formats array of strings File formats in which the report is available. Each value can be used as a key to get a link to download the report (see links)

    FPS: See the tables for Settling Participants or Non-Settling Participants for possible values.

    FPS MIDEP: See the tables for MIDEP Reports for possible values.

    Bacs: See the list of Bacs reports for possible values.

    SEPA Instant & SCT: See the list of SEPA Instant or SCT reports for possible values.
    relationships.report_admission resource Report Admission resource that relates to the report
    links.{format}.href string Download link for the report in the given format. See format attribute for available values for {format}.
    links.{format}.meta.content-type string Content type to use in the HTML request header when downloading a report. See format attribute for available values for {format}.

    Fetch

    Example request

    GET v1/notification/reports/3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/notification/reports/3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/notification/reports/3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
       "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_SERVICE_USER",
              "formats": [
                  "xml",
                  "zipped_xhtml"
              ]
          },    
          "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"
          },
          "xml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
       }   
    }
    
    
    {
       "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_SERVICE_USER",
              "formats": [
                  "xml",
                  "zipped_xhtml"
              ]
          },    
          "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"
          },
          "xml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
       }   
    }
    
    
    {
       "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_SERVICE_USER",
              "formats": [
                  "xml",
                  "zipped_xhtml"
              ]
          },    
          "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"
          },
          "xml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
       }   
    }
    
    

    Get a report using the report ID.

    HTTP Request

    GET v1/notification/reports/{report_id}

    URL Parameter Description
    report_id string, unique identifier (UUID) ID of the report to fetch
    Headers Description
    accepted mime type MimeType used to specify the expected report format. If not specified or application/vnd.api+json is used, the resource payload is returned.

    Response Body

    Attribute Description
    report_type string The type of report, usually a scheme-specific code

    FPS: The FPS report type, see the tables for Settling Participants or Non-Settling Participants for possible values.
    always

    FPS MIDEP: The MIDEP report direction. See the table for MIDEP reports for more information.
    always

    Bacs: The Bacs report type, see the list of Bacs reports for possible values.
    always

    SEPA Instant & SCT: The SEPA report type, see the list of SEPA Instant or SCT reports for possible values.
    always
    report_type_description string Description of the type of report

    FPS: The name of the report, see the tables for Settling Participants or Non-Settling Participants for possible values.
    always

    FPS MIDEP: Scheme-compatible name for this part of the report in format DIRECTION-ID-DATE-TIME-x-of-y where DIRECTION is either SENT or RECEIVED, ID is the FPS Participant ID, DATE is in format yyyymmdd, TIME is in format hhmm and x and y denote which part of the report this particular entry represents.
    always

    Bacs: The name of the Bacs report, see the list of Bacs reports for possible values.
    always

    SEPA Instant & SCT: Description of the type of report, see the list of SEPA Instant or SCT reports for possible values.
    always
    generation_time datetime Datetime on which the report file was generated

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

    SEPA Instant & SCT: No additional information
    always
    processing_date date Date of the business day on which the report was processed

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

    SEPA Instant & SCT: No additional information
    always
    report_source string Scheme source responsible for generating the report

    FPS: Always FPS
    always

    FPS MIDEP: Always FPS_MIDEP
    always

    Bacs: Always BACS_SERVICE_USER
    always

    SEPA Instant & SCT: Always SEPA Instant for Instant, SEPA SCT for Credit Transfer
    always
    formats array of strings File formats in which the report is available. Each value can be used as a key to get a link to download the report (see links)

    FPS: See the tables for Settling Participants or Non-Settling Participants for possible values.
    always

    FPS MIDEP: See the tables for MIDEP Reports for possible values.
    always

    Bacs: See the list of Bacs reports for possible values.
    always

    SEPA Instant & SCT: See the list of SEPA Instant or SCT reports for possible values.
    always
    relationships.report_admission resource Report Admission resource that relates to the report

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

    SEPA Instant & SCT: No additional information
    always
    links.{format}.href string Download link for the report in the given format. See format attribute for available values for {format}.

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

    SEPA Instant & SCT: No additional information
    always
    links.{format}.meta.content-type string Content type to use in the HTML request header when downloading a report. See format attribute for available values for {format}.

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

    SEPA Instant & SCT: No additional information
    always

    List

    Example request

    GET v1/notification/reports HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/notification/reports \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/notification/reports', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
                "id": "2e885451-3089-4e84-bf0e-0646b99697c2",
                "type": "reports",
                "version": 0,
                "created_on": "2019-01-16T16:03:37.617Z",
                "modified_on": "2019-01-16T16:03:37.617Z",
                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                "attributes": {
                    "report_type": "Balance",
                    "report_type_description": "Example of a Balance Report",
                    "report_source": "FPS",
                    "generation_time": "2019-01-16T16:03:37.515Z",
                    "processing_date": "2019-01-16"
                },
                "relationships": {
                    "report_admission": {
                        "data": []
                    }
                }
            },
            {
                "id": "338a49fc-4b46-44b7-8327-5c3b77f02fd8",
                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                "type": "reports",
                "version": 1,
                "created_on": "2019-01-16T16:04:31.486Z",
                "modified_on": "2019-01-16T16:07:52.246Z",
                "attributes": {
                    "report_type": "2013",
                    "report_type_description": "AUDDIS Input",
                    "report_source": "BACS",
                    "generation_time": "2019-01-16T16:04:31.194Z",
                    "processing_date": "2019-01-16",
                    "formats": [
                        "pdf"
                    ]
                },
                "relationships": {
                    "report_admission": {
                        "data": [
                            {
                                "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                                "type": "report_admissions",
                                "version": 0,
                                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                                "created_on": "2019-01-16T16:05:03.261Z",
                                "modified_on": "2019-01-16T16:05:03.261Z",
                                "attributes": {
                                    "admission_datetime": "2019-01-16T16:05:03.261Z",
                                    "source_gateway": "StarlingGateway",
                                    "status": "delivery_confirmed"
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    
    
    {
        "data": [
            {
                "id": "2e885451-3089-4e84-bf0e-0646b99697c2",
                "type": "reports",
                "version": 0,
                "created_on": "2019-01-16T16:03:37.617Z",
                "modified_on": "2019-01-16T16:03:37.617Z",
                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                "attributes": {
                    "report_type": "Balance",
                    "report_type_description": "Example of a Balance Report",
                    "report_source": "FPS",
                    "generation_time": "2019-01-16T16:03:37.515Z",
                    "processing_date": "2019-01-16"
                },
                "relationships": {
                    "report_admission": {
                        "data": []
                    }
                }
            },
            {
                "id": "338a49fc-4b46-44b7-8327-5c3b77f02fd8",
                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                "type": "reports",
                "version": 1,
                "created_on": "2019-01-16T16:04:31.486Z",
                "modified_on": "2019-01-16T16:07:52.246Z",
                "attributes": {
                    "report_type": "2013",
                    "report_type_description": "AUDDIS Input",
                    "report_source": "BACS",
                    "generation_time": "2019-01-16T16:04:31.194Z",
                    "processing_date": "2019-01-16",
                    "formats": [
                        "pdf"
                    ]
                },
                "relationships": {
                    "report_admission": {
                        "data": [
                            {
                                "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                                "type": "report_admissions",
                                "version": 0,
                                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                                "created_on": "2019-01-16T16:05:03.261Z",
                                "modified_on": "2019-01-16T16:05:03.261Z",
                                "attributes": {
                                    "admission_datetime": "2019-01-16T16:05:03.261Z",
                                    "source_gateway": "StarlingGateway",
                                    "status": "delivery_confirmed"
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    
    
    {
        "data": [
            {
                "id": "2e885451-3089-4e84-bf0e-0646b99697c2",
                "type": "reports",
                "version": 0,
                "created_on": "2019-01-16T16:03:37.617Z",
                "modified_on": "2019-01-16T16:03:37.617Z",
                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                "attributes": {
                    "report_type": "Balance",
                    "report_type_description": "Example of a Balance Report",
                    "report_source": "FPS",
                    "generation_time": "2019-01-16T16:03:37.515Z",
                    "processing_date": "2019-01-16"
                },
                "relationships": {
                    "report_admission": {
                        "data": []
                    }
                }
            },
            {
                "id": "338a49fc-4b46-44b7-8327-5c3b77f02fd8",
                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                "type": "reports",
                "version": 1,
                "created_on": "2019-01-16T16:04:31.486Z",
                "modified_on": "2019-01-16T16:07:52.246Z",
                "attributes": {
                    "report_type": "2013",
                    "report_type_description": "AUDDIS Input",
                    "report_source": "BACS",
                    "generation_time": "2019-01-16T16:04:31.194Z",
                    "processing_date": "2019-01-16",
                    "formats": [
                        "pdf"
                    ]
                },
                "relationships": {
                    "report_admission": {
                        "data": [
                            {
                                "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                                "type": "report_admissions",
                                "version": 0,
                                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                                "created_on": "2019-01-16T16:05:03.261Z",
                                "modified_on": "2019-01-16T16:05:03.261Z",
                                "attributes": {
                                    "admission_datetime": "2019-01-16T16:05:03.261Z",
                                    "source_gateway": "StarlingGateway",
                                    "status": "delivery_confirmed"
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    
    

    List reports with the ability to filter and page.

    HTTP Request

    v1/notification/reports?page[number]={page_number}&page[size]={page_size}

    Page parameters

    All fields are optional.

    Parameter Default Description
    page[number] 0 Page number being requested (starting from zero)
    page[size] 1000 Size of the page being requested
    filter[organisation_id] Filter by organisationId
    filter[report_type] Filter by report type
    filter[report_type_description] Filter by report type description
    filter[report_source] Filter by report source
    filter[created_on_after] Request reports created after specific date time
    filter[created_on_before] Request reports created before specific date time
    filter[modified_on_after] Request reports modified after specific date time
    filter[modified_on_before] Request reports modified before specific date time

    Response Body

    Attribute Description
    data array of resources Report resources matching the paging and filter terms. See Fetch call for a list of resource attributes.
    always

    Report Admissions

    A Report Admission represents an incoming report. Subscribing to create events of report admissions is the recommended way to watch for incoming reports.

    Resource

    Example report admission resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
      "type": "report_admissions",
      "version": 0,
      "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
      "created_on": "2019-01-16T16:05:03.261Z",
      "modified_on": "2019-01-16T16:05:03.261Z",
      "attributes": {
        "admission_datetime": "2019-01-16T16:05:03.261Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "report": {
          "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"
                ]
              }
            }
          ]
        }
      }
    }
    
    
    {
      "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
      "type": "report_admissions",
      "version": 0,
      "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
      "created_on": "2019-01-16T16:05:03.261Z",
      "modified_on": "2019-01-16T16:05:03.261Z",
      "attributes": {
        "admission_datetime": "2019-01-16T16:05:03.261Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "report": {
          "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"
                ]
              }
            }
          ]
        }
      }
    }
    
    
    {
      "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
      "type": "report_admissions",
      "version": 0,
      "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
      "created_on": "2019-01-16T16:05:03.261Z",
      "modified_on": "2019-01-16T16:05:03.261Z",
      "attributes": {
        "admission_datetime": "2019-01-16T16:05:03.261Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "report": {
          "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"
                ]
              }
            }
          ]
        }
      }
    }
    
    
    Attribute Description
    admission_datetime datetime read-only Date and time the report admission was created
    status string read-only Status of the admission
    relationships.report resource read-only Report resource that relates to the admission

    Fetch

    Example request

    GET v1/notification/reports/3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99/admissions/6e782ac4-7b26-4499-8006-f787c6851456 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/notification/reports/3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99/admissions/6e782ac4-7b26-4499-8006-f787c6851456 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/notification/reports/3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99/admissions/6e782ac4-7b26-4499-8006-f787c6851456', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
      "type": "report_admissions",
      "version": 0,
      "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
      "created_on": "2019-01-16T16:05:03.261Z",
      "modified_on": "2019-01-16T16:05:03.261Z",
      "attributes": {
        "admission_datetime": "2019-01-16T16:05:03.261Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "report": {
          "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"
                ]
              }
            }
          ]
        }
      }
    }
    
    
    {
      "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
      "type": "report_admissions",
      "version": 0,
      "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
      "created_on": "2019-01-16T16:05:03.261Z",
      "modified_on": "2019-01-16T16:05:03.261Z",
      "attributes": {
        "admission_datetime": "2019-01-16T16:05:03.261Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "report": {
          "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"
                ]
              }
            }
          ]
        }
      }
    }
    
    
    {
      "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
      "type": "report_admissions",
      "version": 0,
      "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
      "created_on": "2019-01-16T16:05:03.261Z",
      "modified_on": "2019-01-16T16:05:03.261Z",
      "attributes": {
        "admission_datetime": "2019-01-16T16:05:03.261Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "report": {
          "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"
                ]
              }
            }
          ]
        }
      }
    }
    
    

    Get a single report admission using the admission ID.

    HTTP Request

    GET v1/notification/reports/{report_id}/admissions/{admission_id}

    URL Parameter Description
    report_id string, unique identifier (UUID) Report ID referenced by the admission to fetch
    admission_id string, unique identifier (UUID) Admission ID of the admission to fetch

    Scheme Messages

    Scheme messages are informational messages that are delivered to the participant of a scheme. They inform the participant of information such as issues with other participants and warnings when you get close to your limit.

    A list of supported scheme messages is provided below

    Scheme Message

    Resource

    Example scheme message resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
     "data": { 
        "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
        "type": "scheme_messages",    
        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
        "attributes": {
            "date": "2018-12-21T12:57:15.559Z",
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
            "entries": [
                {
                  "key": "Settlement Method",
                  "value": "CLRG"
                },
                {
                  "key": "Settlement Date",
                  "value": "2019-01-09"
                },
                {
                  "key": "Function Code",
                  "value": "FPS Institution and Third Party Beneficiary status change"
                },
                {
                  "key": "Institutional Connection Status Priority",
                  "value": "2"
                },
                {
                  "key": "Institutional Connection Status Availability",
                  "value": "0"
                },
                {
                  "key": "Financial Institution Id",
                  "value": "000011"
                },
                {
                  "key": "Financial Institution Issuer",
                  "value": "01"
                },
                {
                  "key": "Financial Institution Name",
                  "value": "ABC BUILDING SOCIETY"
                }
            ]        
        },    
        "relationships": {
            "scheme_message_admission": {
                "data": [
                    {
                        "id": "a4425b4a-9caf-4991-8235-8b02b6f85098",
                        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                        "type": "scheme_message_admissions",
                        "version": 0,
                        "attributes": {
                            "admission_datetime": "2018-12-21T12:57:15.931Z",
                            "status": "delivery_confirmed"
                        }
                    }
                ]
            }
        }    
     }   
    }
    
    
    {
     "data": { 
        "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
        "type": "scheme_messages",    
        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
        "attributes": {
            "date": "2018-12-21T12:57:15.559Z",
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
            "entries": [
                {
                  "key": "Settlement Method",
                  "value": "CLRG"
                },
                {
                  "key": "Settlement Date",
                  "value": "2019-01-09"
                },
                {
                  "key": "Function Code",
                  "value": "FPS Institution and Third Party Beneficiary status change"
                },
                {
                  "key": "Institutional Connection Status Priority",
                  "value": "2"
                },
                {
                  "key": "Institutional Connection Status Availability",
                  "value": "0"
                },
                {
                  "key": "Financial Institution Id",
                  "value": "000011"
                },
                {
                  "key": "Financial Institution Issuer",
                  "value": "01"
                },
                {
                  "key": "Financial Institution Name",
                  "value": "ABC BUILDING SOCIETY"
                }
            ]        
        },    
        "relationships": {
            "scheme_message_admission": {
                "data": [
                    {
                        "id": "a4425b4a-9caf-4991-8235-8b02b6f85098",
                        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                        "type": "scheme_message_admissions",
                        "version": 0,
                        "attributes": {
                            "admission_datetime": "2018-12-21T12:57:15.931Z",
                            "status": "delivery_confirmed"
                        }
                    }
                ]
            }
        }    
     }   
    }
    
    
    {
     "data": { 
        "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
        "type": "scheme_messages",    
        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
        "attributes": {
            "date": "2018-12-21T12:57:15.559Z",
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
            "entries": [
                {
                  "key": "Settlement Method",
                  "value": "CLRG"
                },
                {
                  "key": "Settlement Date",
                  "value": "2019-01-09"
                },
                {
                  "key": "Function Code",
                  "value": "FPS Institution and Third Party Beneficiary status change"
                },
                {
                  "key": "Institutional Connection Status Priority",
                  "value": "2"
                },
                {
                  "key": "Institutional Connection Status Availability",
                  "value": "0"
                },
                {
                  "key": "Financial Institution Id",
                  "value": "000011"
                },
                {
                  "key": "Financial Institution Issuer",
                  "value": "01"
                },
                {
                  "key": "Financial Institution Name",
                  "value": "ABC BUILDING SOCIETY"
                }
            ]        
        },    
        "relationships": {
            "scheme_message_admission": {
                "data": [
                    {
                        "id": "a4425b4a-9caf-4991-8235-8b02b6f85098",
                        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                        "type": "scheme_message_admissions",
                        "version": 0,
                        "attributes": {
                            "admission_datetime": "2018-12-21T12:57:15.931Z",
                            "status": "delivery_confirmed"
                        }
                    }
                ]
            }
        }    
     }   
    }
    
    
    Attribute Description
    payment_scheme string read-only The scheme which the scheme message was delivered on e.g. FPS
    scheme_message_type string read-only The scheme message type ID as specified by the scheme
    unique_scheme_id string read-only The unique scheme identifier for the message
    date datetime read-only The datetime of the scheme message
    entries list of key/value pair read-only List of key-value pairs that contain detail of the scheme message e.g. Key:Settlement Method, Value:CLRG
    relationships.scheme_message_admission resource read-only The scheme message admission that corresponds to the scheme message

    Fetch

    Example request

    GET v1/notification/schememessages/3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/notification/schememessages/3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/notification/schememessages/3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
     "data": { 
        "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
        "type": "scheme_messages",    
        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
        "attributes": {
            "date": "2018-12-21T12:57:15.559Z",
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
            "entries": [
                {
                  "key": "Settlement Method",
                  "value": "CLRG"
                },
                {
                  "key": "Settlement Date",
                  "value": "2019-01-09"
                },
                {
                  "key": "Function Code",
                  "value": "FPS Institution and Third Party Beneficiary status change"
                },
                {
                  "key": "Institutional Connection Status Priority",
                  "value": "2"
                },
                {
                  "key": "Institutional Connection Status Availability",
                  "value": "0"
                },
                {
                  "key": "Financial Institution Id",
                  "value": "000011"
                },
                {
                  "key": "Financial Institution Issuer",
                  "value": "01"
                },
                {
                  "key": "Financial Institution Name",
                  "value": "ABC BUILDING SOCIETY"
                }
            ]        
        },    
        "relationships": {
            "scheme_message_admission": {
                "data": [
                    {
                        "id": "a4425b4a-9caf-4991-8235-8b02b6f85098",
                        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                        "type": "scheme_message_admissions",
                        "version": 0,
                        "attributes": {
                            "admission_datetime": "2018-12-21T12:57:15.931Z",
                            "status": "delivery_confirmed"
                        }
                    }
                ]
            }
        }    
     }   
    }
    
    
    {
     "data": { 
        "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
        "type": "scheme_messages",    
        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
        "attributes": {
            "date": "2018-12-21T12:57:15.559Z",
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
            "entries": [
                {
                  "key": "Settlement Method",
                  "value": "CLRG"
                },
                {
                  "key": "Settlement Date",
                  "value": "2019-01-09"
                },
                {
                  "key": "Function Code",
                  "value": "FPS Institution and Third Party Beneficiary status change"
                },
                {
                  "key": "Institutional Connection Status Priority",
                  "value": "2"
                },
                {
                  "key": "Institutional Connection Status Availability",
                  "value": "0"
                },
                {
                  "key": "Financial Institution Id",
                  "value": "000011"
                },
                {
                  "key": "Financial Institution Issuer",
                  "value": "01"
                },
                {
                  "key": "Financial Institution Name",
                  "value": "ABC BUILDING SOCIETY"
                }
            ]        
        },    
        "relationships": {
            "scheme_message_admission": {
                "data": [
                    {
                        "id": "a4425b4a-9caf-4991-8235-8b02b6f85098",
                        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                        "type": "scheme_message_admissions",
                        "version": 0,
                        "attributes": {
                            "admission_datetime": "2018-12-21T12:57:15.931Z",
                            "status": "delivery_confirmed"
                        }
                    }
                ]
            }
        }    
     }   
    }
    
    
    {
     "data": { 
        "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
        "type": "scheme_messages",    
        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
        "attributes": {
            "date": "2018-12-21T12:57:15.559Z",
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
            "entries": [
                {
                  "key": "Settlement Method",
                  "value": "CLRG"
                },
                {
                  "key": "Settlement Date",
                  "value": "2019-01-09"
                },
                {
                  "key": "Function Code",
                  "value": "FPS Institution and Third Party Beneficiary status change"
                },
                {
                  "key": "Institutional Connection Status Priority",
                  "value": "2"
                },
                {
                  "key": "Institutional Connection Status Availability",
                  "value": "0"
                },
                {
                  "key": "Financial Institution Id",
                  "value": "000011"
                },
                {
                  "key": "Financial Institution Issuer",
                  "value": "01"
                },
                {
                  "key": "Financial Institution Name",
                  "value": "ABC BUILDING SOCIETY"
                }
            ]        
        },    
        "relationships": {
            "scheme_message_admission": {
                "data": [
                    {
                        "id": "a4425b4a-9caf-4991-8235-8b02b6f85098",
                        "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                        "type": "scheme_message_admissions",
                        "version": 0,
                        "attributes": {
                            "admission_datetime": "2018-12-21T12:57:15.931Z",
                            "status": "delivery_confirmed"
                        }
                    }
                ]
            }
        }    
     }   
    }
    
    

    Get a single scheme message using the scheme message ID.

    HTTP Request

    GET v1/notification/schememessages/{scheme_message_id}

    URL Parameter Description
    scheme_message_id string, unique identifier (UUID) ID of the scheme message to fetch

    List

    Example request

    GET v1/notification/schememessages HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/notification/schememessages \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/notification/schememessages', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": [
        {
          "id": "c7402a77-8f3e-4543-94c7-a48bd9a6987b",
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "type": "scheme_messages",
          "version": 0,
          "attributes": {
            "date": "2018-12-21T13:17:58.126Z",
            "entries": [
              {
                "key": "key1",
                "value": "value1"
              },
              {
                "key": "key2",
                "value": "value2"
              }
            ],
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "d8a48a38-f1e2-4f34-ade8-17c5f6f1bba3"
          },
          "relationships": {
            "scheme_message_admission": {
              "data": [
                {
                  "id": "a4425b4a-9caf-4991-8235-8b02b6f85098",
                  "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                  "type": "scheme_message_admissions",
                  "version": 0,
                  "attributes": {
                    "admission_datetime": "2018-12-21T13:17:58.517Z",
                    "status": "delivery_confirmed"
                  }
                }
              ]
            }
          }
        },
        {
          "id": "01b4f50f-b31b-4aac-9d89-2e1c1e4f6d40",
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "type": "scheme_messages",
          "version": 0,
          "attributes": {
            "date": "2018-12-21T13:17:58.517Z",
            "entries": [
              {
                "key": "key2",
                "value": "value2"
              },
              {
                "key": "key1",
                "value": "value1"
              }
            ],
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "3f5ef238-b1ac-44d4-b7a5-47c88a416ead"
          },
          "relationships": {
            "scheme_message_admission": {
              "data": [
                {
                  "id": "387be675-e8b4-4aad-963b-c38a454a3fb5",
                  "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                  "type": "scheme_message_admissions",
                  "version": 0,
                  "attributes": {
                    "admission_datetime": "2018-12-21T13:17:58.517Z",
                    "status": "delivery_confirmed"
                  }
                }
              ]
            }
          }
        }
      ]
    }
    
    
    {
      "data": [
        {
          "id": "c7402a77-8f3e-4543-94c7-a48bd9a6987b",
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "type": "scheme_messages",
          "version": 0,
          "attributes": {
            "date": "2018-12-21T13:17:58.126Z",
            "entries": [
              {
                "key": "key1",
                "value": "value1"
              },
              {
                "key": "key2",
                "value": "value2"
              }
            ],
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "d8a48a38-f1e2-4f34-ade8-17c5f6f1bba3"
          },
          "relationships": {
            "scheme_message_admission": {
              "data": [
                {
                  "id": "a4425b4a-9caf-4991-8235-8b02b6f85098",
                  "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                  "type": "scheme_message_admissions",
                  "version": 0,
                  "attributes": {
                    "admission_datetime": "2018-12-21T13:17:58.517Z",
                    "status": "delivery_confirmed"
                  }
                }
              ]
            }
          }
        },
        {
          "id": "01b4f50f-b31b-4aac-9d89-2e1c1e4f6d40",
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "type": "scheme_messages",
          "version": 0,
          "attributes": {
            "date": "2018-12-21T13:17:58.517Z",
            "entries": [
              {
                "key": "key2",
                "value": "value2"
              },
              {
                "key": "key1",
                "value": "value1"
              }
            ],
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "3f5ef238-b1ac-44d4-b7a5-47c88a416ead"
          },
          "relationships": {
            "scheme_message_admission": {
              "data": [
                {
                  "id": "387be675-e8b4-4aad-963b-c38a454a3fb5",
                  "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                  "type": "scheme_message_admissions",
                  "version": 0,
                  "attributes": {
                    "admission_datetime": "2018-12-21T13:17:58.517Z",
                    "status": "delivery_confirmed"
                  }
                }
              ]
            }
          }
        }
      ]
    }
    
    
    {
      "data": [
        {
          "id": "c7402a77-8f3e-4543-94c7-a48bd9a6987b",
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "type": "scheme_messages",
          "version": 0,
          "attributes": {
            "date": "2018-12-21T13:17:58.126Z",
            "entries": [
              {
                "key": "key1",
                "value": "value1"
              },
              {
                "key": "key2",
                "value": "value2"
              }
            ],
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "d8a48a38-f1e2-4f34-ade8-17c5f6f1bba3"
          },
          "relationships": {
            "scheme_message_admission": {
              "data": [
                {
                  "id": "a4425b4a-9caf-4991-8235-8b02b6f85098",
                  "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                  "type": "scheme_message_admissions",
                  "version": 0,
                  "attributes": {
                    "admission_datetime": "2018-12-21T13:17:58.517Z",
                    "status": "delivery_confirmed"
                  }
                }
              ]
            }
          }
        },
        {
          "id": "01b4f50f-b31b-4aac-9d89-2e1c1e4f6d40",
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "type": "scheme_messages",
          "version": 0,
          "attributes": {
            "date": "2018-12-21T13:17:58.517Z",
            "entries": [
              {
                "key": "key2",
                "value": "value2"
              },
              {
                "key": "key1",
                "value": "value1"
              }
            ],
            "payment_scheme": "FPS",
            "scheme_message_type": "972",
            "unique_scheme_id": "3f5ef238-b1ac-44d4-b7a5-47c88a416ead"
          },
          "relationships": {
            "scheme_message_admission": {
              "data": [
                {
                  "id": "387be675-e8b4-4aad-963b-c38a454a3fb5",
                  "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
                  "type": "scheme_message_admissions",
                  "version": 0,
                  "attributes": {
                    "admission_datetime": "2018-12-21T13:17:58.517Z",
                    "status": "delivery_confirmed"
                  }
                }
              ]
            }
          }
        }
      ]
    }
    
    

    List scheme messages with the ability to filter and page.

    HTTP Request v1/notification/schememessages?page[number]={page_number}&page[size]={page_size}

    Page parameters

    All fields are optional.

    Parameter Default Description
    page[number] 0 Page number being requested (starting from zero)
    page[size] 1000 Size of the page being requested
    filter[scheme_message_type] Find all scheme messages for a specific scheme message type
    filter[unique_scheme_id] Find all scheme messages by the unique scheme id
    filter[payment_scheme] Find all scheme messages for a specific payment scheme
    filter[admission.admission_date_from] Find all scheme messages admitted from and including this date/time, in ISO 8601 format YYYY-MM-DDThh:mm:ss.sTZD eg 1997-07-16T19:20:30.45+01:00
    filter[admission.admission_date_to] Find all scheme messages up to and included this date/time, in ISO 8601 format YYYY-MM-DDThh:mm:ss.sTZD eg 1997-07-16T19:20:30.45+01:00

    Scheme Message Admissions

    A Scheme Message Admission represents an incoming scheme message. Subscribing to create events of scheme message admissions is the recommended way to watch for incoming scheme messages.

    Resource

    Example scheme message admission resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "id": "6e782ac4-7b26-4499-8006-f787c6851456",
      "organisation_id": "92b3aeec-fc5a-4901-9e7b-eab058b331aa",
      "type": "scheme_message_admissions",
      "version": 0,
      "attributes": {
        "admission_datetime": "2018-12-21T13:56:57.649Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "scheme_message": {
          "data": [
            {
              "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
              "type": "scheme_messages",    
              "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
              "attributes": {
                "date": "2018-12-21T12:57:15.559Z",
                "payment_scheme": "FPS",
                "scheme_message_type": "972",
                "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
                "entries": [
                  {
                    "key": "Settlement Method",
                    "value": "CLRG"
                  },
                  {
                    "key": "Settlement Date",
                    "value": "2019-01-09"
                  },
                  {
                    "key": "Function Code",
                    "value": "FPS Institution and Third Party Beneficiary status change"
                  },
                  {
                    "key": "Institutional Connection Status Priority",
                    "value": "2"
                  },
                  {
                    "key": "Institutional Connection Status Availability",
                    "value": "0"
                  },
                  {
                    "key": "Financial Institution Id",
                    "value": "000011"
                  },
                  {
                    "key": "Financial Institution Issuer",
                    "value": "01"
                  },
                  {
                    "key": "Financial Institution Name",
                    "value": "ABC BUILDING SOCIETY"
                  }
                ]        
              }
            }
          ]
        }
      }
    }
    
    
    {
      "id": "6e782ac4-7b26-4499-8006-f787c6851456",
      "organisation_id": "92b3aeec-fc5a-4901-9e7b-eab058b331aa",
      "type": "scheme_message_admissions",
      "version": 0,
      "attributes": {
        "admission_datetime": "2018-12-21T13:56:57.649Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "scheme_message": {
          "data": [
            {
              "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
              "type": "scheme_messages",    
              "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
              "attributes": {
                "date": "2018-12-21T12:57:15.559Z",
                "payment_scheme": "FPS",
                "scheme_message_type": "972",
                "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
                "entries": [
                  {
                    "key": "Settlement Method",
                    "value": "CLRG"
                  },
                  {
                    "key": "Settlement Date",
                    "value": "2019-01-09"
                  },
                  {
                    "key": "Function Code",
                    "value": "FPS Institution and Third Party Beneficiary status change"
                  },
                  {
                    "key": "Institutional Connection Status Priority",
                    "value": "2"
                  },
                  {
                    "key": "Institutional Connection Status Availability",
                    "value": "0"
                  },
                  {
                    "key": "Financial Institution Id",
                    "value": "000011"
                  },
                  {
                    "key": "Financial Institution Issuer",
                    "value": "01"
                  },
                  {
                    "key": "Financial Institution Name",
                    "value": "ABC BUILDING SOCIETY"
                  }
                ]        
              }
            }
          ]
        }
      }
    }
    
    
    {
      "id": "6e782ac4-7b26-4499-8006-f787c6851456",
      "organisation_id": "92b3aeec-fc5a-4901-9e7b-eab058b331aa",
      "type": "scheme_message_admissions",
      "version": 0,
      "attributes": {
        "admission_datetime": "2018-12-21T13:56:57.649Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "scheme_message": {
          "data": [
            {
              "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
              "type": "scheme_messages",    
              "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
              "attributes": {
                "date": "2018-12-21T12:57:15.559Z",
                "payment_scheme": "FPS",
                "scheme_message_type": "972",
                "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
                "entries": [
                  {
                    "key": "Settlement Method",
                    "value": "CLRG"
                  },
                  {
                    "key": "Settlement Date",
                    "value": "2019-01-09"
                  },
                  {
                    "key": "Function Code",
                    "value": "FPS Institution and Third Party Beneficiary status change"
                  },
                  {
                    "key": "Institutional Connection Status Priority",
                    "value": "2"
                  },
                  {
                    "key": "Institutional Connection Status Availability",
                    "value": "0"
                  },
                  {
                    "key": "Financial Institution Id",
                    "value": "000011"
                  },
                  {
                    "key": "Financial Institution Issuer",
                    "value": "01"
                  },
                  {
                    "key": "Financial Institution Name",
                    "value": "ABC BUILDING SOCIETY"
                  }
                ]        
              }
            }
          ]
        }
      }
    }
    
    
    Attribute Description
    admission_datetime datetime read-only Date and time the scheme message admission was created
    status string read-only Status of the admission
    relationships.scheme_message resource read-only Scheme message resource that relates to the admission

    Fetch

    Example request

    GET v1/notification/schememessages/5fcb5536-988b-483f-878e-559671ebdcc4/admissions/6e782ac4-7b26-4499-8006-f787c6851456 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/notification/schememessages/5fcb5536-988b-483f-878e-559671ebdcc4/admissions/6e782ac4-7b26-4499-8006-f787c6851456 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/notification/schememessages/5fcb5536-988b-483f-878e-559671ebdcc4/admissions/6e782ac4-7b26-4499-8006-f787c6851456', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "id": "6e782ac4-7b26-4499-8006-f787c6851456",
      "organisation_id": "92b3aeec-fc5a-4901-9e7b-eab058b331aa",
      "type": "scheme_message_admissions",
      "version": 0,
      "attributes": {
        "admission_datetime": "2018-12-21T13:56:57.649Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "scheme_message": {
          "data": [
            {
              "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
              "type": "scheme_messages",    
              "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
              "attributes": {
                "date": "2018-12-21T12:57:15.559Z",
                "payment_scheme": "FPS",
                "scheme_message_type": "972",
                "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
                "entries": [
                  {
                    "key": "Settlement Method",
                    "value": "CLRG"
                  },
                  {
                    "key": "Settlement Date",
                    "value": "2019-01-09"
                  },
                  {
                    "key": "Function Code",
                    "value": "FPS Institution and Third Party Beneficiary status change"
                  },
                  {
                    "key": "Institutional Connection Status Priority",
                    "value": "2"
                  },
                  {
                    "key": "Institutional Connection Status Availability",
                    "value": "0"
                  },
                  {
                    "key": "Financial Institution Id",
                    "value": "000011"
                  },
                  {
                    "key": "Financial Institution Issuer",
                    "value": "01"
                  },
                  {
                    "key": "Financial Institution Name",
                    "value": "ABC BUILDING SOCIETY"
                  }
                ]        
              }
            }
          ]
        }
      }
    }
    
    
    {
      "id": "6e782ac4-7b26-4499-8006-f787c6851456",
      "organisation_id": "92b3aeec-fc5a-4901-9e7b-eab058b331aa",
      "type": "scheme_message_admissions",
      "version": 0,
      "attributes": {
        "admission_datetime": "2018-12-21T13:56:57.649Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "scheme_message": {
          "data": [
            {
              "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
              "type": "scheme_messages",    
              "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
              "attributes": {
                "date": "2018-12-21T12:57:15.559Z",
                "payment_scheme": "FPS",
                "scheme_message_type": "972",
                "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
                "entries": [
                  {
                    "key": "Settlement Method",
                    "value": "CLRG"
                  },
                  {
                    "key": "Settlement Date",
                    "value": "2019-01-09"
                  },
                  {
                    "key": "Function Code",
                    "value": "FPS Institution and Third Party Beneficiary status change"
                  },
                  {
                    "key": "Institutional Connection Status Priority",
                    "value": "2"
                  },
                  {
                    "key": "Institutional Connection Status Availability",
                    "value": "0"
                  },
                  {
                    "key": "Financial Institution Id",
                    "value": "000011"
                  },
                  {
                    "key": "Financial Institution Issuer",
                    "value": "01"
                  },
                  {
                    "key": "Financial Institution Name",
                    "value": "ABC BUILDING SOCIETY"
                  }
                ]        
              }
            }
          ]
        }
      }
    }
    
    
    {
      "id": "6e782ac4-7b26-4499-8006-f787c6851456",
      "organisation_id": "92b3aeec-fc5a-4901-9e7b-eab058b331aa",
      "type": "scheme_message_admissions",
      "version": 0,
      "attributes": {
        "admission_datetime": "2018-12-21T13:56:57.649Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "scheme_message": {
          "data": [
            {
              "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
              "type": "scheme_messages",    
              "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",    
              "attributes": {
                "date": "2018-12-21T12:57:15.559Z",
                "payment_scheme": "FPS",
                "scheme_message_type": "972",
                "unique_scheme_id": "6b7386bb-68ac-471c-8c86-6ea08e3c394f",
                "entries": [
                  {
                    "key": "Settlement Method",
                    "value": "CLRG"
                  },
                  {
                    "key": "Settlement Date",
                    "value": "2019-01-09"
                  },
                  {
                    "key": "Function Code",
                    "value": "FPS Institution and Third Party Beneficiary status change"
                  },
                  {
                    "key": "Institutional Connection Status Priority",
                    "value": "2"
                  },
                  {
                    "key": "Institutional Connection Status Availability",
                    "value": "0"
                  },
                  {
                    "key": "Financial Institution Id",
                    "value": "000011"
                  },
                  {
                    "key": "Financial Institution Issuer",
                    "value": "01"
                  },
                  {
                    "key": "Financial Institution Name",
                    "value": "ABC BUILDING SOCIETY"
                  }
                ]        
              }
            }
          ]
        }
      }
    }
    
    

    Get a single scheme message admission using the admission ID.

    HTTP Request GET v1/notification/schememessages/{scheme_message_id}/admissions/{admission_id}

    URL Parameter Description
    scheme_message_id string, unique identifier (UUID) Scheme Message ID referenced by the admission to fetch
    admission_id string, unique identifier (UUID) Admission ID of the admission to fetch

    Organisation

    Accounts

    An Account represents a bank account that is registered with Form3. It is used to validate and allocate inbound payments.

    Resource

    Example account resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    Attribute Description
    country string, ISO code required ISO 3166-1 code used to identify the domicile of the account, e.g. 'GB', 'FR'
    base_currencystring, ISO code optional ISO 4217 code used to identify the base currency of the account, e.g. 'GBP', 'EUR'
    bank_id string, maximum length 11 optional Local country bank identifier. Format depends on the country. Required for most countries.
    bank_id_code string conditional Identifies the type of bank ID being used, see here for allowed value for each country. Required value depends on country attribute.
    account_numberstring optional Account number. A unique account number will automatically be generated if not provided.
    bic string, 8 or 11 character code optional SWIFT BIC in either 8 or 11 character format e.g. 'NWBKGB22'
    iban string optional IBAN of the account. Will be calculated from other fields if not supplied.
    customer_id string optional A free-format reference that can be used to link this account to an external system
    title string [40] optional The account holder's title, e.g. Ms, Dr, Mr.
    first_name string [40] optional The account holder's first name.
    bank_account_name string [140] optional Primary account name, used for Confirmation of Payee matching. Required if Confirmation of Payee is enabled for the organisation.
    alternative_bank_account_names array [3] of string [140] optional Up to 3 alternative account names, used for Confirmation of Payee matching.
    account_classification string optional Classification of account. Can be either Personal or Business. Defaults to Personal.
    joint_account boolean optional True is this is a joint account. Defaults to false.
    account_matching_opt_out boolean optional True if the account has opted out of account matching, e.g. Confirmation of Payee. Defaults to false.
    secondary_identification string [140] optional Secondary identification, e.g. building society roll number. Used for Confirmation of Payee.

    Create

    Register an existing bank account with Form3 or create a new one. The country attribute must be specified as a minimum. Depending on the country, other attributes such as bank_id and bic are mandatory.

    Form3 generates account numbers and IBANs, where appropriate, in the following cases:

    Note that a given bank_id and bic need to be registered with Form3 and connected to your organisation ID.

    This table gives an overview of required attributes depending on the country the account is registered in:

    Country Attributes
    United Kingdom Country code: GB
    Bank ID: required, 6 characters, UK sort code
    BIC: required
    Bank ID Code: required, has to be GBDSC
    Account Number: optional, 8 characters, generated if not provided
    IBAN: Generated if not provided
    Australia Country code: AU
    Bank ID: optional, 6 characters, Australian Bank State Branch (BSB) code
    BIC: required
    Bank ID Code: required, has to be AUBSB
    Account Number: optional, 6-10 characters, first character cannot be 0, generated if not provided
    IBAN: has to be empty
    Belgium Country code: BE
    Bank ID: required, 3 characters
    BIC: optional
    Bank ID Code: required, has to be BE
    Account Number: optional, 7 characters, generated if not provided
    IBAN: generated if not provided
    Canada Country code: CA
    Bank ID: optional, 9 characters starting with zero, Routing Number for Electronic Funds Transfers
    BIC: required
    Bank ID Code: optional, if provided, has to be CACPA
    Account Number: optional, 7-12 characters, generated if not provided
    IBAN: not supported, has to be empty
    France Country code: FR
    Bank ID: required, 10 characters, national bank code + branch code (code guichet)
    BIC: optional
    Bank ID Code: required, has to be FR
    Account Number: optional, 10 characters, generated if not provided
    IBAN: generated if not provided
    Germany Country code: DE
    Bank ID: required, 8 characters, Bankleitzahl (BLZ)
    BIC: optional
    Bank ID Code: required, has to be DEBLZ
    Account Number: optional, 7 characters, generated if not provided
    IBAN: generated if not provided
    Greece Country code: GR
    Bank ID: required, 7 characters, HEBIC (Hellenic Bank Identification Code)
    BIC: optional
    Bank ID Code: required, has to be GRBIC
    Account Number: optional, 16 characters, generated if not provided
    IBAN: generated if not provided
    Hong Kong Country code: HK
    Bank ID: optional, 3 characters, Bank Code or Institution ID
    BIC: required
    Bank ID Code: optional, if provided, has to be HKNCC
    Account Number: optional, 9-12 characters, generated if not provided
    IBAN: not supported, has to be empty
    Italy Country code: IT
    Bank ID: required, national bank code (ABI) + branch code (CAB), 10 characters if account number is not present, 11 characters with added check digit as first character if account number is present
    BIC: optional
    Bank ID Code: required, has to be ITNCC
    Account Number: optional, 12 characters, generated if not provided
    IBAN: generated if not provided
    Luxembourg Country code: LU
    Bank ID: required, 3 characters, IBAN Bank Identifier
    BIC: optional
    Bank ID Code: required, has to be LULUX
    Account Number: optional, 13 characters, generated if not provided
    IBAN: generated if not provided
    Netherlands Country code: NL
    Bank ID: not supported, has to be empty
    BIC: required
    Bank ID Code: not supported, has to be empty
    Account Number: optional, 10 characters, generated if not provided
    IBAN: generated if not provided
    Poland Country code: PL
    Bank ID: required, 8 characters, national bank code + branch code + national check digit
    BIC: optional
    Bank ID Code: required, has to be PLKNR
    Account Number: optional, 16 characters, generated if not provided
    IBAN: generated if not provided
    Portugal Country code: PT
    Bank ID: required, 8 characters, bank identifier + PSP reference number
    BIC: optional
    Bank ID Code: required, has to be PTNCC
    Account Number: optional, 11 characters, generated if not provided
    IBAN: generated if not provided
    Spain Country code: ES
    Bank ID: required, 8 characters, Código de entidad + Código de oficina
    BIC: optional
    Bank ID Code: required, has to be ESNCC
    Account Number: optional, 10 characters, generated if not provided
    IBAN: generated if not provided
    Switzerland Country code: CH
    Bank ID: required, 5 characters
    BIC: optional
    Bank ID Code: required, has to be CHBCC
    Account Number: optional, 12 characters, generated if not provided
    IBAN: generated if not provided
    United States Country code: US
    Bank ID: required, 9 characters, ABA routing number
    BIC: required
    Bank ID Code: required, has to be USABA
    Account Number: optional, 6-17 characters, generated if not provided
    IBAN: not supported, has to be empty

    HTTP Request

    POST /v1/organisation/accounts

    Example request

    POST /v1/organisation/accounts HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
        "title": "Ms",
        "first_name": "Samantha",
        "bank_account_name": "Samantha Holder",
        "alternative_bank_account_names": [
          "Sam Holder"
        ],
        "account_classification": "Personal",
        "joint_account": false,
        "account_matching_opt_out": false,
        "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/organisation/accounts
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
        "title": "Ms",
        "first_name": "Samantha",
        "bank_account_name": "Samantha Holder",
        "alternative_bank_account_names": [
          "Sam Holder"
        ],
        "account_classification": "Personal",
        "joint_account": false,
        "account_matching_opt_out": false,
        "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'type': 'accounts',
        'id': 'ad27e265-9605-4b4b-a0e5-3003ea9cc4dc',
        'organisation_id': 'eb0bd6f5-c3f5-44b2-b677-acd23cdde73c',
        'attributes': {
          'country': 'GB',
          'base_currency': 'GBP',
          'account_number': '41426819',
          'bank_id': '400300',
          'bank_id_code': 'GBDSC',
          'bic': 'NWBKGB22',
          'iban': 'GB11NWBK40030041426819',
        'title': 'Ms',
        'first_name': 'Samantha',
        'bank_account_name': 'Samantha Holder',
        'alternative_bank_account_names': [
          'Sam Holder'
        ],
        'account_classification': 'Personal',
        'joint_account': false,
        'account_matching_opt_out': false,
        'secondary_identification': 'A1B2C3D4'
        }
      }
    }
    """
    req = requests.post('https://api.form3.tech/v1/organisation/accounts', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    Attribute Description
    country string, ISO code required ISO 3166-1 code used to identify the domicile of the account, e.g. 'GB', 'FR'
    base_currencystring, ISO code optional ISO 4217 code used to identify the base currency of the account, e.g. 'GBP', 'EUR'
    bank_id string, maximum length 11 optional Local country bank identifier. Format depends on the country. Required for most countries.
    bank_id_code string conditional Identifies the type of bank ID being used, see here for allowed value for each country. Required value depends on country attribute.
    account_numberstring optional Account number. A unique account number will automatically be generated if not provided.
    bic string, 8 or 11 character code optional SWIFT BIC in either 8 or 11 character format e.g. 'NWBKGB22'
    iban string optional IBAN of the account. Will be calculated from other fields if not supplied.
    customer_id string optional A free-format reference that can be used to link this account to an external system
    title string [40] optional The account holder's title, e.g. Ms, Dr, Mr.
    first_name string [40] optional The account holder's first name.
    bank_account_name string [140] optional Primary account name, used for Confirmation of Payee matching. Required if Confirmation of Payee is enabled for the organisation.
    alternative_bank_account_names array [3] of string [140] optional Up to 3 alternative account names, used for Confirmation of Payee matching.
    account_classification string optional Classification of account. Can be either Personal or Business. Defaults to Personal.
    joint_account boolean optional True is this is a joint account. Defaults to false.
    account_matching_opt_out boolean optional True if the account has opted out of account matching, e.g. Confirmation of Payee. Defaults to false.
    secondary_identification string [140] optional Secondary identification, e.g. building society roll number. Used for Confirmation of Payee.

    Fetch

    Example request

    GET /v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    

    Get a single account using the account ID.

    HTTP Request

    GET /v1/organisation/accounts/{account.id}

    Attribute Description
    account_id string, unique identifier (UUID) Account ID of the account to fetch

    Patch

    Example request

    PATCH /v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 1,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    curl -X PATCH -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 1,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    Error while processing include. Cannot find parameter 1.
    """
    req = requests.patch('https://api.form3.tech"Error while processing include. Cannot find file /home/travis/build/form3tech/api-docs/lib/form3/../../source/includes/"/v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"organisations/examples/_account_patch.md"', json=json, headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 2,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 2,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 2,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "title": "Ms",
          "first_name": "Samantha",
          "bank_account_name": "Samantha Holder",
          "alternative_bank_account_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4"
        }
      }
    }
    
    

    Update an individual account.

    HTTP Request

    PATCH /v1/organisation/accounts/{account_id}

    URL Parameter Description
    account_id string, unique identifier (UUID) Account ID of the account to update

    Request Body

    Attribute Description
    version integer required Version number of the resource to patch. Has to be the latest version of the resource.
    Note that the attribute is located on the top level of the resource, not on the attributes sub level (see code example).
    country string, ISO code optional ISO 3166-1 code used to identify the domicile of the account, e.g. 'GB', 'FR'
    base_currencystring, ISO code optional ISO 4217 code used to identify the base currency of the account, e.g. 'GBP', 'EUR'
    bank_id string, maximum length 11 optional Local country bank identifier. Format depends on the country. Required for most countries.
    bank_id_code string conditional Identifies the type of bank ID being used, see here for allowed value for each country. Required value depends on country attribute.
    account_numberstring optional Account number. A unique account number will automatically be generated if not provided.
    bic string, 8 or 11 character code optional SWIFT BIC in either 8 or 11 character format e.g. 'NWBKGB22'
    iban string optional IBAN of the account. Will be calculated from other fields if not supplied.
    customer_id string optional A free-format reference that can be used to link this account to an external system
    title string [40] optional The account holder's title, e.g. Ms, Dr, Mr.
    first_name string [40] optional The account holder's first name.
    bank_account_name string [140] optional Primary account name, used for Confirmation of Payee matching. Required if Confirmation of Payee is enabled for the organisation.
    alternative_bank_account_names array [3] of string [140] optional Up to 3 alternative account names, used for Confirmation of Payee matching.
    account_classification string optional Classification of account. Can be either Personal or Business. Defaults to Personal.
    joint_account boolean optional True is this is a joint account. Defaults to false.
    account_matching_opt_out boolean optional True if the account has opted out of account matching, e.g. Confirmation of Payee. Defaults to false.
    secondary_identification string [140] optional Secondary identification, e.g. building society roll number. Used for Confirmation of Payee.

    List

    Example request

    GET /v1/organisation/accounts/ HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/organisation/accounts/ \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/organisation/accounts/', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": [
        {
          "type": "accounts",
          "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "account_number": "41426819",
            "bank_id": "400300",
            "bank_id_code": "GBDSC"
          }
        },
        {
          "type": "accounts",
          "id": "ea6239c1-99e9-42b3-bca1-92f5c068da6b",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "account_number": "51426819",
            "bank_id": "200200",
            "bank_id_code": "GBDSC"
          }
        }
      ]
    }
    
    {
      "data": [
        {
          "type": "accounts",
          "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "account_number": "41426819",
            "bank_id": "400300",
            "bank_id_code": "GBDSC"
          }
        },
        {
          "type": "accounts",
          "id": "ea6239c1-99e9-42b3-bca1-92f5c068da6b",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "account_number": "51426819",
            "bank_id": "200200",
            "bank_id_code": "GBDSC"
          }
        }
      ]
    }
    
    {
      "data": [
        {
          "type": "accounts",
          "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "account_number": "41426819",
            "bank_id": "400300",
            "bank_id_code": "GBDSC"
          }
        },
        {
          "type": "accounts",
          "id": "ea6239c1-99e9-42b3-bca1-92f5c068da6b",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "account_number": "51426819",
            "bank_id": "200200",
            "bank_id_code": "GBDSC"
          }
        }
      ]
    }
    

    List accounts with the ability to filter and page. All accounts that match all filter criteria will be returned (combinations of filters act as AND expressions). Multiple values can be set for filters in CSV format, e.g. filter[country]=GB,FR,DE.

    HTTP Request

    GET /v1/organisation/accounts?page[number]={page_number}&page[size]={page_size}&filter[{attribute}]={filter_value}

    Page parameters

    All fields are optional.

    Parameter Default Description
    page[number] 0 Page number being requested
    page[size] 100 Size of the page being requested
    filter Used to filter accounts being returned. See: account filter parameters

    Filter parameters

    Value Description
    filter[bank_id_code] Find all accounts for a given list of bank ID codes. See ISO 20022 code for a list of all possible codes.
    filter[bank_id] Find all accounts for a given list of bank IDs (e.g. sort code)
    filter[account_number] Find all accounts for a given list of account numbers
    filter[iban] Find all accounts for a given list of IBANs
    filter[customer_id] Find all accounts for a given list of customer IDs
    filter[country] Find all accounts for a given list of countries

    Delete

    Delete an account

    Example request

    DELETE /v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc HTTP/1.1
    
    curl -X DELETE https://api.form3.tech//v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc
    
    import requests
    requests.delete('https://api.form3.tech//v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc')
    

    Response (204 No Content)

    HTTP Request

    DELETE /v1/organisation/accounts/{account.id}?version={version}

    Attribute Description
    account_id string, unique identifier (UUID), required Account ID of a account to delete
    version integer, required Version number of record

    HTTP Response

    Code Meaning Description
    204 No Content Resource has been successfully deleted
    404 Not Found Specified resource does not exist
    409 Conflict Specified version incorrect

    Account Number Generation

    Form3 offers the generation of account numbers and IBANs. When registering an account without providing an account number or IBAN, the numbers are generated according to national rules of the country provided in the country attribute.

    For most countries, generated account numbers are valid random numbers. Some countries required sequential account numbers. See the table below for which numbers are generated, the check digit rule applied and if sequential number generation is used:

    Country (Country Code) What is generated Check Digit Rule Comment
    United Kingdom (UK) Account number, IBAN Combination of "Mod 11" and "Double Alternate" methods as described here
    Australia (AU) Account number 2 check digits based on "Mod 97"
    Belgium (BE) Account number, IBAN 2 check digits as described here
    Canada (CA) Account number 2 check digits based on "Mod 97" Account number generation is incremental
    France (FR) Account number, IBAN Relevé d'identité bancaire
    Germany (DE) Account number, IBAN Bundesbank Check Digit Method 28 Last 2 chars of account number are sub-account ID, always chosen as "01" by Form3
    Greece (GR) Account number, IBAN No check digits used
    Hong Kong (HK) Account number 2 check digits based on "Mod 97" Account number generation is incremental
    Italy (IT) Account number, IBAN 1 Alpha (CIN) Check Character as described here
    Luxembourg (LU) Account number, IBAN No check digits used Account number generation is incremental
    Netherlands (NL) Account number, IBAN Integrated check as described here Account number generation is incremental
    Poland (PL) Account number, IBAN No check digits used
    Portugal (PT) Account number, IBAN 2 check digits as described here
    Spain (ES) Account number, IBAN 2 check digits as described here
    Switzerland (CH) Account number, IBAN No check digits used
    United States (US) Account number 2 check digits based on "Mod 97" Account number generation is incremental

    Units

    All data within Form3 is segregated between independent entities called Organisations. Each organisation has a parent and can have one or more child organisations. Users with access to the parent organisation have automatic access to all child organisations of that organisation.

    Organisations can be chained together in arbitrary levels of complexity. See the Security API for more information about users, roles and access control.

    Resource

    Example organisation resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "Organisation",
        "id": "d7ff9ce7-3145-4722-8f0a-1cd11ee8696b",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "name": "Test Bank"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/organisations/units/d7ff9ce7-3145-4722-8f0a-1cd11ee8696b"
      }
    }
    
    {
      "data": {
        "type": "Organisation",
        "id": "d7ff9ce7-3145-4722-8f0a-1cd11ee8696b",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "name": "Test Bank"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/organisations/units/d7ff9ce7-3145-4722-8f0a-1cd11ee8696b"
      }
    }
    
    {
      "data": {
        "type": "Organisation",
        "id": "d7ff9ce7-3145-4722-8f0a-1cd11ee8696b",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "name": "Test Bank"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/organisations/units/d7ff9ce7-3145-4722-8f0a-1cd11ee8696b"
      }
    }
    
    Attribute Description
    name string Name of the organisation

    Create

    Example request

    POST /v1/organisation/units HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "b2107afd-365a-4b28-8af7-b837a45f378b",
            "organisation_id": "19ddf23d-7175-4a66-a963-ead829df92ca",
            "attributes": {
                "name": "Test Bank"
            }
        }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/organisation/units
    
    {
        "data": {
            "id": "b2107afd-365a-4b28-8af7-b837a45f378b",
            "organisation_id": "19ddf23d-7175-4a66-a963-ead829df92ca",
            "attributes": {
                "name": "Test Bank"
            }
        }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
        'data': {
            'id': 'b2107afd-365a-4b28-8af7-b837a45f378b',
            'organisation_id': '19ddf23d-7175-4a66-a963-ead829df92ca',
            'attributes': {
                'name': 'Test Bank'
            }
        }
    }
    """
    req = requests.post('https://api.form3.tech/v1/organisation/units', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "Organisation",
        "id": "d7ff9ce7-3145-4722-8f0a-1cd11ee8696b",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "name": "Test Bank"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/organisations/units/d7ff9ce7-3145-4722-8f0a-1cd11ee8696b"
      }
    }
    
    {
      "data": {
        "type": "Organisation",
        "id": "d7ff9ce7-3145-4722-8f0a-1cd11ee8696b",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "name": "Test Bank"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/organisations/units/d7ff9ce7-3145-4722-8f0a-1cd11ee8696b"
      }
    }
    
    {
      "data": {
        "type": "Organisation",
        "id": "d7ff9ce7-3145-4722-8f0a-1cd11ee8696b",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "name": "Test Bank"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/organisations/units/d7ff9ce7-3145-4722-8f0a-1cd11ee8696b"
      }
    }
    

    Create a new organisation.

    HTTP Request

    POST /v1/organisation/units

    Attribute Description
    name string Name of the organisation

    Fetch

    Example request

    GET /v1/organisation/units/b2107afd-365a-4b28-8af7-b837a45f378b HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/organisation/units/b2107afd-365a-4b28-8af7-b837a45f378b \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/organisation/units/b2107afd-365a-4b28-8af7-b837a45f378b', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "Organisation",
        "id": "d7ff9ce7-3145-4722-8f0a-1cd11ee8696b",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "name": "Test Bank"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/organisations/units/d7ff9ce7-3145-4722-8f0a-1cd11ee8696b"
      }
    }
    
    {
      "data": {
        "type": "Organisation",
        "id": "d7ff9ce7-3145-4722-8f0a-1cd11ee8696b",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "name": "Test Bank"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/organisations/units/d7ff9ce7-3145-4722-8f0a-1cd11ee8696b"
      }
    }
    
    {
      "data": {
        "type": "Organisation",
        "id": "d7ff9ce7-3145-4722-8f0a-1cd11ee8696b",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "name": "Test Bank"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/organisations/units/d7ff9ce7-3145-4722-8f0a-1cd11ee8696b"
      }
    }
    

    Get a single organisation using the organisation ID.

    HTTP Request

    GET /v1/organisation/units/{organisation_id}

    Parameters

    Attribute Description
    organisation_id string, unique identifier (UUID) Organisation ID of the organisation to fetch

    List

    Example request

    GET /v1/organisation/units HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/organisation/units \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/organisation/units', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
              "type": "Organisation",
              "id": "378d51c7-f1e4-4953-ac29-fcc31ceab07a",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "name": "Global Organisations"
              }
            },
            {
              "type": "Organisation",
              "id": "1a734d34-3bc1-4c6d-aef2-17f8087c517c",
              "version": 0,
              "organisation_id": "378d51c7-f1e4-4953-ac29-fcc31ceab07a",
              "attributes": {
                "name": "Subsidiary UK"
              }
            },
            {
              "type": "Organisation",
              "id": "42672b6c-f32f-4429-833f-f39fec8bc648",
              "version": 0,
              "organisation_id": "378d51c7-f1e4-4953-ac29-fcc31ceab07a",
              "attributes": {
                "name": "Subsidiary USA"
              }
            }
        ],
        "links": {
            "self": "https://api.form3.tech/v1/organisations/units"
        }
    }
    
    {
        "data": [
            {
              "type": "Organisation",
              "id": "378d51c7-f1e4-4953-ac29-fcc31ceab07a",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "name": "Global Organisations"
              }
            },
            {
              "type": "Organisation",
              "id": "1a734d34-3bc1-4c6d-aef2-17f8087c517c",
              "version": 0,
              "organisation_id": "378d51c7-f1e4-4953-ac29-fcc31ceab07a",
              "attributes": {
                "name": "Subsidiary UK"
              }
            },
            {
              "type": "Organisation",
              "id": "42672b6c-f32f-4429-833f-f39fec8bc648",
              "version": 0,
              "organisation_id": "378d51c7-f1e4-4953-ac29-fcc31ceab07a",
              "attributes": {
                "name": "Subsidiary USA"
              }
            }
        ],
        "links": {
            "self": "https://api.form3.tech/v1/organisations/units"
        }
    }
    
    {
        "data": [
            {
              "type": "Organisation",
              "id": "378d51c7-f1e4-4953-ac29-fcc31ceab07a",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "name": "Global Organisations"
              }
            },
            {
              "type": "Organisation",
              "id": "1a734d34-3bc1-4c6d-aef2-17f8087c517c",
              "version": 0,
              "organisation_id": "378d51c7-f1e4-4953-ac29-fcc31ceab07a",
              "attributes": {
                "name": "Subsidiary UK"
              }
            },
            {
              "type": "Organisation",
              "id": "42672b6c-f32f-4429-833f-f39fec8bc648",
              "version": 0,
              "organisation_id": "378d51c7-f1e4-4953-ac29-fcc31ceab07a",
              "attributes": {
                "name": "Subsidiary USA"
              }
            }
        ],
        "links": {
            "self": "https://api.form3.tech/v1/organisations/units"
        }
    }
    

    List organisations with the ability to filter by child organisation ID. All accounts that match the filter criterium will be returned.

    HTTP Request

    GET /v1/organisation/units?filter[{attribute}]={filter_value}

    Filter parameters

    Value Description
    filter[child_organisation_id] Find all organisations that are parents of the organisation with the given ID
    filter[organisation_ids] Find all the organisations whose IDs match those in the list

    Patch

    Example request

    PATCH /v1/organisation/units HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "type": "Organisation",
            "id": "b2107afd-365a-4b28-8af7-b837a45f378b",
            "version": 0,
            "organisation_id": "19ddf23d-7175-4a66-a963-ead829df92ca",
            "attributes": {
                "name": "New Name"
            }
        }
    }
    
    curl -X PATCH -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/organisation/units
    
    {
        "data": {
            "type": "Organisation",
            "id": "b2107afd-365a-4b28-8af7-b837a45f378b",
            "version": 0,
            "organisation_id": "19ddf23d-7175-4a66-a963-ead829df92ca",
            "attributes": {
                "name": "New Name"
            }
        }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
        'data': {
            'type': 'Organisation',
            'id': 'b2107afd-365a-4b28-8af7-b837a45f378b',
            'version': 0,
            'organisation_id': '19ddf23d-7175-4a66-a963-ead829df92ca',
            'attributes': {
                'name': 'New Name'
            }
        }
    }
    """
    req = requests.patch('https://api.form3.tech/v1/organisation/units', json=json, headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "type": "Organisation",
            "id": "b2107afd-365a-4b28-8af7-b837a45f378b",
            "version": 1,
            "organisation_id": "19ddf23d-7175-4a66-a963-ead829df92ca",
            "attributes": {
                "name": "New Name"
            }
        },
        "links": {
            "self": "https://api.form3.tech/v1/organisation/units/b2107afd-365a-4b28-8af7-b837a45f378b"
        }
    }
    
    {
        "data": {
            "type": "Organisation",
            "id": "b2107afd-365a-4b28-8af7-b837a45f378b",
            "version": 1,
            "organisation_id": "19ddf23d-7175-4a66-a963-ead829df92ca",
            "attributes": {
                "name": "New Name"
            }
        },
        "links": {
            "self": "https://api.form3.tech/v1/organisation/units/b2107afd-365a-4b28-8af7-b837a45f378b"
        }
    }
    
    {
        "data": {
            "type": "Organisation",
            "id": "b2107afd-365a-4b28-8af7-b837a45f378b",
            "version": 1,
            "organisation_id": "19ddf23d-7175-4a66-a963-ead829df92ca",
            "attributes": {
                "name": "New Name"
            }
        },
        "links": {
            "self": "https://api.form3.tech/v1/organisation/units/b2107afd-365a-4b28-8af7-b837a45f378b"
        }
    }
    

    Update an organisation.

    HTTP Request

    PATCH /v1/organisation/units/{organisation_id}

    URL Parameter Description
    organisation_id string, unique identifier (UUID) Organisation ID of the organisation to update

    Request Body

    Attribute Description
    version integer required Version number of the resource to patch. Has to be the latest version of the resource.
    Note that the attribute is located on the top level of the resource, not on the attributes sub level (see code example).
    name string optional New name of the organisation

    Balances

    Resource

    Example balances resource

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data": [
            {
                "type": "balances",
                "id": "60c23de2-6d8f-4407-b1a3-6927208ef6d3",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "holding_institution": "starling",
                    "amount": "1000000",
                    "currency": "GBP",
                    "description": "settlement account"
                }
            }
        ]
    }
    
    
    {
        "data": [
            {
                "type": "balances",
                "id": "60c23de2-6d8f-4407-b1a3-6927208ef6d3",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "holding_institution": "starling",
                    "amount": "1000000",
                    "currency": "GBP",
                    "description": "settlement account"
                }
            }
        ]
    }
    
    
    {
        "data": [
            {
                "type": "balances",
                "id": "60c23de2-6d8f-4407-b1a3-6927208ef6d3",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "holding_institution": "starling",
                    "amount": "1000000",
                    "currency": "GBP",
                    "description": "settlement account"
                }
            }
        ]
    }
    
    
    Attribute Description
    holding_institution string Institution that holds the funds
    amount string Amount of funds
    currency string Currency of funds
    description string Balance description

    List

    Example request

    GET /v1/organisation/balances HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/organisation/balances \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/organisation/balances', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data": [
            {
                "type": "balances",
                "id": "60c23de2-6d8f-4407-b1a3-6927208ef6d3",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "holding_institution": "starling",
                    "amount": "1000000",
                    "currency": "GBP",
                    "description": "settlement account"
                }
            }
        ]
    }
    
    
    {
        "data": [
            {
                "type": "balances",
                "id": "60c23de2-6d8f-4407-b1a3-6927208ef6d3",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "holding_institution": "starling",
                    "amount": "1000000",
                    "currency": "GBP",
                    "description": "settlement account"
                }
            }
        ]
    }
    
    
    {
        "data": [
            {
                "type": "balances",
                "id": "60c23de2-6d8f-4407-b1a3-6927208ef6d3",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "holding_institution": "starling",
                    "amount": "1000000",
                    "currency": "GBP",
                    "description": "settlement account"
                }
            }
        ]
    }
    
    

    Get the current cash balance for settlement accounts.

    HTTP Request GET /v1/organisation/balances

    Positions

    The Position resource provides information on the Net Sender Cap (NSC) and the current limit utilisation. For non-settling participants, the NSC is agreed with the settlement sponsor. For schemes that support settlement cycles, the limit utilisation is reset at the beginning of a new cycle.

    Resource

    Example positions resource

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data": [
            {
                "type": "positions",
                "id": "8379995c-cb85-4ca0-a479-6936ab3f2035",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "scheme": "FPS",
                    "limit": "1000",
                    "position": "10"
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "type": "positions",
                "id": "8379995c-cb85-4ca0-a479-6936ab3f2035",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "scheme": "FPS",
                    "limit": "1000",
                    "position": "10"
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "type": "positions",
                "id": "8379995c-cb85-4ca0-a479-6936ab3f2035",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "scheme": "FPS",
                    "limit": "1000",
                    "position": "10"
                }
            }
        ]
    }
    
    Attribute Description
    scheme string Scheme associated with the limit
    limit string Current Net Sender Cap
    position string Remaining liquidity before reaching the NSC. The position is calculated as NSC - sum of outbound payment amounts in the given settlement cycle + sum of inbound payment amounts in the given settlement cycle.

    List

    Example request

    GET /v1/organisation/positions HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/organisation/positions \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/organisation/positions', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data": [
            {
                "type": "positions",
                "id": "8379995c-cb85-4ca0-a479-6936ab3f2035",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "scheme": "FPS",
                    "limit": "1000",
                    "position": "10"
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "type": "positions",
                "id": "8379995c-cb85-4ca0-a479-6936ab3f2035",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "scheme": "FPS",
                    "limit": "1000",
                    "position": "10"
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "type": "positions",
                "id": "8379995c-cb85-4ca0-a479-6936ab3f2035",
                "version": 0,
                "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
                "attributes": {
                    "scheme": "FPS",
                    "limit": "1000",
                    "position": "10"
                }
            }
        ]
    }
    

    Get current positions against the configured limits.

    HTTP Request

    GET /v1/organisation/positions

    Security

    The Security API is used to control permissions to read, create, delete and modify resources on the Form3 platform.

    All resources on the platform belong to an organisation. Each organisation can have multiple users with different permissions to read, create or change resources. Resource access is granted using an Access Control Entry (ACE), specifying the type of access (read, create, etc.) and the resource type.

    For convenience, ACEs are grouped into roles that can be shared between users. A user can be granted access to multiple roles.

    Because organisation access rights are only granted to users of your organisation, other Form3 customers cannot access any of your data. This is enforced across the platform and all resources follow the same behaviour.

    Security Considerations

    New organisations are created with one admin user. We recommend using this user only to create other users with reduced permission sets.

    When creating new users, be careful which permissions (ACEs) you provide that user with. Special care should be taken with write access (CREATE, EDIT and DELETE actions) to the following resources:

    Users with write access to these resources are deemed to be admin level users as they are able to provide other users with arbitrary access permissions to any resource within their organisation. No regular users should be given these permissions. We recommend that users are created with the lowest level of access to resources possible.

    Users

    The User resource represents a user entity in the system. A user is part of an Organisation and can have access to different system functions by having Roles assigned to it.

    Resource

    Example user resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "User",
        "id": "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "username" : "viewer.testbank",
            "email" : "viewer.testbank@form3.tech",
            "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"]
      },
      "links": {
        "self": "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
      }
    }
    
    {
      "data": {
        "type": "User",
        "id": "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "username" : "viewer.testbank",
            "email" : "viewer.testbank@form3.tech",
            "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"]
      },
      "links": {
        "self": "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
      }
    }
    
    {
      "data": {
        "type": "User",
        "id": "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "username" : "viewer.testbank",
            "email" : "viewer.testbank@form3.tech",
            "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"]
      },
      "links": {
        "self": "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
      }
    }
    
    Attribute Description
    username string required User name
    email string required Email address
    role_ids array of UUID optional List of roles that this user belongs to

    Create

    Example request

    POST /v1/security/users HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
        "data":{
            "id" : "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
            "organisation_id" : "89a5aa0e-ef84-4da7-83a2-cec9ab9aefa9",
            "attributes": {
                "email" : "viewer.testbank@form3.tech",
                "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"],
                "username" : "viewer.testbank"
            }
        }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/security/users
    
    {
        "data":{
            "id" : "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
            "organisation_id" : "89a5aa0e-ef84-4da7-83a2-cec9ab9aefa9",
            "attributes": {
                "email" : "viewer.testbank@form3.tech",
                "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"],
                "username" : "viewer.testbank"
            }
        }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
        'data':{
            'id' : 'faaf9b16-fca0-42d5-809b-c6f6bc636a10',
            'organisation_id' : '89a5aa0e-ef84-4da7-83a2-cec9ab9aefa9',
            'attributes': {
                'email' : 'viewer.testbank@form3.tech',
                'role_ids' : ['1081014a-37a8-45c9-a40d-59c028a565d8'],
                'username' : 'viewer.testbank'
            }
        }
    }
    """
    req = requests.post('https://api.form3.tech/v1/security/users', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "User",
        "id": "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "username" : "viewer.testbank",
            "email" : "viewer.testbank@form3.tech",
            "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"]
      },
      "links": {
        "self": "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
      }
    }
    
    {
      "data": {
        "type": "User",
        "id": "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "username" : "viewer.testbank",
            "email" : "viewer.testbank@form3.tech",
            "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"]
      },
      "links": {
        "self": "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
      }
    }
    
    {
      "data": {
        "type": "User",
        "id": "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "username" : "viewer.testbank",
            "email" : "viewer.testbank@form3.tech",
            "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"]
      },
      "links": {
        "self": "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
      }
    }
    

    Create a new user.

    HTTP Request

    POST /v1/security/users

    Attribute Description
    username string required User name
    email string required Email address
    role_ids array of UUID optional List of roles that this user belongs to

    Fetch

    Example request

    GET v1/security/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/security/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/security/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "User",
        "id": "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "username" : "viewer.testbank",
            "email" : "viewer.testbank@form3.tech",
            "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"]
      },
      "links": {
        "self": "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
      }
    }
    
    {
      "data": {
        "type": "User",
        "id": "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "username" : "viewer.testbank",
            "email" : "viewer.testbank@form3.tech",
            "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"]
      },
      "links": {
        "self": "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
      }
    }
    
    {
      "data": {
        "type": "User",
        "id": "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
            "username" : "viewer.testbank",
            "email" : "viewer.testbank@form3.tech",
            "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"]
      },
      "links": {
        "self": "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
      }
    }
    

    Get a single user using the user ID.

    HTTP Request

    GET /v1/security/users/{user_id}

    URL Parameter Description
    user_id string, unique identifier (UUID) User ID of the user to fetch

    List

    Example request

    GET /v1/security/users HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/security/users \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/security/users', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
              "type": "User",
              "id": "c6fb3d06-dbaa-4c51-8b7f-bbab1366a77d",
              "version": 0,
              "organisation_id": "1a734d34-3bc1-4c6d-aef2-17f8087c517c",
              "attributes": {
                "username": "submitter.testbank",
                "email": "submitter.testbank@form3.tech",
                "role_ids": [
                  "1c37f69c-d87b-4793-9201-6dc4c697376c"
                ]
              }
            },
            {
              "type": "User",
              "id": "4fcc03ee-4307-4d0e-8091-51b38cd3f019",
              "version": 0,
              "organisation_id": "1a734d34-3bc1-4c6d-aef2-17f8087c517c",
              "attributes": {
                "username": "approver.testbank",
                "email": "approver.testbank@form3.tech",
                "role_ids": [
                  "2474a939-9532-41da-a037-fd06571b7582"
                ]
              }
            }
        ],
        "links" : {
            "self" : "https://api.form3.tech/v1/users"
        }
    }
    
    {
        "data": [
            {
              "type": "User",
              "id": "c6fb3d06-dbaa-4c51-8b7f-bbab1366a77d",
              "version": 0,
              "organisation_id": "1a734d34-3bc1-4c6d-aef2-17f8087c517c",
              "attributes": {
                "username": "submitter.testbank",
                "email": "submitter.testbank@form3.tech",
                "role_ids": [
                  "1c37f69c-d87b-4793-9201-6dc4c697376c"
                ]
              }
            },
            {
              "type": "User",
              "id": "4fcc03ee-4307-4d0e-8091-51b38cd3f019",
              "version": 0,
              "organisation_id": "1a734d34-3bc1-4c6d-aef2-17f8087c517c",
              "attributes": {
                "username": "approver.testbank",
                "email": "approver.testbank@form3.tech",
                "role_ids": [
                  "2474a939-9532-41da-a037-fd06571b7582"
                ]
              }
            }
        ],
        "links" : {
            "self" : "https://api.form3.tech/v1/users"
        }
    }
    
    {
        "data": [
            {
              "type": "User",
              "id": "c6fb3d06-dbaa-4c51-8b7f-bbab1366a77d",
              "version": 0,
              "organisation_id": "1a734d34-3bc1-4c6d-aef2-17f8087c517c",
              "attributes": {
                "username": "submitter.testbank",
                "email": "submitter.testbank@form3.tech",
                "role_ids": [
                  "1c37f69c-d87b-4793-9201-6dc4c697376c"
                ]
              }
            },
            {
              "type": "User",
              "id": "4fcc03ee-4307-4d0e-8091-51b38cd3f019",
              "version": 0,
              "organisation_id": "1a734d34-3bc1-4c6d-aef2-17f8087c517c",
              "attributes": {
                "username": "approver.testbank",
                "email": "approver.testbank@form3.tech",
                "role_ids": [
                  "2474a939-9532-41da-a037-fd06571b7582"
                ]
              }
            }
        ],
        "links" : {
            "self" : "https://api.form3.tech/v1/users"
        }
    }
    

    List users with the ability to paginate.

    HTTP Request

    GET /v1/security/users?page[number]={page_number}&page[size]={page_size}

    Page parameters

    All fields are optional.

    Parameter Default Description
    page[number] 0 Page number being requested (starting from zero)
    page[size] 1000 Size of the page being requested

    Patch

    Example request

    PATCH /v1/security/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10 HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
        "data":{
            "id" : "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
            "version" : 0,
            "organisation_id" : "89a5aa0e-ef84-4da7-83a2-cec9ab9aefa9",
            "attributes": {
                "email" : "new.viewer.testbank@form3.tech"
            }
        }
    }
    
    curl -X PATCH -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/security/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10
    
    {
        "data":{
            "id" : "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
            "version" : 0,
            "organisation_id" : "89a5aa0e-ef84-4da7-83a2-cec9ab9aefa9",
            "attributes": {
                "email" : "new.viewer.testbank@form3.tech"
            }
        }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
        'data':{
            'id' : 'faaf9b16-fca0-42d5-809b-c6f6bc636a10',
            'version' : 0,
            'organisation_id' : '89a5aa0e-ef84-4da7-83a2-cec9ab9aefa9',
            'attributes': {
                'email' : 'new.viewer.testbank@form3.tech'
            }
        }
    }
    """
    req = requests.patch('https://api.form3.tech/v1/security/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10', json=json, headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data":{
            "type" : "User",
            "id" : "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
            "version" : 1,
            "organisation_id" : "89a5aa0e-ef84-4da7-83a2-cec9ab9aefa9",
            "attributes": {
                "email" : "new.viewer.testbank@form3.tech",
                "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"],
                "username" : "viewer.testbank"
            }
        },
        "links" : {
            "self" : "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10"
        }
    }
    
    {
        "data":{
            "type" : "User",
            "id" : "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
            "version" : 1,
            "organisation_id" : "89a5aa0e-ef84-4da7-83a2-cec9ab9aefa9",
            "attributes": {
                "email" : "new.viewer.testbank@form3.tech",
                "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"],
                "username" : "viewer.testbank"
            }
        },
        "links" : {
            "self" : "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10"
        }
    }
    
    {
        "data":{
            "type" : "User",
            "id" : "faaf9b16-fca0-42d5-809b-c6f6bc636a10",
            "version" : 1,
            "organisation_id" : "89a5aa0e-ef84-4da7-83a2-cec9ab9aefa9",
            "attributes": {
                "email" : "new.viewer.testbank@form3.tech",
                "role_ids" : ["1081014a-37a8-45c9-a40d-59c028a565d8"],
                "username" : "viewer.testbank"
            }
        },
        "links" : {
            "self" : "https://api.form3.tech/v1/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10"
        }
    }
    

    Update user details. Note that any attribute field that isn't passed is defaulted to the previous value.

    HTTP Request

    PATCH /v1/security/users/{user_id}

    URL Parameter Description
    user_id ID of the user to update

    Request Body

    Attribute Description
    version integer required Version number of the resource to patch. Has to be the latest version of the resource.
    Note that the attribute is located on the top level of the resource, not on the attributes sub level (see code example).
    username string optional User name
    email string optional Email address
    role_ids array of UUID optional List of roles that this user belongs to

    Delete

    Example request

    DELETE /v1/security/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10?version=1 HTTP/1.1
    
    curl -X DELETE https://api.form3.tech//v1/security/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10?version=1
    
    import requests
    requests.delete('https://api.form3.tech//v1/security/users/faaf9b16-fca0-42d5-809b-c6f6bc636a10?version=1')
    

    Response (204 No Content)

    Delete a user.

    HTTP Request

    DELETE /v1/security/users/{user_id}?version={version_number}

    URL Parameter Description
    user_id string, unique identifier (UUID), required User ID of user to delete
    version_number integer, required Version number of record

    HTTP Response

    Code Meaning Description
    204 No Content Resource has been successfully deleted
    404 Not Found Specified resource does not exist
    409 Conflict Specified version incorrect

    Fetch ACL

    Example request

    GET v1/security/users/aeb5179a-2c51-4c51-bf10-d17480060dd8/aces?filter[record_type]=Subscription HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/security/users/aeb5179a-2c51-4c51-bf10-d17480060dd8/aces?filter[record_type]=Subscription \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/security/users/aeb5179a-2c51-4c51-bf10-d17480060dd8/aces?filter[record_type]=Subscription', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": [
        {
          "type": "ace",
          "id": "aeb5179a-2c51-4c51-bf10-d17480060dd8",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "READ",
            "record_type": "Subscription"
          }
        },
        {
          "type": "ace",
          "id": "6e89b6fc-0de6-45d7-91ee-bb1ac596f407",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "CREATE",
            "record_type": "Subscription"
          }
        },
        {
          "type": "ace",
          "id": "1885a640-2828-4f1a-8bd9-d55dc3f6368e",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "EDIT",
            "record_type": "Subscription"
          }
        },
        {
          "type": "ace",
          "id": "6edf6c1e-3df1-48e0-b070-48181e9c2e7d",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "DELETE",
            "record_type": "Subscription"
          }
        }
      ],
      "links": {
        "self": "https://api.form3.tech/v1/users/a1e818a5-a45b-4c88-810a-db241de62a1f/aces"
      }
    }
    
    {
      "data": [
        {
          "type": "ace",
          "id": "aeb5179a-2c51-4c51-bf10-d17480060dd8",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "READ",
            "record_type": "Subscription"
          }
        },
        {
          "type": "ace",
          "id": "6e89b6fc-0de6-45d7-91ee-bb1ac596f407",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "CREATE",
            "record_type": "Subscription"
          }
        },
        {
          "type": "ace",
          "id": "1885a640-2828-4f1a-8bd9-d55dc3f6368e",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "EDIT",
            "record_type": "Subscription"
          }
        },
        {
          "type": "ace",
          "id": "6edf6c1e-3df1-48e0-b070-48181e9c2e7d",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "DELETE",
            "record_type": "Subscription"
          }
        }
      ],
      "links": {
        "self": "https://api.form3.tech/v1/users/a1e818a5-a45b-4c88-810a-db241de62a1f/aces"
      }
    }
    
    {
      "data": [
        {
          "type": "ace",
          "id": "aeb5179a-2c51-4c51-bf10-d17480060dd8",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "READ",
            "record_type": "Subscription"
          }
        },
        {
          "type": "ace",
          "id": "6e89b6fc-0de6-45d7-91ee-bb1ac596f407",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "CREATE",
            "record_type": "Subscription"
          }
        },
        {
          "type": "ace",
          "id": "1885a640-2828-4f1a-8bd9-d55dc3f6368e",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "EDIT",
            "record_type": "Subscription"
          }
        },
        {
          "type": "ace",
          "id": "6edf6c1e-3df1-48e0-b070-48181e9c2e7d",
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "role_id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
            "action": "DELETE",
            "record_type": "Subscription"
          }
        }
      ],
      "links": {
        "self": "https://api.form3.tech/v1/users/a1e818a5-a45b-4c88-810a-db241de62a1f/aces"
      }
    }
    

    Retrieve the full Access Control List (ACL) for the specified user with the ability to filter.

    HTTP Request

    GET /v1/security/users/{user_id}/aces?filter[{attribute}]={filter_value}

    URL Parameter Description
    user_id string, unique identifier (UUID), required User ID
    filter[record_type] string Filter by specific record type e.g. payments
    filter[action] string Filter by specific action e.g. EDIT, DELETE, CREATE

    Fetch Roles

    Example request

    GET v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": [
        {
          "type": "roles",
          "id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
          "version": 0,
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "name": "Subscription Manager Role"
          }
        }
      ],
      "links": {
        "self": "https://api.form3.tech/v1/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles"
      }
    }
    
    {
      "data": [
        {
          "type": "roles",
          "id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
          "version": 0,
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "name": "Subscription Manager Role"
          }
        }
      ],
      "links": {
        "self": "https://api.form3.tech/v1/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles"
      }
    }
    
    {
      "data": [
        {
          "type": "roles",
          "id": "8e8dabce-452e-4205-b3bc-aa5c32b283f9",
          "version": 0,
          "organisation_id": "105a7b00-acd7-4aba-a8df-a9b98b728239",
          "attributes": {
            "name": "Subscription Manager Role"
          }
        }
      ],
      "links": {
        "self": "https://api.form3.tech/v1/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles"
      }
    }
    

    Get a list of all the role records belonging to a specified user using the user ID.

    HTTP Request

    GET /v1/security/users/{user_id}/roles

    URL Parameter Description
    user_id string, unique identifier (UUID), required User ID of the user to fetch roles for

    Add Role

    Example request

    POST v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles/8e8dabce-452e-4205-b3bc-aa5c32b283f9 HTTP/1.1
    Content-Type: application/vnd.api+json
    
    
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech/v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles/8e8dabce-452e-4205-b3bc-aa5c32b283f9
    
    
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    
    """
    req = requests.post('https://api.form3.techv1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles/8e8dabce-452e-4205-b3bc-aa5c32b283f9', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    
    
    
    
    
    

    Add a specific role to a user using the role ID and the user ID.

    HTTP Request

    POST /v1/security/users/{user_id}/roles/{role_id}

    URL Parameter Description
    user_id string, unique identifier (UUID), required User ID of the user to add the role to
    role_id string, unique identifier (UUID), required Role ID of the role that should be added

    Delete Role

    Example request

    DELETE /v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles/8e8dabce-452e-4205-b3bc-aa5c32b283f9 HTTP/1.1
    
    curl -X DELETE https://api.form3.tech//v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles/8e8dabce-452e-4205-b3bc-aa5c32b283f9
    
    import requests
    requests.delete('https://api.form3.tech//v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/roles/8e8dabce-452e-4205-b3bc-aa5c32b283f9')
    

    Response (204 No Content)

    Remove a specific role from a user using the role ID and the user ID.

    HTTP Request

    DELETE /v1/security/users/{user_id}/roles/{role_id}

    URL Parameter Description
    user_id string, unique identifier (UUID), required User ID of user to remove the role from
    role_id string, unique identifier (UUID), required Role ID of the role to Remove

    HTTP Response

    Code Meaning Description
    204 No Content Resource has been successfully deleted
    404 Not Found Specified resource does not exist
    409 Conflict Specified version incorrect

    Create Credentials

    Example request

    POST /v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/credentials HTTP/1.1
    Content-Type: application/vnd.api+json
    
    
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/credentials
    
    
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    
    """
    req = requests.post('https://api.form3.tech/v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/credentials', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
        "data": {
            "client_id": "34d710b3-f647-4fef-ae6b-e271fec05eea",
            "client_secret": "3937c1b9-8d8a-406a-815a-aa2a3c4f8c5c"
        }
    }
    
    {
        "data": {
            "client_id": "34d710b3-f647-4fef-ae6b-e271fec05eea",
            "client_secret": "3937c1b9-8d8a-406a-815a-aa2a3c4f8c5c"
        }
    }
    
    {
        "data": {
            "client_id": "34d710b3-f647-4fef-ae6b-e271fec05eea",
            "client_secret": "3937c1b9-8d8a-406a-815a-aa2a3c4f8c5c"
        }
    }
    

    Generate new credentials for a user. This is the only way to obtain the client secret for a user and that each call creates a new set of client_id and client_secret. Existing credentials for this user remain valid. We recommend deleting old credentials after creating new ones.

    HTTP Request

    POST /v1/security/users/{user_id}/credentials

    URL Parameter Description
    user_id string, unique identifier (UUID), required ID of the user to create credentials for

    Fetch Credentials

    Example request

    GET /v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/credentials HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/credentials \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/credentials', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "client_id": "34d710b3-f647-4fef-ae6b-e271fec05eea"
        }
    }
    
    {
        "data": {
            "client_id": "34d710b3-f647-4fef-ae6b-e271fec05eea"
        }
    }
    
    {
        "data": {
            "client_id": "34d710b3-f647-4fef-ae6b-e271fec05eea"
        }
    }
    

    Fetch credentials for a user. Note that only the client ID is returned, never the client secret. If you forget your client secret, create a new set of credentials using the create credentials call.

    HTTP Request

    GET /v1/security/users/{user_id}/credentials

    URL Parameter Description
    user_id string, unique identifier (UUID), required ID of the user to fetch credentials for

    Delete Credentials

    Example request

    DELETE /v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/credentials/34d710b3-f647-4fef-ae6b-e271fec05eea HTTP/1.1
    
    curl -X DELETE https://api.form3.tech//v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/credentials/34d710b3-f647-4fef-ae6b-e271fec05eea
    
    import requests
    requests.delete('https://api.form3.tech//v1/security/users/a1e818a5-a45b-4c88-810a-db241de62a1f/credentials/34d710b3-f647-4fef-ae6b-e271fec05eea')
    

    Response (204 No Content)

    Delete credentials for a user. It is recommended to delete old credentials after creating a new set.

    HTTP Request

    DELETE /v1/security/users/{user_id}/credentials/{client_id}

    URL Parameter Description
    user_id string, unique identifier (UUID), required ID of the user to delete credentials for
    client_id string, unique identifier (UUID), required Client ID of the credentials to delete

    HTTP Response

    Code Meaning Description
    204 No Content Resource has been successfully deleted
    404 Not Found Specified resource does not exist
    409 Conflict Specified version incorrect

    Roles

    The Role resource groups access permissions (ACEs) to functions in the system. A user is granted permissions by assigning a role to them.

    A role can have a parent role that it inherits all ACEs from. Roles only inherit ACEs from their direct parent, parent-of-parent inheritance is not supported.

    Resource

    Example role resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "roles",
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c"
      }
    }
    
    {
      "data": {
        "type": "roles",
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c"
      }
    }
    
    {
      "data": {
        "type": "roles",
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c"
      }
    }
    
    Attribute Description
    name string Name of the role
    parent_role_id string, unique identifier (UUID) ID of the parent role that this role inherits its ACEs from

    Create

    Example request

    POST /v1/security/roles HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/security/roles
    
    {
      "data": {
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'id': '1742503e-c8b5-4572-b91f-449fb27e4b2c',
        'organisation_id': '743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb',
        'attributes': {
          'name': 'Read-only Role',
          'parent_role_id': '9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba'
        }
      }
    }
    """
    req = requests.post('https://api.form3.tech/v1/security/roles', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "roles",
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c"
      }
    }
    
    {
      "data": {
        "type": "roles",
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c"
      }
    }
    
    {
      "data": {
        "type": "roles",
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c"
      }
    }
    

    Create a new role.

    HTTP Request

    POST /v1/security/roles

    Attribute Description
    name string required Name of the role
    parent_role_id string, unique identifier (UUID) optional ID of a parent role that this role inherits its ACEs from

    Fetch

    Example request

    GET v1/security/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/security/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/security/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "roles",
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c"
      }
    }
    
    {
      "data": {
        "type": "roles",
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c"
      }
    }
    
    {
      "data": {
        "type": "roles",
        "id": "1742503e-c8b5-4572-b91f-449fb27e4b2c",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "name": "Read-only Role",
          "parent_role_id": "9ecd590c-2fd6-4a4c-98a5-26ede6ccc9ba"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/1742503e-c8b5-4572-b91f-449fb27e4b2c"
      }
    }
    

    Fetch a single role using the role ID.

    HTTP Request

    GET /v1/security/roles/{role_id}

    URL Parameter Description
    role_id string, unique identifier (UUID) Role ID of the role to fetch

    List

    Example request

    GET /v1/security/roles HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/security/roles \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/security/roles', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
              "type": "roles",
              "id": "b603aae9-c230-4084-99b4-6e733ca9781c",
              "version": 0,
              "organisation_id": "546e4deb-937e-4229-aeb2-1c0a4b843e69",
              "attributes": {
                "name": "ViewerRole"
              }
            },
            {
              "type": "roles",
              "id": "beb86ce2-ba64-4610-8040-6e007eb84534",
              "version": 0,
              "organisation_id": "e5843c10-8856-4042-aee5-f3f24ac24581",
              "attributes": {
                "name": "SubmitterRole"
              }
            },
            {
              "type": "roles",
              "id": "1b92c1e6-d3f1-4f90-8a89-ec5ffdb5173f",
              "version": 0,
              "organisation_id": "e5843c10-8856-4042-aee5-f3f24ac24581",
              "attributes": {
                "name": "ApprovalRole"
              }
            }
        ],
        "links": {
            "self": "https://api.form3.tech/v1/roles"
        }
    }
    
    {
        "data": [
            {
              "type": "roles",
              "id": "b603aae9-c230-4084-99b4-6e733ca9781c",
              "version": 0,
              "organisation_id": "546e4deb-937e-4229-aeb2-1c0a4b843e69",
              "attributes": {
                "name": "ViewerRole"
              }
            },
            {
              "type": "roles",
              "id": "beb86ce2-ba64-4610-8040-6e007eb84534",
              "version": 0,
              "organisation_id": "e5843c10-8856-4042-aee5-f3f24ac24581",
              "attributes": {
                "name": "SubmitterRole"
              }
            },
            {
              "type": "roles",
              "id": "1b92c1e6-d3f1-4f90-8a89-ec5ffdb5173f",
              "version": 0,
              "organisation_id": "e5843c10-8856-4042-aee5-f3f24ac24581",
              "attributes": {
                "name": "ApprovalRole"
              }
            }
        ],
        "links": {
            "self": "https://api.form3.tech/v1/roles"
        }
    }
    
    {
        "data": [
            {
              "type": "roles",
              "id": "b603aae9-c230-4084-99b4-6e733ca9781c",
              "version": 0,
              "organisation_id": "546e4deb-937e-4229-aeb2-1c0a4b843e69",
              "attributes": {
                "name": "ViewerRole"
              }
            },
            {
              "type": "roles",
              "id": "beb86ce2-ba64-4610-8040-6e007eb84534",
              "version": 0,
              "organisation_id": "e5843c10-8856-4042-aee5-f3f24ac24581",
              "attributes": {
                "name": "SubmitterRole"
              }
            },
            {
              "type": "roles",
              "id": "1b92c1e6-d3f1-4f90-8a89-ec5ffdb5173f",
              "version": 0,
              "organisation_id": "e5843c10-8856-4042-aee5-f3f24ac24581",
              "attributes": {
                "name": "ApprovalRole"
              }
            }
        ],
        "links": {
            "self": "https://api.form3.tech/v1/roles"
        }
    }
    

    List all roles with ability to paginate.

    HTTP Request

    GET /v1/security/roles?page[number]={page_number}&page[size]={page_size}

    Page parameters

    All fields are optional.

    Parameter Default Description
    page[number] 0 Page number being requested (starting from zero)
    page[size] 1000 Size of the page being requested

    ACE

    Access Control Entries define individual rights for access to carry out a specific action on a specific record type for a specific organisation.

    Resource

    Example ACE

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data" : {
            "type" : "ace",
            "id" : "e2f01974-3a65-4410-be4d-3cb08d75f677",
            "version" : 0,
            "organisation_id" : "6a465dd8-332a-4d52-9e14-c07b33ef23f3",
            "attributes" : {
                "role_id" : "7104597f-1da5-4aeb-bc5d-a3013034406e",
                "action" : "READ",
                "record_type" : "payments"
            }
        }
    }
    
    {
        "data" : {
            "type" : "ace",
            "id" : "e2f01974-3a65-4410-be4d-3cb08d75f677",
            "version" : 0,
            "organisation_id" : "6a465dd8-332a-4d52-9e14-c07b33ef23f3",
            "attributes" : {
                "role_id" : "7104597f-1da5-4aeb-bc5d-a3013034406e",
                "action" : "READ",
                "record_type" : "payments"
            }
        }
    }
    
    {
        "data" : {
            "type" : "ace",
            "id" : "e2f01974-3a65-4410-be4d-3cb08d75f677",
            "version" : 0,
            "organisation_id" : "6a465dd8-332a-4d52-9e14-c07b33ef23f3",
            "attributes" : {
                "role_id" : "7104597f-1da5-4aeb-bc5d-a3013034406e",
                "action" : "READ",
                "record_type" : "payments"
            }
        }
    }
    
    Attribute Description
    role_id UUID Role ID of the role that this ACE belongs to
    action string Action that this ACE controls. See here for a list of valid actions.
    record_type string Type of record that this ACE gives access to. See here for a list of valid record types

    Create ACE

    Example request

    POST /v1/security/roles/7104597f-1da5-4aeb-bc5d-a3013034406e/aces HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id":"e2f01974-3a65-4410-be4d-3cb08d75f677",
            "organisation_id" : "6a465dd8-332a-4d52-9e14-c07b33ef23f3",
            "attributes" : {
                "action":"READ",
                "record_type":"payments",
                "role_id": "7104597f-1da5-4aeb-bc5d-a3013034406e"
            }
        }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/security/roles/7104597f-1da5-4aeb-bc5d-a3013034406e/aces
    
    {
        "data": {
            "id":"e2f01974-3a65-4410-be4d-3cb08d75f677",
            "organisation_id" : "6a465dd8-332a-4d52-9e14-c07b33ef23f3",
            "attributes" : {
                "action":"READ",
                "record_type":"payments",
                "role_id": "7104597f-1da5-4aeb-bc5d-a3013034406e"
            }
        }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
        'data': {
            'id':'e2f01974-3a65-4410-be4d-3cb08d75f677',
            'organisation_id' : '6a465dd8-332a-4d52-9e14-c07b33ef23f3',
            'attributes' : {
                'action':'READ',
                'record_type':'payments',
                'role_id': '7104597f-1da5-4aeb-bc5d-a3013034406e'
            }
        }
    }
    """
    req = requests.post('https://api.form3.tech/v1/security/roles/7104597f-1da5-4aeb-bc5d-a3013034406e/aces', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
        "data" : {
            "type" : "ace",
            "id" : "e2f01974-3a65-4410-be4d-3cb08d75f677",
            "version" : 0,
            "organisation_id" : "6a465dd8-332a-4d52-9e14-c07b33ef23f3",
            "attributes" : {
                "role_id" : "7104597f-1da5-4aeb-bc5d-a3013034406e",
                "action" : "READ",
                "record_type" : "payments"
            }
        }
    }
    
    {
        "data" : {
            "type" : "ace",
            "id" : "e2f01974-3a65-4410-be4d-3cb08d75f677",
            "version" : 0,
            "organisation_id" : "6a465dd8-332a-4d52-9e14-c07b33ef23f3",
            "attributes" : {
                "role_id" : "7104597f-1da5-4aeb-bc5d-a3013034406e",
                "action" : "READ",
                "record_type" : "payments"
            }
        }
    }
    
    {
        "data" : {
            "type" : "ace",
            "id" : "e2f01974-3a65-4410-be4d-3cb08d75f677",
            "version" : 0,
            "organisation_id" : "6a465dd8-332a-4d52-9e14-c07b33ef23f3",
            "attributes" : {
                "role_id" : "7104597f-1da5-4aeb-bc5d-a3013034406e",
                "action" : "READ",
                "record_type" : "payments"
            }
        }
    }
    

    Create a new Access Control Entry (ACE) and add it to a role.

    HTTP Request

    POST /v1/security/roles/{role_id}/aces

    URL Parameter Description
    role_id UUID required Role ID of the role that the ACE should be added to

    Request and Response Body

    Attribute Description
    role_id UUID required Role ID of the role that this ACE belongs to
    action string required Action that this ACE controls. See here for a list of valid actions.
    record_type string required Type of record that this ACE gives access to. See here for a list of valid record types

    Fetch ACE

    Example request

    GET v1/security/roles/32881d6b-a000-4258-b779-56c59970590f/aces/7dbff98f-920d-49a6-890e-8c435f1279de HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/security/roles/32881d6b-a000-4258-b779-56c59970590f/aces/7dbff98f-920d-49a6-890e-8c435f1279de \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/security/roles/32881d6b-a000-4258-b779-56c59970590f/aces/7dbff98f-920d-49a6-890e-8c435f1279de', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "ace",
        "id": "7dbff98f-920d-49a6-890e-8c435f1279de",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "role_id": "32881d6b-a000-4258-b779-56c59970590f",
          "action": "READ",
          "record_type": "Organisation"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/32881d6b-a000-4258-b779-56c59970590f/aces/7dbff98f-920d-49a6-890e-8c435f1279de"
      }
    }
    
    {
      "data": {
        "type": "ace",
        "id": "7dbff98f-920d-49a6-890e-8c435f1279de",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "role_id": "32881d6b-a000-4258-b779-56c59970590f",
          "action": "READ",
          "record_type": "Organisation"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/32881d6b-a000-4258-b779-56c59970590f/aces/7dbff98f-920d-49a6-890e-8c435f1279de"
      }
    }
    
    {
      "data": {
        "type": "ace",
        "id": "7dbff98f-920d-49a6-890e-8c435f1279de",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "role_id": "32881d6b-a000-4258-b779-56c59970590f",
          "action": "READ",
          "record_type": "Organisation"
        }
      },
      "links": {
        "self": "https://api.form3.tech/v1/roles/32881d6b-a000-4258-b779-56c59970590f/aces/7dbff98f-920d-49a6-890e-8c435f1279de"
      }
    }
    

    Fetch a single ACE for a specific role using the ACE ID and the role ID.

    HTTP Request

    POST /v1/security/roles/{role_id}/aces/{ace_id}

    Parameter Description
    role_id UUID, required Role ID of the role that the ACE is assigned to
    ace_id UUID, required ACE ID of the ACE that should be fetched

    List ACE

    Example request

    GET /v1/security/roles/32881d6b-a000-4258-b779-56c59970590f/aces HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/security/roles/32881d6b-a000-4258-b779-56c59970590f/aces \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/security/roles/32881d6b-a000-4258-b779-56c59970590f/aces', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
              "type": "ace",
              "id": "7dbff98f-920d-49a6-890e-8c435f1279de",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "role_id": "32881d6b-a000-4258-b779-56c59970590f",
                "action": "READ",
                "record_type": "Organisation"
              }
            },
            {
              "type": "ace",
              "id": "f74dd399-87ce-4aae-8da8-477442d64a06",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "role_id": "32881d6b-a000-4258-b779-56c59970590f",
                "action": "CREATE_APPROVE",
                "record_type": "Organisation"
              }
            },
            {
              "type": "ace",
              "id": "77df890e-75cc-41c1-a81e-7912310e53a9",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "role_id": "32881d6b-a000-4258-b779-56c59970590f",
                "action": "EDIT_APPROVE",
                "record_type": "Organisation"
              }
            }
        ],
      "links": {
        "self": "https://api.form3.tech/v1/roles/32881d6b-a000-4258-b779-56c59970590f/aces"
      }
    }
    
    {
        "data": [
            {
              "type": "ace",
              "id": "7dbff98f-920d-49a6-890e-8c435f1279de",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "role_id": "32881d6b-a000-4258-b779-56c59970590f",
                "action": "READ",
                "record_type": "Organisation"
              }
            },
            {
              "type": "ace",
              "id": "f74dd399-87ce-4aae-8da8-477442d64a06",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "role_id": "32881d6b-a000-4258-b779-56c59970590f",
                "action": "CREATE_APPROVE",
                "record_type": "Organisation"
              }
            },
            {
              "type": "ace",
              "id": "77df890e-75cc-41c1-a81e-7912310e53a9",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "role_id": "32881d6b-a000-4258-b779-56c59970590f",
                "action": "EDIT_APPROVE",
                "record_type": "Organisation"
              }
            }
        ],
      "links": {
        "self": "https://api.form3.tech/v1/roles/32881d6b-a000-4258-b779-56c59970590f/aces"
      }
    }
    
    {
        "data": [
            {
              "type": "ace",
              "id": "7dbff98f-920d-49a6-890e-8c435f1279de",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "role_id": "32881d6b-a000-4258-b779-56c59970590f",
                "action": "READ",
                "record_type": "Organisation"
              }
            },
            {
              "type": "ace",
              "id": "f74dd399-87ce-4aae-8da8-477442d64a06",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "role_id": "32881d6b-a000-4258-b779-56c59970590f",
                "action": "CREATE_APPROVE",
                "record_type": "Organisation"
              }
            },
            {
              "type": "ace",
              "id": "77df890e-75cc-41c1-a81e-7912310e53a9",
              "version": 0,
              "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
              "attributes": {
                "role_id": "32881d6b-a000-4258-b779-56c59970590f",
                "action": "EDIT_APPROVE",
                "record_type": "Organisation"
              }
            }
        ],
      "links": {
        "self": "https://api.form3.tech/v1/roles/32881d6b-a000-4258-b779-56c59970590f/aces"
      }
    }
    

    List all ACEs for the specified role using the role ID.

    HTTP Request

    GET /v1/security/roles/{role_id}/aces

    Parameter Description
    role_id UUID, required Role ID of the role that ACEs should be listed for

    Delete ACE

    Example request

    DELETE /v1/security/roles/32881d6b-a000-4258-b779-56c59970590f/aces/77df890e-75cc-41c1-a81e-7912310e53a9 HTTP/1.1
    
    curl -X DELETE https://api.form3.tech//v1/security/roles/32881d6b-a000-4258-b779-56c59970590f/aces/77df890e-75cc-41c1-a81e-7912310e53a9
    
    import requests
    requests.delete('https://api.form3.tech//v1/security/roles/32881d6b-a000-4258-b779-56c59970590f/aces/77df890e-75cc-41c1-a81e-7912310e53a9')
    

    Response (204 No Content)

    Remove a specific ACE from a role using the ACE ID and the role ID.

    HTTP Request

    DELETE /v1/security/roles/{role_id}/aces/{ace_id}

    Parameter Description
    role_id UUID, required Role ID of the role that the ACE is assigned to
    ace_id UUID, required ACE ID of the ACE that should be removed from the role

    HTTP Response

    Code Meaning Description
    204 No Content Resource has been successfully deleted
    404 Not Found Specified resource does not exist
    409 Conflict Specified version incorrect

    Actions

    The action attribute of an ACE determines which action it allows. The following actions exist in the Form3 API:

    Value Description
    READ All calls using HTTP GET requests, such as fetch and list
    CREATE and CREATE_APPROVE All calls using HTTP POST requests, such as create
    EDIT and EDIT_APPROVE All calls using HTTP PATCH requests, such as edit and patch
    DELETE and DELETE_APPROVE All calls using HTTP DELETE requests, such as delete

    Depending on what capabilities a role should have, a different combination of actions is required:

    Note that the X_APPROVAL actions will be removed from the API in the near future. However, currently some endpoints require ACEs with these actions to allow create, edit, and delete access. Until they are removed, it is recommended to always create an ACE for the X action and another for X_APPROVE.

    Record Types

    The following values are valid for the record_type attribute of the ACE resource. Note that some record types are spelled using CamelCase while others use snake_case. Most record types support both spellings. It is recommended to create ACEs for all spellings to ensure your user has all required permissions.

    Record Type
    recall_submissions / RecallSubmission
    direct_debit_reversal_admissions / DirectDebitReversalAdmission
    direct_debit_admissions / DirectDebitAdmission
    mandate_admissions / MandateAdmission
    Balance
    recall_decision_submissions / RecallDecisionSubmission
    payment_admissions / PaymentAdmission
    reversal_admissions / ReversalAdmission
    return_reversal_admissions / ReturnReversalAdmission
    return_reversals / ReturnReversal
    return_admissions / ReturnAdmission
    reversals / Reversal
    Position
    direct_debits / DirectDebit
    direct_debit_reversals / DirectDebitReversal
    Ace
    Subscription
    payments / Payment
    Organisation
    recall_decisions / RecallDecision
    direct_debit_return_submissions / DirectDebitReturnSubmission
    returns / Return
    roles / Role
    payment_submissions / PaymentSubmission
    claims
    return_submissions / ReturnSubmission
    User
    accounts / Account
    claim_submissions
    scheme_messages
    recalls / Recall
    direct_debit_returns / DirectDebitReturn
    reversal_submissions / ReversalSubmission
    mandates / Mandate
    recall_decision_admissions / RecallDecisionAdmission
    recall_reversals / RecallReversal
    recall_reversal_admissions / RecallReversalAdmission
    mandate_submissions / MandateSubmission
    payment_advice_submissions / AdviceSubmission
    claim_reversal_submissions
    payment_advices / Advice
    claim_reversals
    mandate_return_submissions
    mandate_returns
    reports
    report_admissions

    Validation

    GBDSC

    Validate UK Domestic Sort Codes and perform modulus checks on account numbers.

    Sort codes are checked against the Extended Industry Sorting Code Directory (EISCD). In our production environment, records are updated weekly as they are published by VocaLink. In staging, records are updated frequently, but sometimes with a slight delay.

    Sort code validation

    Example request

    GET v1/validations/gbdsc/sortcodes/123456 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/validations/gbdsc/sortcodes/123456 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/validations/gbdsc/sortcodes/123456', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "sort_codes",
        "id": "123456",
        "attributes": {
            "bank_name": "BANK NAME LIMITED",
            "bank_office_title": "OFFICE",
            "supported_schemes": {
                "BACS": {
                    "accepts_payments": true,
                    "service_status": "A"
                },
                "CCC": {
                    "accepts_payments": true,
                    "service_status": "A"
                },
                "CHAPS": {
                    "accepts_payments": true,
                    "service_status": "I"
                },
                "FPS": {
                    "accepts_payments": true,
                    "service_status": "M"
                }
            }
        }
      }
    }
    
    
    {
      "data": {
        "type": "sort_codes",
        "id": "123456",
        "attributes": {
            "bank_name": "BANK NAME LIMITED",
            "bank_office_title": "OFFICE",
            "supported_schemes": {
                "BACS": {
                    "accepts_payments": true,
                    "service_status": "A"
                },
                "CCC": {
                    "accepts_payments": true,
                    "service_status": "A"
                },
                "CHAPS": {
                    "accepts_payments": true,
                    "service_status": "I"
                },
                "FPS": {
                    "accepts_payments": true,
                    "service_status": "M"
                }
            }
        }
      }
    }
    
    
    {
      "data": {
        "type": "sort_codes",
        "id": "123456",
        "attributes": {
            "bank_name": "BANK NAME LIMITED",
            "bank_office_title": "OFFICE",
            "supported_schemes": {
                "BACS": {
                    "accepts_payments": true,
                    "service_status": "A"
                },
                "CCC": {
                    "accepts_payments": true,
                    "service_status": "A"
                },
                "CHAPS": {
                    "accepts_payments": true,
                    "service_status": "I"
                },
                "FPS": {
                    "accepts_payments": true,
                    "service_status": "M"
                }
            }
        }
      }
    }
    
    

    Response (404 Not Found)

    HTTP/1.1 404 Not Found
    Content-Type: application/vnd.api+json
    
    {
        "error_message": "Sort code not found: 123456"
    }
    
    
    {
        "error_message": "Sort code not found: 123456"
    }
    
    
    {
        "error_message": "Sort code not found: 123456"
    }
    
    

    Validate a sort code and return the supported payment schemes

    HTTP Request

    GET v1/validations/gbdsc/sortcodes/{sort_code}

    URL Parameter Description
    sort_code string Sort code to validate

    Response body

    Attribute Description
    bank_name string The full name of the owning bank
    bank_office_title string The short bank office title
    supported_schemes​.BACS.accepts_payments boolean Determines whether the sort code accepts payments for this scheme or not
    supported_schemes​.BACS.service_status string The Bacs service status
    supported_schemes​.CCC.accepts_payments boolean Determines whether the sort code accepts payments for this scheme or not
    supported_schemes​.CCC.service_status string The CCC service status
    supported_schemes​.CHAPS.accepts_payments boolean Determines whether the sort code accepts payments for this scheme or not
    supported_schemes​.CHAPS.service_status string The CHAPS service status
    supported_schemes​.FPS.accepts_payments boolean Determines whether the sort code accepts payments for this scheme or not
    supported_schemes​.FPS.service_status string The FPS service status

    Error response

    If the sort code is not found, a 404 (Not Found) response is returned.

    Account number validation

    Example request

    GET v1/validations/gbdsc/sortcodes/123456/accountnumbers/12345678 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/validations/gbdsc/sortcodes/123456/accountnumbers/12345678 \
       -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/validations/gbdsc/sortcodes/123456/accountnumbers/12345678', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "account_numbers",
        "id": "12345678",
        "relationships": {
            "sort_code": {
                "type": "sort_codes",
                "id": "123456",
                "attributes": {
                    "bank_name": "BANK NAME LIMITED",
                    "bank_office_title": "OFFICE",
                    "supported_schemes": {
                        "BACS": {
                            "accepts_payments": true,
                            "service_status": "A"
                        },
                        "CCC": {
                            "accepts_payments": false,
                            "service_status": "N"
                        },
                        "CHAPS": {
                            "accepts_payments": true,
                            "service_status": "I"
                        },
                        "FPS": {
                            "accepts_payments": true,
                            "service_status": "M"
                        }
                    }
                }
            }
      }
    }
    
    
    {
      "data": {
        "type": "account_numbers",
        "id": "12345678",
        "relationships": {
            "sort_code": {
                "type": "sort_codes",
                "id": "123456",
                "attributes": {
                    "bank_name": "BANK NAME LIMITED",
                    "bank_office_title": "OFFICE",
                    "supported_schemes": {
                        "BACS": {
                            "accepts_payments": true,
                            "service_status": "A"
                        },
                        "CCC": {
                            "accepts_payments": false,
                            "service_status": "N"
                        },
                        "CHAPS": {
                            "accepts_payments": true,
                            "service_status": "I"
                        },
                        "FPS": {
                            "accepts_payments": true,
                            "service_status": "M"
                        }
                    }
                }
            }
      }
    }
    
    
    {
      "data": {
        "type": "account_numbers",
        "id": "12345678",
        "relationships": {
            "sort_code": {
                "type": "sort_codes",
                "id": "123456",
                "attributes": {
                    "bank_name": "BANK NAME LIMITED",
                    "bank_office_title": "OFFICE",
                    "supported_schemes": {
                        "BACS": {
                            "accepts_payments": true,
                            "service_status": "A"
                        },
                        "CCC": {
                            "accepts_payments": false,
                            "service_status": "N"
                        },
                        "CHAPS": {
                            "accepts_payments": true,
                            "service_status": "I"
                        },
                        "FPS": {
                            "accepts_payments": true,
                            "service_status": "M"
                        }
                    }
                }
            }
      }
    }
    
    

    Response MOD check failed (404 Not Found)

    HTTP/1.1 404 Not Found
    Content-Type: application/vnd.api+json
    
    {
        "error_message": "MOD check failed"
    }
    
    
    {
        "error_message": "MOD check failed"
    }
    
    
    {
        "error_message": "MOD check failed"
    }
    
    

    Response sort code not found (404 Not Found)

    HTTP/1.1 404 Not Found
    Content-Type: application/vnd.api+json
    
    {
        "error_message": "Sort code not found: 123456"
    }
    
    
    {
        "error_message": "Sort code not found: 123456"
    }
    
    
    {
        "error_message": "Sort code not found: 123456"
    }
    
    

    Validate a sort code and perform an account number modulus checking

    HTTP Request

    GET v1/validations/gbdsc/sortcodes/{sort_code}/accountnumbers/{account_number}

    URL Parameter Description
    sort_code string Sort code to validate
    account_number string Account number to validate

    Response body

    Attribute Description
    relationships.sort_code object The Sort Code resource related to the sort code mentioned in the sort_code URL parameter

    Error response

    If the validation fails, a 404 (Not Found) response is returned containing the reason for failure.

    error_message Description
    Sort code not found: 123456 The Sort Code could not be found
    MOD check failed The account number failed the modulus check validation

    Payments

    Overview

    The Payment resource is used to initiate new outgoing payments, update existing payments (in certain circumstances such as cancelling pending payments), and retrieve details of payments that were previously submitted or received.

    The resource is generic and designed to handle a wide range of payment schemes and methods of payment. Many of the fields map directly to elements of the ISO20022 and SWIFT payments standards.

    For more information about setting up and handling notifications of payment events, see the Notifications section as well as the list of common event subscriptions.

    Payments

    Resource

    Example payment resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "payments",
        "id": "20b1f7a2-83c7-45d3-a6e3-0a75b14b9f7f",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "231.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "71268996",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "400302",
              "bank_id_code": "GBDSC"
            },
            "country": "GB"
          },
          "currency": "GBP",
          "debtor_party": {
            "account_name": "Mr Sending Test",
            "account_number": "87654321",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "333333",
              "bank_id_code": "GBDSC"
            },
            "country": "GB"
          },
          "numeric_reference": "0001",
          "scheme_transaction_id": "17276758959",
          "payment_scheme": "FPS",
          "processing_date": "2019-03-29",
          "reference": "D/1234567890123456",
          "scheme_payment_sub_type": "TelephoneBanking",
          "scheme_payment_type": "ImmediatePayment"
        },
        "relationships": {
          "payment_submission": {
            "data": []
          },
          "payment_return": {
            "data": []
          },
          "payment_admission": {
            "data": []
          },
          "payment_reversal": {
            "data": []
          },
          "payment_recall": {
            "data": []
          },
          "payment_advice": {
            "data": []
          }
        }
      }
    }
    
    {
      "data": {
        "type": "payments",
        "id": "20b1f7a2-83c7-45d3-a6e3-0a75b14b9f7f",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "231.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "71268996",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "400302",
              "bank_id_code": "GBDSC"
            },
            "country": "GB"
          },
          "currency": "GBP",
          "debtor_party": {
            "account_name": "Mr Sending Test",
            "account_number": "87654321",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "333333",
              "bank_id_code": "GBDSC"
            },
            "country": "GB"
          },
          "numeric_reference": "0001",
          "scheme_transaction_id": "17276758959",
          "payment_scheme": "FPS",
          "processing_date": "2019-03-29",
          "reference": "D/1234567890123456",
          "scheme_payment_sub_type": "TelephoneBanking",
          "scheme_payment_type": "ImmediatePayment"
        },
        "relationships": {
          "payment_submission": {
            "data": []
          },
          "payment_return": {
            "data": []
          },
          "payment_admission": {
            "data": []
          },
          "payment_reversal": {
            "data": []
          },
          "payment_recall": {
            "data": []
          },
          "payment_advice": {
            "data": []
          }
        }
      }
    }
    
    {
      "data": {
        "type": "payments",
        "id": "20b1f7a2-83c7-45d3-a6e3-0a75b14b9f7f",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "231.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "71268996",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "400302",
              "bank_id_code": "GBDSC"
            },
            "country": "GB"
          },
          "currency": "GBP",
          "debtor_party": {
            "account_name": "Mr Sending Test",
            "account_number": "87654321",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "333333",
              "bank_id_code": "GBDSC"
            },
            "country": "GB"
          },
          "numeric_reference": "0001",
          "scheme_transaction_id": "17276758959",
          "payment_scheme": "FPS",
          "processing_date": "2019-03-29",
          "reference": "D/1234567890123456",
          "scheme_payment_sub_type": "TelephoneBanking",
          "scheme_payment_type": "ImmediatePayment"
        },
        "relationships": {
          "payment_submission": {
            "data": []
          },
          "payment_return": {
            "data": []
          },
          "payment_admission": {
            "data": []
          },
          "payment_reversal": {
            "data": []
          },
          "payment_recall": {
            "data": []
          },
          "payment_advice": {
            "data": []
          }
        }
      }
    }
    

    Below is a list of all available attribute fields. The availibility of each field depends on the API call and scheme. See the Create and Fetch call documentation for additional information for each field when performing these requests.

    Attribute Description
    amount string, pattern: ^[0-9.]{0,20}$ Amount of money moved between the instructing agent and instructed agent

    Bacs: Field8, automatically converted to pence when submitted to Bacs. Maximum value 20000000.00.

    FPS: Format uses decimal point. Maximum two decimals, value must be > 0. Maximum value 250000.00.

    SEPA Instant & SCT: Interbank settlement amount, must have 2 decimal places. Maximum value for SEPA Instant is 15000.00 (will change to 100000.00 on July 1, 2020), maximum value for SCT is 999999999999999.99.
    beneficiary_party.account_name string Name of beneficiary as given with account

    Bacs: Field11, maximum length 18 characters

    FPS: Maxiumum length 35 characters

    SEPA Instant & SCT: Maximum length 70 characters. If beneficiary name is different from account holder name, this field should contain account holder name and beneficiary_party.name should contain beneficiary name.
    beneficiary_party.account_number string Beneficiary account number

    Bacs: Field2, maximum length 8 characters

    FPS: Maximum length 8 characters

    SEPA Instant & SCT: Must be in IBAN format according to ISO 13616, maximum length 34 characters
    beneficiary_party.account_number_code string [4] The type of identification provided in account_number attribute

    FPS: Must be BBAN

    SEPA Instant & SCT: Must be IBAN
    beneficiary_party.account_type integer The type of the account given with beneficiary_party.account_number

    Bacs: Field3 (Defaults to 0), must be a single digit number

    FPS: Only required if requested by the beneficiary party. Defaults to 0, must be a single digit number.
    beneficiary_party.account_with.bank_address array Financial institution address
    beneficiary_party.account_with.bank_id string [11] Financial institution identification of the institution servicing the beneficiary account

    Bacs: Field1. Has to be a Bacs-addressable UK sort code. Maximum length 6 characters.

    FPS: UK sort code when bank_id_code is GBDSC. BIC8/11 if bank_id_code is SWBIC

    SEPA Instant & SCT: Must be a BIC
    beneficiary_party.account_with.bank_id_code string [5] The type of identification provided at bank_id attribute. Must be ISO code as listed in the External Code Sets spreadsheet

    FPS: Must be GBDSC (GB Domestic Sort Code)

    SEPA Instant & SCT: Must be SWBIC (SWIFT BIC)
    beneficiary_party.account_with.bank_name string [35] Financial institution name
    beneficiary_party.account_with.bank_party_id string [35] Identifier of the financial institution which services the account
    beneficiary_party.address array Beneficiary address

    SEPA Instant & SCT: Max 2 lines of 70 text
    beneficiary_party.birth_city string [35] Beneficiary birth city

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed.
    beneficiary_party.birth_country string [2] Beneficiary birth country, ISO 3166 format country code

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed.
    beneficiary_party.birth_date date Beneficiary birth date. Formatted according to ISO 8601 format: YYYY-MM-DD

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed.
    beneficiary_party.birth_province string [35] Beneficiary birth province

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed. Not supported for SEPA Indirect.
    beneficiary_party.country string [2] Country of the beneficiary address, ISO 3166 format country code
    beneficiary_party.name string [70] Beneficiary name

    SEPA Instant & SCT: Only used if different from beneficiary_party.account_name
    beneficiary_party.organisation_identification string [35] Organisation identification of the beneficiary, used in the case the beneficiary is an organisation and not a private person

    SEPA Instant & SCT: The kind of identification expected depends on the organisation_identification_code or organisation_identification_scheme, depending on which is provided. If organisation identification is present, neither private identification nor date and place of birth are allowed.
    beneficiary_party.organisation_identification_code string [4] Code to specify the type of organisation_identification

    SEPA Instant & SCT: If provided, must be a valid organisation identification code. Either this field or organisation_identification_scheme must be present if organisation_identification is specified, but never both.
    beneficiary_party.organisation_identification_scheme string [35] Code to specify a custom type of organisation_identification

    SEPA Instant & SCT: Use this field if the identification in organisation_identification is a custom internal code type. Either this field or organisation_identification_scheme must be present if organisation_identification is specified, but never both. Not supported for SEPA Indirect.
    beneficiary_party.organisation_identification_issuer string [35] Issuer of the organisation identification

    SEPA Instant & SCT: Not supported for SEPA Indirect
    beneficiary_party.private_identification.identification string [35] Private Identification of a beneficiary

    SEPA Instant & SCT: If private identification is present, neither organisation identification nor date and place of birth are allowed.
    beneficiary_party.private_identification.identification_scheme_code string The code specifying the type of identification

    SEPA Instant & SCT: If provided, must be a valid private identification scheme code. Either this field or private_identification.identification_scheme must be present if private_identification.identification is specified, but never both.
    beneficiary_party.private_identification.identification_scheme string [35] Scheme used for identification

    SEPA Instant & SCT: Either this field or private_identification.identification_scheme_code must be present if private_identification.identification is specified, but never both. Not supported for SEPA Indirect.
    beneficiary_party.private_identification.identification_issuer string Issuer of identification

    SEPA Instant & SCT: Maximum length 35 characters. Not supported for SEPA Indirect.
    beneficiary_party.telephone_number string [16] Beneficiary phone number
    category_purpose string [35] Category purpose in proprietary form. Specifies the high level purpose of the instruction. Cannot be used at the same time as category_purpose_coded.

    SEPA Instant & SCT: Not supported for SEPA Indirect.
    category_purpose_coded string [4] Category purpose in a coded form. Specifies the high level purpose of the instruction. Cannot be used at the same time as category_purpose.

    SEPA Instant & SCT: The codes used must be part of the ISO 20022 ExternalCategoryPurpose1Code list. Not supported for inbound payments with SEPA Indirect.
    charges_information.bearer_code string [4] Specifies which party/parties will bear the charges associated with the processing of the payment transaction. Can be one of the following: DEBT, CRED, SHAR or SLEV

    SEPA Instant & SCT: Only SLEV is allowed. Defaults to SLEV if no value is provided.
    charges_information.receiver_charges_amount string Transaction charges due to the receiver of the transaction. Requires 1 to 2 decimal places. Must be > 0.

    FPS: Maximum length 15 characters
    charges_information.receiver_charges_currency string [3] Currency of receiver_charges_amount. Currency code as defined in ISO 4217.
    charges_information.sender_charges.items object List of transaction charges due to the sender of the transaction
    charges_information.sender_charges.items.amount string Amount of transaction charges for this item

    FPS: Maximum length 15 characters
    charges_information.sender_charges.items.currency string Currency of amount, currency code as defined in ISO 4217
    clearing_id string [6] Unique identifier for organisations collecting payments

    Bacs: Bacs Service User Number (6 numeric digits). VOL1/Field7 HDR1/Field 3 EOF1/Field 3
    currency string [3] Currency of the transaction amount. Currency code as defined in ISO 4217

    Bacs: Field 32A: Digits 7-9

    SEPA Instant & SCT: Must be EUR
    debtor_party.account_name string Name of debtor as given with account

    Bacs: Field9, maximum length 18 characters

    FPS: Maximum length 35 characters

    SEPA Instant & SCT: Maximum length 70 characters. If debtor name is different from account holder name, this field should contain account holder name and debtor_party.name should contain debtor name.
    debtor_party.account_number string [34] Debtor account number. Allows upper case and numeric characters.

    Bacs: Field6, maximum length 8 characters

    FPS: Domestic account number if account_number_code is BBAN, IBAN if account_number_code is IBAN. Maximum length 34 characters.

    SEPA Instant & SCT: Must be in IBAN format according to ISO 13616, maximum length 34 characters
    debtor_party.account_number_code string [4] The type of identification given at account_number attribute

    FPS: BBAN for domestic debtors, IBAN if inbound payment originated overseas

    SEPA Instant & SCT: Must be IBAN
    debtor_party.account_with.bank_address array Financial institution address
    debtor_party.account_with.bank_id string [11] Financial institution identification

    Bacs: Field1

    FPS: UK sort code when bank_id_code is GBDSC. BIC8/11 if bank_id_code is SWBIC

    SEPA Instant & SCT: Must be a BIC
    debtor_party.account_with.bank_id_code string [5] The type of identification provided at bank_id attribute. Must be ISO code as listed in the External Code Sets spreadsheet

    FPS: Always GBDSC for outbound payments and inbound payment originated from a domestic account, SWBIC (SWIFT BIC) if inbound payment originated overseas

    SEPA Instant & SCT: Always has to be SWBIC (SWIFT BIC)
    debtor_party.account_with.bank_name string [35] Financial institution name
    debtor_party.account_with.bank_party_id string [35] Identifier of the financial institution which services the account
    debtor_party.address array Debtor address

    SEPA Instant & SCT: Max 2 lines of 70 text.
    debtor_party.birth_city string [35] Debtor birth city

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed. Not supported for outbound payments with SEPA Indirect.
    debtor_party.birth_country string [2] Debtor birth country. ISO 3166 format country code

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed. Not supported for outbound payments with SEPA Indirect.
    debtor_party.birth_date date Debtor birth date. Formatted according to ISO 8601 format: YYYY-MM-DD

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed. Not supported for outbound payments with SEPA Indirect.
    debtor_party.birth_province string [35] Debtor birth province

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed. Not supported for SEPA Indirect.
    debtor_party.country string [2] Country of debtor address. ISO 3166 format country code"
    debtor_party.customer_id string [11] SWIFT BIC for ordering customer, either BIC8 or BIC11
    debtor_party.customer_id_code string [5] Code for customer_id
    debtor_party.name string [70] Debtor name

    SEPA Instant & SCT: Only used if different from debtor_party.account_name
    debtor_party.organisation_identification string [35] Organisation identification of the debtor, used in the case the debtor is an organisation and not a private person

    SEPA Instant & SCT: The kind of identification expected depends on the organisation_identification_code or organisation_identification_scheme, depending on which is provided. If organisation identification is present, neither private identification nor date and place of birth are allowed. Not supported for outbound payments with SEPA Indirect.
    debtor_party.organisation_identification_code string [4] Code to specify the type of organisation_identification

    SEPA Instant & SCT:If provided, must be a valid organisation identification code. Either this field or organisation_identification_scheme must be present if organisation_identification is specified, but never both. Not supported for SEPA Indirect, code is inferred from customer configuration data at Form3.
    debtor_party.organisation_identification_scheme string [35] Code to specify a custom type of organisation_identification

    SEPA Instant & SCT: Use this field if the identification in organisation_identification is a custom internal code type. Either this field or organisation_identification_scheme must be present if organisation_identification is specified, but never both. Not supported for SEPA Indirect.
    debtor_party.organisation_identification_issuer string [35] Issuer of the organisation identification

    SEPA Instant & SCT: Not supported for SEPA Indirect
    debtor_party.private_identification.identification string [35] Private Identification of a debtor

    SEPA Instant & SCT: If private identification is present, neither organisation identification nor date and place of birth are allowed. Not supported for outbound payments with SEPA Indirect.
    debtor_party.private_identification.identification_scheme_code string The code specifying the type of identification

    SEPA Instant & SCT: If provided, must be a valid private identification scheme code. Either this field or private_identification.identification_scheme must be present if private_identification.identification is specified, but never both. Not supported for outbound payments with SEPA Indirect.
    debtor_party.private_identification.identification_scheme string [35] Scheme used for identification

    SEPA Instant & SCT: Either this field or private_identification.identification_scheme_code must be present if private_identification.identification is specified, but never both. Not supported for SEPA Indirect.
    debtor_party.private_identification.identification_issuer string Issuer of identification

    SEPA Instant & SCT: Maximum length 35 characters. Not supported for SEPA Indirect.
    end_to_end_reference string Unique identification, as assigned by the initiating party, to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

    FPS: Maximum length 31 characters

    SEPA Instant & SCT: In the event that no reference was given, NOTPROVIDED must be used. For inbound payments, can be an empty string when using SEPA Indirect. Maximum length 35 characters.
    fx.contract_reference string [35] Reference to the foreign exchange contract associated with the transaction
    fx.exchange_rate string [12] Factor to convert fx.original_amount from the instructed currency fx.original_currency into the transaction currency currency. Usually agreed to between debtor and beneficiary. Decimal value represented as a string, must be > 0.

    SEPA Instant & SCT: Required if fx.original_currency is not EUR, must be empty otherwise. Not supported for SEPA Indirect.
    fx.original_amount string Amount of money to be moved between the debtor and creditor before deduction of charges, expressed in the currency as instructed by the initiating party. Decimal value. Must be > 0.

    SEPA Instant & SCT: If this field is present, fx.original_currency must be present as well. Not supported for SEPA Indirect.
    fx.original_currency string [3] Currency of fx.orginal_amount as instructed by the initiating party. Currency code as defined in ISO 4217.

    SEPA Instant & SCT: Required if fx.original_amount is present, must be empty otherwise. If value is not EUR, fx.exchange_rate must be provided. Not supported for SEPA Indirect.
    instruction_id string [35] Unique identification, as assigned by the initiating party to unambigiously identify the transaction. This identification is an point-to-point reference and is passed on, unchanged, throughout the entire chain.

    SEPA Instant & SCT: Cannot include leading, trailing or internal spaces
    intermediary_bank.bank_address array Financial institution address
    intermediary_bank.bank_id string [11] Financial institution identification
    intermediary_bank.bank_id_code string [5] The type of identification provided at bank_id attribute. Must be ISO code as listed in the External Code Sets spreadsheet
    intermediary_bank.bank_name string [35] Financial institution name
    intermediary_bank.bank_party_id string [37] Identifier of the financial institution which services the account
    numeric_reference string [4] Numeric reference field, see scheme specific descriptions for usage

    Bacs: Field7: Reference field used for UK tax info and Bacs Returns

    FPS: Standing Order Reference Number, only used when scheme_payment_type is StandingOrder
    payment_acceptance_datetime date-time Timestamp of when the payment instruction meets the set processing conditions. Format: YYYY-MM-DDThh:mm:ss:mmm+hh:mm
    payment_purpose string [35] Purpose of the payment in a proprietary form

    FPS: FPS Procedures do not mandate any values for the use of this field

    SEPA Instant & SCT: Not supported for SEPA Indirect
    payment_purpose_coded string [4] Purpose of the payment in a coded form

    SEPA Instant & SCT: The codes used must be part of the ISO 20022 ExternalPurpose1Code list
    payment_scheme string Clearing infrastructure through which the payment instruction is to be processed. Default for given organisation ID is used if left empty. Has to be a valid scheme identifier.

    Bacs: BACS or empty if default for organisation is BACS

    FPS: FPS or empty if default for organisation is FPS

    SEPA Instant & SCT: SEPAINSTANT for SEPA Instant, SEPASCT for SCT. Can be empty if default for organisation is set to the desired scheme.
    payment_type string The type of payment. Legacy field only present in some inbound payments.

    FPS: Only present in some inbound payments, ignored for outbound. Use is discouraged.
    processing_date date Date on which the payment is to be debited from the debtor account. Formatted according to ISO 8601 format: YYYY-MM-DD.

    Bacs: Field12 +/- one working day

    FPS: Must be within +/- 1 day of today

    SEPA Instant & SCT: Ignored in outbound payments, interbank settlement date for inbound payments.
    receivers_correspondent.bank_address array [140] Receiver's correspondent's address
    receivers_correspondent.bank_id string [11] SWIFT BIC for receiver's correspondent
    receivers_correspondent.bank_id_code string [5] The type of identification provided at bank_id attribute. Must be ISO code as listed in the External Code Sets spreadsheet
    receivers_correspondent.bank_name string [35] Receiver's correspondent's name
    receivers_correspondent.bank_party_id string [37] Reciever's correspondent party identifier
    reference string [18] Payment reference for beneficiary use

    Bacs: Field10

    FPS: Short reference information associated with the payment. Field can be empty on inbound payments. If present, the beneficiary bank must pass on this information to beneficiary.
    regulatory_reporting string [105] Regulatory reporting information
    reimbursement.bank_address array Third party reimbursement institution address
    reimbursement.bank_id string [11] Identification of third party reimbursement institution
    reimbursement.bank_id_code string [5] The type of identification provided at bank_id attribute. Must be ISO code as listed in the External Code Sets spreadsheet
    reimbursement.bank_name string [35] Third party reimbursement institution name
    reimbursement.bank_party_id string [37] Third party reimbursement institution identifier
    relationships.payment_admission.data array Array of Payment Admission resources related to the payment
    relationships.payment_advice.data array Array of Payment Advice resources related to the payment
    relationships.payment_recall.data array Array of Payment Recall resources related to the payment
    relationships.payment_return.data array Array of Payment Return resources related to the payment
    relationships.payment_reversal.data array Array of Payment Reversal resources related to the payment
    relationships.payment_submission.data array Array of Payment Submission resources related to the payment
    remittance_information string [140] Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts receivable system provided by the debtor for the beneficiary.

    FPS: Longer reference information associated with the payment.

    SEPA Instant & SCT: Either this field or the structured remittance information structured_reference or none of the above can be present but not both.
    scheme_payment_sub_type string The scheme specific payment sub type

    FPS: Has to be a valid FPS payment sub type

    SCT: Local Instrument Proprietary, can be any string that has been agreed by beneficiary and debtor. Either this field or scheme_payment_type can be present but not both. Not supported for SEPA Indirect.
    scheme_payment_type string The scheme-specific payment type

    Bacs: Has to be valid payment type for Bacs Direct Credit

    FPS: Either ImmediatePayment, ForwardDatedPayment or StandingOrder

    SCT: Local Instrument code, must be part of the ExternalLocalInstrument1Code. Either this field or scheme_payment_sub_type can be present but not both. Not supported for SEPA Indirect.
    scheme_processing_date date Date on which the payment is processed by the scheme. Only used if different from processing_date.

    Bacs: Field12. Usually day 2 of the Bacs cycle, only populated on incoming payments.
    scheme_transaction_id string Unique identification, as assigned by the first instructing agent, to unambiguously identify the transaction that is passed on, unchanged, throughout the entire interbank chain.

    Bacs: Transaction identifier used internally by Bacs. The scheme advises that ID format is liable to change.

    FPS: Corresponds to the Transaction Reference Number (TRN), maximum length 18 characters

    SEPA Instant & SCT: Cannot include leading, trailing or internal spaces, maximum length 35 characters. Must be unique. Not supported for outbound payments with SEPA Indirect.
    senders_correspondent.bank_address array Sender's correspondent's address
    senders_correspondent.bank_id string [11] SWIFT BIC for sender's correspondent
    senders_correspondent.bank_id_code string [5] The type of identification provided at bank_id attribute. Must be ISO code as listed in the External Code Sets spreadsheet
    senders_correspondent.bank_name string [35] Sender's correspondent's name
    senders_correspondent.bank_party_id string [37] Identifier of the financial institution which services the account
    structured_reference.issuer string [35] Issuer of remittance reference

    SEPA Instant & SCT: Entity that assigns the structured reference. Either the structured remittance information structured_reference or unstructured remittance_information or none of the above can be present but not both.
    structured_reference.reference string [35] Unique reference to unambiguously refer to the payment originated by the creditor, this reference enables reconciliation by the creditor upon receipt of the amount of money.

    SEPA Instant & SCT: Creditor Reference as identified in SCOR. Either this field or remittance_information or none of the above can be present but not both.
    swift.bank_operation_code string [4] SWIFT service level
    swift.header.destination string [12] Destination SWIFT logical terminal address. Complete 12-character SWIFT destination, including BIC (x8), logical terminal code (x1) and branch code (x).
    swift.header.message_type string [5] The message type of the SWIFT payment, has to match [A-Z]{2}[0-9]{3}. Currently MT103 is the only supported value
    swift.header.priority string [8] SWIFT priority. Either Normal or Priority.
    swift.header.recipient string [8] The destination SWIFT BIC for SWIFT MT messages being sent by Form3 client to SWIFT. Formatted as BIC8 or BIC11.
    swift.header.source string [8] The source SWIFT BIC for SWIFT MT messages being received by Form3 client from SWIFT. Formatted as BIC8 or BIC11.
    swift.header.user_reference string [16] Message User Reference (MUR) value, which can be up to 16 characters, and will be returned in the ACK
    swift.instruction_code string [35] A SWIFT instruction code
    swift.sender_receiver_information string [210] This field specifies additional information for the Receiver or other party specified.
    swift.time_indication string This repetitive field specifies one or several time indication(s) related to the processing of the payment instruction.
    ultimate_beneficiary.address array Ultimate beneficiary address
    ultimate_beneficiary.birth_city string [35] Ultimate beneficiary birth city

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed.
    ultimate_beneficiary.birth_country string [2] Ultimate beneficiary birth country. ISO 3166 format country code

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed.
    ultimate_beneficiary.birth_date date Ultimate beneficiary birth date. Formatted ISO 8601 format YYYY-MM-DD

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed.
    ultimate_beneficiary.birth_province string [35] Ultimate beneficiary birth province

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed. Not supported for SEPA Indirect.
    ultimate_beneficiary.country string [2] Country of ultimate beneficiary address. ISO 3166 format country code
    ultimate_beneficiary.name string [70] Ultimate beneficiary name
    ultimate_beneficiary.organisation_identification string [35] Organisation identification of the ultimate beneficiary, used in the case the ultimate beneficiary is an organisation and not a private person

    SEPA Instant & SCT: The kind of identification expected depends on the organisation_identification_code or organisation_identification_scheme, depending on which is provided. If organisation identification is present, neither private identification nor date and place of birth are allowed.
    ultimate_beneficiary.organisation_identification_code string [4] Code to specify the type of organisation_identification

    SEPA Instant & SCT: If provided, must be a valid organisation identification code. Either this field or organisation_identification_scheme must be present if organisation_identification is specified, but never both.
    ultimate_beneficiary.organisation_identification_scheme string [35] Code to specify a custom type of organisation_identification

    SEPA Instant & SCT: Use this field if the identification in organisation_identification is a custom internal code type. Either this field or organisation_identification_scheme must be present if organisation_identification is specified, but never both. Not supported for SEPA Indirect.
    ultimate_beneficiary.organisation_identification_issuer string [35] Issuer of the organisation identification

    SEPA Instant & SCT: Not supported for SEPA Indirect
    ultimate_beneficiary.private_identification.identification string [35] Private Identification of a ultimate beneficiary

    SEPA Instant & SCT: If private identification is present, neither organisation identification nor date and place of birth are allowed.
    ultimate_beneficiary.private_identification.identification_scheme_code string The code specifying the type of identification

    SEPA Instant & SCT: If provided, must be a valid private identification scheme code. Either this field or private_identification.identification_scheme must be present if private_identification.identification is specified, but never both.
    ultimate_beneficiary.private_identification.identification_scheme string [35] Scheme used for identification

    SEPA Instant & SCT: Either this field or private_identification.identification_scheme_code must be present if private_identification.identification is specified, but never both. Not supported for SEPA Indirect.
    ultimate_beneficiary.private_identification.identification_issuer string Issuer of identification

    SEPA Instant & SCT: Maximum length 35 characters. Not supported for SEPA Indirect.
    ultimate_debtor.address array Ultimate debtor address

    SEPA Instant & SCT: Max 2 lines of 70 text. Not supported for SEPA Indirect.
    ultimate_debtor.birth_city string [35] Ultimate debtor birth city

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed.
    ultimate_debtor.birth_country string [2] Ultimate debtor birth country. ISO 3166 format country code

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed.
    ultimate_debtor.birth_date date Ultimate debtor birth date. Formatted ISO 8601 format YYYY-MM-DD

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed.
    ultimate_debtor.birth_province string [35] Ultimate debtor birth province

    SEPA Instant & SCT: If place and date of birth is present, neither organisation identification nor private identification are allowed. Not supported for SEPA Indirect.
    ultimate_debtor.country string [2] Country of ultimate debtor address. ISO 3166 format country code
    ultimate_debtor.name string [70] Ultimate debtor name
    ultimate_debtor.organisation_identification string [35] Organisation identification of the ultimate debtor, used in the case the ultimate debtor is an organisation and not a private person

    SEPA Instant & SCT: The kind of identification expected depends on the organisation_identification_code or organisation_identification_scheme, depending on which is provided. If organisation identification is present, neither private identification nor date and place of birth are allowed.
    ultimate_debtor.organisation_identification_code string [4] Code to specify the type of organisation_identification

    SEPA Instant & SCT: provided, must be a valid organisation identification code. Either this field or organisation_identification_scheme must be present if organisation_identification is specified, but never both.
    ultimate_debtor.organisation_identification_scheme string [35] Code to specify a custom type of organisation_identification

    SEPA Instant & SCT: Use this field if the identification in organisation_identification is a custom internal code type. Either this field or organisation_identification_scheme must be present if organisation_identification is specified, but never both. Not supported for SEPA Indirect.
    ultimate_debtor.organisation_identification_issuer string [35] Issuer of the organisation identification

    SEPA Instant & SCT: Not supported for SEPA Indirect
    ultimate_debtor.private_identification.identification string [35] Private Identification of a ultimate debtor

    SEPA Instant & SCT: If private identification is present, neither organisation identification nor date and place of birth are allowed.
    ultimate_debtor.private_identification.identification_scheme_code string The code specifying the type of identification

    SEPA Instant & SCT: If provided, must be a valid private identification scheme code. Either this field or private_identification.identification_scheme must be present if private_identification.identification is specified, but never both.
    ultimate_debtor.private_identification.identification_scheme string [35] Scheme used for identification

    SEPA Instant & SCT: Either this field or private_identification.identification_scheme_code must be present if private_identification.identification is specified, but never both. Not supported for SEPA Indirect.
    ultimate_debtor.private_identification.identification_issuer string Issuer of identification

    SEPA Instant & SCT: Maximum length 35 characters. Not supported for SEPA Indirect.
    unique_scheme_id string [42] The scheme-specific unique transaction ID. Populated by the scheme.

    Bacs: Internal Bacs transaction reference, only present for incoming payments or after payment has been submitted to the scheme.

    FPS: Corresponds to the FPID, only present for incoming payments or after payment has been submitted to the scheme.

    Create

    Example request (UK Faster Payment)

    POST /v1/transaction/payments HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "id": "20b1f7a2-83c7-45d3-a6e3-0a75b14b9f7f",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "231.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "71268996",
            "account_number_code": "BBAN",
            "account_type": 1,
            "account_with": {
              "bank_id": "400302",
              "bank_id_code": "GBDSC" 
            },
            "country": "GB" 
          },
          "currency": "GBP",
          "debtor_party": {
            "account_name": "Mr Sending Test",
            "account_number": "87654321",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "333333",
              "bank_id_code": "GBDSC" 
            },
            "country": "GB" 
          },
          "numeric_reference": "0001",
          "processing_date": "2019-03-29",
          "reference": "D/1234567890123456",
          "scheme_payment_sub_type": "TelephoneBanking",
          "scheme_payment_type": "ImmediatePayment",
          "payment_scheme": "FPS"
        }
      }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/transaction/payments
    
    {
      "data": {
        "id": "20b1f7a2-83c7-45d3-a6e3-0a75b14b9f7f",
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "231.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "71268996",
            "account_number_code": "BBAN",
            "account_type": 1,
            "account_with": {
              "bank_id": "400302",
              "bank_id_code": "GBDSC" 
            },
            "country": "GB" 
          },
          "currency": "GBP",
          "debtor_party": {
            "account_name": "Mr Sending Test",
            "account_number": "87654321",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "333333",
              "bank_id_code": "GBDSC" 
            },
            "country": "GB" 
          },
          "numeric_reference": "0001",
          "processing_date": "2019-03-29",
          "reference": "D/1234567890123456",
          "scheme_payment_sub_type": "TelephoneBanking",
          "scheme_payment_type": "ImmediatePayment",
          "payment_scheme": "FPS"
        }
      }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'id': '20b1f7a2-83c7-45d3-a6e3-0a75b14b9f7f',
        'organisation_id': '743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb',
        'attributes': {
          'amount': '231.00',
          'beneficiary_party': {
            'account_name': 'Mrs Receiving Test',
            'account_number': '71268996',
            'account_number_code': 'BBAN',
            'account_type': 1,
            'account_with': {
              'bank_id': '400302',
              'bank_id_code': 'GBDSC' 
            },
            'country': 'GB' 
          },
          'currency': 'GBP',
          'debtor_party': {
            'account_name': 'Mr Sending Test',
            'account_number': '87654321',
            'account_number_code': 'BBAN',
            'account_with': {
              'bank_id': '333333',
              'bank_id_code': 'GBDSC' 
            },
            'country': 'GB' 
          },
          'numeric_reference': '0001',
          'processing_date': '2019-03-29',
          'reference': 'D/1234567890123456',
          'scheme_payment_sub_type': 'TelephoneBanking',
          'scheme_payment_type': 'ImmediatePayment',
          'payment_scheme': 'FPS'
        }
      }
    }
    """
    req = requests.post('https://api.form3.tech/v1/transaction/payments', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/