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
  • Change log
  • Introduction and API Conventions

    Welcome to the Form3 API documentation. Our API is based on the principle of REST. Requests and responses are built around the json:api specification. 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 string 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-exisiting endpoint.
    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.
    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:

    Webhook

    If the webhook does not acknowledge the receipt of a notification with a HTTP 200 code, Form3 will continue to send the notification with increasing wait times between attempts.

    After 12 hours of unsuccessful delivery attempts, the notification will be deleted. No data-carrying resources such as payments or submissions will be deleted.

    SQS Queue

    SQS queues are a managed service that has built-in timeout handling. Once posted to the queue, no notifications will be lost until they are read by you.

    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
    Organisations GET /v1/organisation/units/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

    In addition, service availability 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 authentication scheme uses OAuth 2 Client Credentials Grant, the recommended mechanism to use for client-owned resources and machine-to-machine communication. 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 outgoing direct debit returns
    direct_debit_return_submissions Submission of outgoing 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

    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.

    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

    Test environment
    X509 Attribute Value
    Subject
    C=GB, L=London, O=Back Office Technology Limited, OU=Back Office Technology Web Services, CN=api.test.form3.tech
    Subject (nginx format)
    CN=api.test.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 a 200 HTTP response to indicate successful receipt of the notification.

    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.

    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": "payment_admissions",
          "deactivated": false
        }
      },
      "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": "payment_admissions",
          "deactivated": false
        }
      },
      "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": "payment_admissions",
          "deactivated": false
        }
      },
      "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
    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.

    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
    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

    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": "payment_admissions",
          "deactivated": false
        }
      },
      "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": "payment_admissions",
          "deactivated": false
        }
      },
      "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": "payment_admissions",
          "deactivated": false
        }
      },
      "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.

    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 change an outdated callback method or URL, also 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",
        "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",
        "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',
        '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": 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"
      }
    }
    

    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
    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
    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.

    Response Body

    See Fetch call for a list of response body attributes.

    Delete

    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

    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 outgoing direct debit returns
    direct_debit_return_submissions Submission of outgoing 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

    Event notification format

    Example event payment

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "id": "7b404bd4-de04-4c5c-a2c9-722c1923b92e",
      "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
      "event_type": "created",
      "record_type": "payments",
      "data": {
        "data": {
          "type": "payments",
          "id": "f13d42cc-388e-48a6-87e8-6cf523f7c2be",
          "version": 0,
          "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
          "attributes": {
            "amount": "13",
            "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"
              },
              "address": [
                "1 Clarence Mew, Horsforth, Leeds Ls18 4EP"
              ],
              "country": "GB"
            },
            "currency": "GBP",
            "debtor_party": {
              "account_name": "Mr Sending Test",
              "account_number": "62588471",
              "account_number_code": "BBAN",
              "account_with": {
                "bank_id": "040013",
                "bank_id_code": "GBDSC"
              },
              "address": [
                "2 Alexandra Crescent, Ilkley LS29 9ER"
              ],
              "country": "GB"
            },
            "end_to_end_reference": "00151519632ZCBBBJQ",
            "numeric_reference": "0001",
            "scheme_transaction_id": "109786097428993120",
            "payment_purpose": "001",
            "processing_date": "2018-02-21",
            "reference": "D/1234567890123456",
            "regulatory_reporting": "May be required for some foreign originated payments",
            "remittance_information": "Remittance information - Additional remittance information over and above reference information",
            "scheme_payment_sub_type": "TelephoneBanking",
            "scheme_payment_type": "StandingOrder"
          }
        }
      }
    }
    
    {
      "id": "7b404bd4-de04-4c5c-a2c9-722c1923b92e",
      "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
      "event_type": "created",
      "record_type": "payments",
      "data": {
        "data": {
          "type": "payments",
          "id": "f13d42cc-388e-48a6-87e8-6cf523f7c2be",
          "version": 0,
          "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
          "attributes": {
            "amount": "13",
            "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"
              },
              "address": [
                "1 Clarence Mew, Horsforth, Leeds Ls18 4EP"
              ],
              "country": "GB"
            },
            "currency": "GBP",
            "debtor_party": {
              "account_name": "Mr Sending Test",
              "account_number": "62588471",
              "account_number_code": "BBAN",
              "account_with": {
                "bank_id": "040013",
                "bank_id_code": "GBDSC"
              },
              "address": [
                "2 Alexandra Crescent, Ilkley LS29 9ER"
              ],
              "country": "GB"
            },
            "end_to_end_reference": "00151519632ZCBBBJQ",
            "numeric_reference": "0001",
            "scheme_transaction_id": "109786097428993120",
            "payment_purpose": "001",
            "processing_date": "2018-02-21",
            "reference": "D/1234567890123456",
            "regulatory_reporting": "May be required for some foreign originated payments",
            "remittance_information": "Remittance information - Additional remittance information over and above reference information",
            "scheme_payment_sub_type": "TelephoneBanking",
            "scheme_payment_type": "StandingOrder"
          }
        }
      }
    }
    
    {
      "id": "7b404bd4-de04-4c5c-a2c9-722c1923b92e",
      "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
      "event_type": "created",
      "record_type": "payments",
      "data": {
        "data": {
          "type": "payments",
          "id": "f13d42cc-388e-48a6-87e8-6cf523f7c2be",
          "version": 0,
          "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
          "attributes": {
            "amount": "13",
            "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"
              },
              "address": [
                "1 Clarence Mew, Horsforth, Leeds Ls18 4EP"
              ],
              "country": "GB"
            },
            "currency": "GBP",
            "debtor_party": {
              "account_name": "Mr Sending Test",
              "account_number": "62588471",
              "account_number_code": "BBAN",
              "account_with": {
                "bank_id": "040013",
                "bank_id_code": "GBDSC"
              },
              "address": [
                "2 Alexandra Crescent, Ilkley LS29 9ER"
              ],
              "country": "GB"
            },
            "end_to_end_reference": "00151519632ZCBBBJQ",
            "numeric_reference": "0001",
            "scheme_transaction_id": "109786097428993120",
            "payment_purpose": "001",
            "processing_date": "2018-02-21",
            "reference": "D/1234567890123456",
            "regulatory_reporting": "May be required for some foreign originated payments",
            "remittance_information": "Remittance information - Additional remittance information over and above reference information",
            "scheme_payment_sub_type": "TelephoneBanking",
            "scheme_payment_type": "StandingOrder"
          }
        }
      }
    }
    

    Example event payment submission

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "id": "9a6bdac3-d609-40de-8b7b-c7ffe3f3dbd1",
      "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
      "event_type": "updated",
      "record_type": "payment_submissions",
      "data": {
        "data": {
          "type": "payment_submissions",
          "id": "6e6d72f4-d5ba-40ce-9257-aeacc033459c",
          "version": 4,
          "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
          "attributes": {
            "status": "released_to_gateway",
            "submission_datetime": "2018-02-21T10:30:46.743Z",
            "settlement_cycle": 0
          },
          "relationships": {
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "f13d42cc-388e-48a6-87e8-6cf523f7c2be"
                }
              ]
            }
          }
        }
      }
    }
    
    {
      "id": "9a6bdac3-d609-40de-8b7b-c7ffe3f3dbd1",
      "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
      "event_type": "updated",
      "record_type": "payment_submissions",
      "data": {
        "data": {
          "type": "payment_submissions",
          "id": "6e6d72f4-d5ba-40ce-9257-aeacc033459c",
          "version": 4,
          "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
          "attributes": {
            "status": "released_to_gateway",
            "submission_datetime": "2018-02-21T10:30:46.743Z",
            "settlement_cycle": 0
          },
          "relationships": {
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "f13d42cc-388e-48a6-87e8-6cf523f7c2be"
                }
              ]
            }
          }
        }
      }
    }
    
    {
      "id": "9a6bdac3-d609-40de-8b7b-c7ffe3f3dbd1",
      "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
      "event_type": "updated",
      "record_type": "payment_submissions",
      "data": {
        "data": {
          "type": "payment_submissions",
          "id": "6e6d72f4-d5ba-40ce-9257-aeacc033459c",
          "version": 4,
          "organisation_id": "2fc8eac2-e6f4-671e-e9e8-03b6e81d4f30",
          "attributes": {
            "status": "released_to_gateway",
            "submission_datetime": "2018-02-21T10:30:46.743Z",
            "settlement_cycle": 0
          },
          "relationships": {
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "f13d42cc-388e-48a6-87e8-6cf523f7c2be"
                }
              ]
            }
          }
        }
      }
    }
    

    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_submissions
    data object always The full resource itself (as you would see from a GET request)

    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
    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",
              "formats": [
                  "pdf"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "pdf": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/pdf"
            }
          }
       }   
    }
    
    
    {
       "data": { 
          "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
          "type": "reports",
          "version": 1,    
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "created_on": "2019-01-16T16:04:31.486Z",
          "modified_on": "2019-01-16T16:05:45.984Z",    
          "attributes": {
              "report_type": "2013",
              "report_type_description": "AUDDIS Input",
              "generation_time": "2019-01-16T16:04:31.194Z",
              "processing_date": "2019-01-16",
              "report_source": "BACS",
              "formats": [
                  "pdf"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "pdf": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/pdf"
            }
          }
       }   
    }
    
    
    {
       "data": { 
          "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
          "type": "reports",
          "version": 1,    
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "created_on": "2019-01-16T16:04:31.486Z",
          "modified_on": "2019-01-16T16:05:45.984Z",    
          "attributes": {
              "report_type": "2013",
              "report_type_description": "AUDDIS Input",
              "generation_time": "2019-01-16T16:04:31.194Z",
              "processing_date": "2019-01-16",
              "report_source": "BACS",
              "formats": [
                  "pdf"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "pdf": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/pdf"
            }
          }
       }   
    }
    
    
    Attribute Description
    report_type string read-only Report type
    report_type_description string read-only Report type description
    generation_time datetime read-only Datetime on which the report was generated
    processing_date date read-only Date on which the report was processed
    report_source string read-only Scheme source responsible for generating the report
    formats array of strings read-only Report formats available. Each value can be used as a key to get a link to download the report (see links)
    relationships.report_admission resource read-only Report Admission resource that relates to
    links.{format}.href string read-only Download link for the report in the given format. See format attribute for available values for {format}.
    links.{format}.meta.content-type string read-only 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",
              "formats": [
                  "pdf"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "pdf": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/pdf"
            }
          }
       }   
    }
    
    
    {
       "data": { 
          "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
          "type": "reports",
          "version": 1,    
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "created_on": "2019-01-16T16:04:31.486Z",
          "modified_on": "2019-01-16T16:05:45.984Z",    
          "attributes": {
              "report_type": "2013",
              "report_type_description": "AUDDIS Input",
              "generation_time": "2019-01-16T16:04:31.194Z",
              "processing_date": "2019-01-16",
              "report_source": "BACS",
              "formats": [
                  "pdf"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "pdf": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/pdf"
            }
          }
       }   
    }
    
    
    {
       "data": { 
          "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
          "type": "reports",
          "version": 1,    
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "created_on": "2019-01-16T16:04:31.486Z",
          "modified_on": "2019-01-16T16:05:45.984Z",    
          "attributes": {
              "report_type": "2013",
              "report_type_description": "AUDDIS Input",
              "generation_time": "2019-01-16T16:04:31.194Z",
              "processing_date": "2019-01-16",
              "report_source": "BACS",
              "formats": [
                  "pdf"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "pdf": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/pdf"
            }
          }
       }   
    }
    
    

    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.

    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

    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",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    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.

    If no account number is provided, Form3 generates a valid account number (see below). If supported by the country, an IBAN is also generated.

    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
    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
    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, 8 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",
        "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",
        "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',
        '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",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    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",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    

    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",
        "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",
        "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",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "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"
        }
      },
      "links": {
        "self": "/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc"
      }
    }
    
    

    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
    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.

    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",
          "attributes": {
            "account_number": "41426819",
            "bank_id": "400300",
            "bank_id_code": "GBDSC"
          }
        },
        {
          "type": "accounts",
          "id": "ea6239c1-99e9-42b3-bca1-92f5c068da6b",
          "attributes": {
            "account_number": "51426819",
            "bank_id": "200200",
            "bank_id_code": "GBDSC"
          }
        }
      ],
      "links": {
        "self": "/accounts?page[number]=3&page[size]=2",
        "first": "/accounts?page[number]=1&page[size]=2",
        "prev": "/accounts?page[number]=2&page[size]=2",
        "next": "/accounts?page[number]=4&page[size]=2",
        "last": "/accounts?page[number]=13&page[size]=2"
      }
    }
    
    {
      "data": [
        {
          "type": "accounts",
          "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
          "attributes": {
            "account_number": "41426819",
            "bank_id": "400300",
            "bank_id_code": "GBDSC"
          }
        },
        {
          "type": "accounts",
          "id": "ea6239c1-99e9-42b3-bca1-92f5c068da6b",
          "attributes": {
            "account_number": "51426819",
            "bank_id": "200200",
            "bank_id_code": "GBDSC"
          }
        }
      ],
      "links": {
        "self": "/accounts?page[number]=3&page[size]=2",
        "first": "/accounts?page[number]=1&page[size]=2",
        "prev": "/accounts?page[number]=2&page[size]=2",
        "next": "/accounts?page[number]=4&page[size]=2",
        "last": "/accounts?page[number]=13&page[size]=2"
      }
    }
    
    {
      "data": [
        {
          "type": "accounts",
          "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
          "attributes": {
            "account_number": "41426819",
            "bank_id": "400300",
            "bank_id_code": "GBDSC"
          }
        },
        {
          "type": "accounts",
          "id": "ea6239c1-99e9-42b3-bca1-92f5c068da6b",
          "attributes": {
            "account_number": "51426819",
            "bank_id": "200200",
            "bank_id_code": "GBDSC"
          }
        }
      ],
      "links": {
        "self": "/accounts?page[number]=3&page[size]=2",
        "first": "/accounts?page[number]=1&page[size]=2",
        "prev": "/accounts?page[number]=2&page[size]=2",
        "next": "/accounts?page[number]=4&page[size]=2",
        "last": "/accounts?page[number]=13&page[size]=2"
      }
    }
    

    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 Description
    204 No Content Account has been successfully deleted

    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"
    France (FR) Account number, IBAN Relevé d'identité bancaire
    Belgium (BE) Account number, IBAN 2 check digits as described here
    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
    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

    Update

    Example request

    PATCH /v1/organisation/units HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "attributes": {
                "name": "New Name"
            }
        }
    }
    
    curl -X PATCH -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/organisation/units
    
    {
        "data": {
            "attributes": {
                "name": "New Name"
            }
        }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
        'data': {
            '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": 0,
            "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": 0,
            "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": 0,
            "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}

    Attribute Description
    organisation_id string, unique identifier (UUID) Organisation ID of the organisation to update
    name string 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

    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 limit
    position string Current position

    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 resources are divided into users and roles. They control access to the Form3 platform.

    All resources on the platform belong to an organisation. To access these resources, a user requires an Access Control Entry (ACE). The ACE defines which organisation, resource type, and action (read, create, etc.) access is granted for.

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

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

    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" : 0,
            "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" : 0,
            "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" : 0,
            "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
    Attribute Description
    username string User name
    email string Email address
    role_ids array of UUID 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

    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

    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

    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

    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.

    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": []
          }
        }
      }
    }
    
    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: Interbank settlement amount, must have 2 decimal places. Maximum value 15000.00.
    beneficiary_party.account_name string Name of beneficiary as given with account

    Bacs: Field11, maximum length 40 characters

    FPS: Maxiumum length 35 characters
    beneficiary_party.account_number string Beneficiary account number

    Bacs: Field2, maximum lebgth 8 characters

    FPS: Maximum length 8 characters

    SEPA Instant: Must be in IBAN format, 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: Must be IBAN
    beneficiary_party.account_type integer The type of the account given with beneficiary_party.account_number. Single digit number

    Bacs: Field3 (Defaults to 0)

    FPS: Only required if requested by the beneficiary party. Defaults to 0.
    beneficiary_party.account_with.bank_address array Financial institution address
    beneficiary_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: 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: 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: Max 2 lines of 70 text
    beneficiary_party.birth_city string [35] Beneficiary birth city

    SEPA Instant: If a Creditor Identification is used then either beneficiary_party.organisation_identification or date and place of birth can be present but not both
    beneficiary_party.birth_country string [2] Beneficiary birth country, ISO 3166 format country code

    SEPA Instant: If a Creditor Identification is used then either beneficiary_party.organisation_identification or date and place of birth can be present but not both
    beneficiary_party.birth_date date Beneficiary birth date. Formatted according to ISO 8601 format: YYYY-MM-DD

    SEPA Instant: If a Creditor Identification is used then either beneficiary_party.organisation_identification or date and place of birth can be present but not both
    beneficiary_party.birth_province string [35] Beneficiary birth province

    SEPA Instant: If a Creditor Identification is used then either beneficiary_party.organisation_identification or date and place of birth can be present but not both
    beneficiary_party.country string [2] Country of the beneficiary address, ISO 3166 format country code
    beneficiary_party.name string [70] Beneficiary 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: The identification can either be a BIC, BEI or Other Identification
    beneficiary_party.organisation_identification_code string [4] The code that specifies the type of organisation_identification

    SEPA Instant: If beneficiary_party.organisation_identification is specified, must be either BIC, BEI, or Other
    beneficiary_party.organisation_identification_issuer string [35] Issuer of the organisation identification

    SEPA Instant: May only be present if beneficary_party.organisation_identification_code is Other
    beneficiary_party.private_identification.identification string Private Identification of a beneficiary

    SEPA Instant: Maximum length 35 characters
    beneficiary_party.private_identification.identification_scheme_code string The code specifying the type of identification

    SEPA Instant: If identification is specified, must be either ARNU, CCPT, CUST, DRLC, EMPL, NIDN, SOSE, TXID or Other
    beneficiary_party.private_identification.identification_scheme string Scheme used for identification

    SEPA Instant: Maximum length 35 character
    beneficiary_party.private_identification.identification_issuer string Issuer of identification

    SEPA Instant: Maximum length 35 characters
    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.
    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: The codes used must be part of the ISO 20022 ExternalCategoryPurpose1Code list
    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: Only SLEV is allowed. If not set, will be defaulted to SLEV.
    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: Must be EUR
    debtor_party.account_name string Name of debtor as given with account

    Bacs: Field9, maximum length 40 characters

    FPS: Maximum length 35 characters
    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: Always is in IBAN format, 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: 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: 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: 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: Max 2 lines of 70 text.
    debtor_party.birth_city string [35] Debtor birth city

    SEPA Instant: If a Debtor Identification is used then either debtor_party.organisation_identification or date and place of birth can be present but not both
    debtor_party.birth_country string [2] Debtor birth country. ISO 3166 format country code

    SEPA Instant: If a Debtor Identification is used then either debtor_party.organisation_identification or date and place of birth can be present but not both
    debtor_party.birth_date date Debtor birth date. Formatted according to ISO 8601 format: YYYY-MM-DD

    SEPA Instant: If a Debtor Identification is used then either debtor_party.organisation_identification or date and place of birth can be present but not both
    debtor_party.birth_province string [35] Debtor birth province

    SEPA Instant: If a Debtor Identification is used then either debtor_party.organisation_identification or date and place of birth can be present but not both
    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
    debtor_party.organisation_identification string [35] Organisation identification of a debtor, in the case the debtor is an organisation and not a private person

    SEPA Instant: The identification can either be a BIC, BEI or Other Identification
    debtor_party.organisation_identification_code string [4] The code that specifies the type of organisation_identification

    SEPA Instant: If debtor_party.organisation_identification is specified, must be either BIC, BEI, or Other
    debtor_party.organisation_identification_issuer string [35] Issuer of the organisation_identification

    SEPA Instant: May only be present if debtor_party.organisation_identification_code is Other
    debtor_party.private_identification.identification string Private Identification of a debtor

    SEPA Instant: Maximum length 35 characters
    debtor_party.private_identification.identification_scheme_code string The code specifying the type of identification

    SEPA Instant: If identification is specified, must be either ARNU, CCPT, CUST, DRLC, EMPL, NIDN, SOSE, TXID or Other
    debtor_party.private_identification.identification_scheme string Scheme used for identification

    SEPA Instant: Maximum length 35 character
    debtor_party.private_identification.identification_issuer string Issuer of identification

    SEPA Instant: Maximum length 35 characters
    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: In the event that no reference was given, NOTPROVIDED must be used, maximum length 35 characters.
    fx.contract_reference string [35] Reference to the foreign exchange contract associated with the transaction
    fx.exchange_rate string Factor used to convert an amount from the instructed currency into the transaction currency: i.e. to convert the fx.original_amount, expressed in the fx.original_currency, to amount specified in currency. Decimal value, represented as a string, maximum length 12. Must be > 0.

    SEPA Instant: If the instructed currency is not EUR: fx.exchange_rate, fx.original_amount and fx.original_currency must be provided
    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: If the instructed currency is not EUR: fx.exchange_rate, fx.original_amount and fx.original_currency must be provided.
    fx.original_currency string [3] Currency of orginal_amount. Currency code as defined in ISO 4217.

    SEPA Instant: If the instructed currency is not EUR: fx.exchange_rate, fx.original_amount and fx.original_currency must be provided.
    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: 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
    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
    payment_purpose_coded string [4] Purpose of the payment in a coded form

    SEPA Instant: 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: SEPAINSTANT or empty if default for organisation is SEPAINSTANT
    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: Ignored
    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. 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: Either the structured remittance information structured_reference or unstructured remittance_information may be present but not both.
    scheme_payment_sub_type string The scheme specific payment sub type

    FPS: Either TelephoneBanking, InternetBanking, BranchInstruction, Letter, Email or MobilePaymentsService
    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
    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: Cannot include leading, trailing or internal spaces, maximum length 35 characters
    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: Either the structured remittance information structured_reference or unstructured remittance_information may be present but not both. Mandatory if SCOR is used in the remittance data proprietary code.
    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: Either the structured remittance information structured_reference or unstructured remittance_information may 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

    SEPA Instant: Max 2 lines of 70 text.
    ultimate_beneficiary.birth_city string [35] Ultimate beneficiary birth city

    SEPA Instant: If a Ultimate Beneficiary Identification is used then either organisation_identification can be present or date and place of birth can be present but not both
    ultimate_beneficiary.birth_country string [2] Ultimate beneficiary birth country. ISO 3166 format country code

    SEPA Instant: If a Ultimate Beneficiary Identification is used then either organisation_identification can be present or date and place of birth can be present but not both
    ultimate_beneficiary.birth_date date Ultimate beneficiary birth date. Formatted ISO 8601 format YYYY-MM-DD

    SEPA Instant: If a Ultimate Beneficiary Identification is used then either organisation_identification can be present or date and place of birth can be present but not both
    ultimate_beneficiary.birth_province string [35] Ultimate beneficiary birth province

    SEPA Instant: If a Ultimate Beneficiary Identification is used then either organisation_identification can be present or date and place of birth can be present but not both
    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 an ultimate beneficiary, in the case that the ultimate beneficiary is an organisation and not a private person.

    SEPA Instant: The Identification can either be a BIC, BEI or Other Identification
    ultimate_beneficiary.organisation_identification_code string [4] The code that specifies the type of organisation_identification

    SEPA Instant: If organisation_identification is specified, must be either BIC, BEI, or Other
    ultimate_beneficiary.organisation_identification_issuer string [35] Issuer of the organisation_identification
    ultimate_beneficiary.private_identification.identification string Private Identification of an ultimate beneficiary

    SEPA Instant: Maximum length 35 characters
    ultimate_beneficiary.private_identification.identification_scheme_code string The code specifying the type of identification

    SEPA Instant: If identification is specified, must be either ARNU, CCPT, CUST, DRLC, EMPL, NIDN, SOSE, TXID or Other
    ultimate_beneficiary.private_identification.identification_scheme string Scheme used for identification

    SEPA Instant: Maximum length 35 character
    ultimate_beneficiary.private_identification.identification_issuer string Issuer of identification

    SEPA Instant: Maximum length 35 characters
    ultimate_debtor.address array Ultimate debtor address

    SEPA Instant: Max 2 lines of 70 text.
    ultimate_debtor.birth_city string [35] Ultimate debtor birth city

    SEPA Instant: If a Ultimate Deptor Identification is used then either organisation_identification can be present or date and place of birth can be present but not both
    ultimate_debtor.birth_country string [2] Ultimate debtor birth country. ISO 3166 format country code

    SEPA Instant: If a Ultimate Debtor Identification is used then either organisation_identification can be present or date and place of birth can be present but not both
    ultimate_debtor.birth_date date Ultimate debtor birth date. Formatted ISO 8601 format YYYY-MM-DD

    SEPA Instant: If a Ultimate Debtor Identification is used then either organisation_identification can be present or date and place of birth can be present but not both
    ultimate_debtor.birth_province string [35] Ultimate debtor birth province

    SEPA Instant: If a Ultimate Debtor Identification is used then either organisation_identification can be present or date and place of birth can be present but not both
    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 an ultimate debtor, in the case that the ultimate debtor is an organisation and not a private person.

    SEPA Instant: The Identification can either be a BIC, BEI or Other Identification
    ultimate_debtor.organisation_identification_code string [4] The code that specifies the type of organisation_identification

    SEPA Instant: If organisation_identification is specified, must be either BIC, BEI, or Other
    ultimate_debtor.organisation_identification_issuer string [35] Issuer of the organisation_identification
    ultimate_debtor.private_identification.identification string Private Identification of an ultimate debtor

    SEPA Instant: Maximum length 35 characters
    ultimate_debtor.private_identification.identification_scheme_code string The code specifying the type of identification

    SEPA Instant: If identification is specified, must be either ARNU, CCPT, CUST, DRLC, EMPL, NIDN, SOSE, TXID or Other
    ultimate_debtor.private_identification.identification_scheme string Scheme used for identification

    SEPA Instant: Maximum length 35 character
    ultimate_debtor.private_identification.identification_issuer string Issuer of identification

    SEPA Instant: Maximum length 35 characters
    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.

    The payment resource is generic and is 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.

    To simplify implementation, we have also included documentation and examples showing which fields need to be populated for the different schemes.

    See:

    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/1.1 201 Created
    Content-Type: application/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": []
          }
        }
      }
    }
    

    Example request (UK Bacs)

    POST /v1/transaction/payments HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "payments",
        "id": "1c5dafcd-f614-435c-987d-6d93103f0189",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "700.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "12345678",
            "account_number_code": "BBAN",
            "account_type": 1,
            "account_with": {
              "bank_id": "123456",
              "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": "ref",
          "scheme_payment_type": "Credit",
          "payment_scheme": "Bacs"
        }
      }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \  
      https://api.form3.tech//v1/transaction/payments
    
    {
      "data": {
        "type": "payments",
        "id": "1c5dafcd-f614-435c-987d-6d93103f0189",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "700.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "12345678",
            "account_number_code": "BBAN",
            "account_type": 1,
            "account_with": {
              "bank_id": "123456",
              "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": "ref",
          "scheme_payment_type": "Credit",
          "payment_scheme": "Bacs"
        }
      }
    }
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'type': 'payments',
        'id': '1c5dafcd-f614-435c-987d-6d93103f0189',
        'version': 0,
        'organisation_id': '743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb',
        'attributes': {
          'amount': '700.00',
          'beneficiary_party': {
            'account_name': 'Mrs Receiving Test',
            'account_number': '12345678',
            'account_number_code': 'BBAN',
            'account_type': 1,
            'account_with': {
              'bank_id': '123456',
              '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': 'ref',
          'scheme_payment_type': 'Credit',
          'payment_scheme': 'Bacs'
        }
      }
    }
    """
    req = requests.post('https://api.form3.tech/v1/transaction/payments', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "payments",
        "id": "1c5dafcd-f614-435c-987d-6d93103f0189",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "700.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "12345678",
            "account_number_code": "BBAN",
            "account_type": 1,
            "account_with": {
              "bank_id": "123456",
              "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": "40322152862679881",
          "payment_scheme": "Bacs",
          "processing_date": "2019-03-29",
          "reference": "ref",
          "scheme_payment_type": "Credit"
        },
        "relationships": {
          "payment_submission": {
            "data": []
          },
          "payment_return": {
            "data": []
          },
          "payment_admission": {
            "data": []
          },
          "payment_reversal": {
            "data": []
          },
          "payment_recall": {
            "data": []
          },
          "payment_advice": {
            "data": []
          }
        }
      }
    }
    
    {
      "data": {
        "type": "payments",
        "id": "1c5dafcd-f614-435c-987d-6d93103f0189",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "700.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "12345678",
            "account_number_code": "BBAN",
            "account_type": 1,
            "account_with": {
              "bank_id": "123456",
              "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": "40322152862679881",
          "payment_scheme": "Bacs",
          "processing_date": "2019-03-29",
          "reference": "ref",
          "scheme_payment_type": "Credit"
        },
        "relationships": {
          "payment_submission": {
            "data": []
          },
          "payment_return": {
            "data": []
          },
          "payment_admission": {
            "data": []
          },
          "payment_reversal": {
            "data": []
          },
          "payment_recall": {
            "data": []
          },
          "payment_advice": {
            "data": []
          }
        }
      }
    }
    
    {
      "data": {
        "type": "payments",
        "id": "1c5dafcd-f614-435c-987d-6d93103f0189",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "700.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "12345678",
            "account_number_code": "BBAN",
            "account_type": 1,
            "account_with": {
              "bank_id": "123456",
              "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": "40322152862679881",
          "payment_scheme": "Bacs",
          "processing_date": "2019-03-29",
          "reference": "ref",
          "scheme_payment_type": "Credit"
        },
        "relationships": {
          "payment_submission": {
            "data": []
          },
          "payment_return": {
            "data": []
          },
          "payment_admission": {
            "data": []
          },
          "payment_reversal": {
            "data": []
          },
          "payment_recall": {
            "data": []
          },
          "payment_advice": {
            "data": []
          }
        }
      }
    }
    

    Example request (SEPA Instant 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": "13.00",
          "beneficiary_party": {
            "name": "Mdm Receiving Test",
            "account_number": "FR1420041010050500013M02606",
            "account_number_code": "IBAN",
            "account_with": {
              "bank_id": "AXABFRPP",
              "bank_id_code": "SWBIC"
            },
            "country": "FR",
            "private_identification": {
              "identification": "AB12345",
              "identification_scheme_code": "CCPT",
              "identification_scheme": "BANK",
              "identification_issuer": "HM Passport Office"
            },
          },
          "charges_information": {
            "bearer_code": "SLEV"
          },
          "currency": "EUR",
          "debtor_party": {
            "name": "Herr Sending Test",
            "account_number": "DE89370400440532013000",
            "account_number_code": "IBAN",
            "account_with": {
              "bank_id": "DEUTDEFF",
              "bank_id_code": "SWBIC"
            },
            "address": [
              "Knesebeckstrasse 4, Breitscheidt",
              "Rheinland-Pfalz, 57539"
            ],
            "country": "DE",
            "private_identification": {
              "identification": "XY9876",
              "identification_scheme_code": "CCPT",
              "identification_scheme": "OTHER_BANK",
              "identification_issuer": "HM Passport Office"
            },
          },
          "ultimate_beneficiary": {
            "private_identification": {
                "identification": "HJ8756",
                "identification_scheme_code": "CCPT",
                "identification_scheme": "ULTIMATE_BANK",
                "identification_issuer": "HM Passport Office"
            },
          },
          "ultimate_debtor": {
            "private_identification": {
                "identification": "DR74653",
                "identification_scheme_code": "CCPT",
                "identification_scheme": "ULTIMATE_BANK",
                "identification_issuer": "HM Passport Office"
            },
          },
          "end_to_end_reference": "471682145093",
          "payment_scheme": "SEPAINSTANT"
        }
      }
    }
    
    
    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": "13.00",
          "beneficiary_party": {
            "name": "Mdm Receiving Test",
            "account_number": "FR1420041010050500013M02606",
            "account_number_code": "IBAN",
            "account_with": {
              "bank_id": "AXABFRPP",
              "bank_id_code": "SWBIC"
            },
            "country": "FR",
            "private_identification": {
              "identification": "AB12345",
              "identification_scheme_code": "CCPT",
              "identification_scheme": "BANK",
              "identification_issuer": "HM Passport Office"
            },
          },
          "charges_information": {
            "bearer_code": "SLEV"
          },
          "currency": "EUR",
          "debtor_party": {
            "name": "Herr Sending Test",
            "account_number": "DE89370400440532013000",
            "account_number_code": "IBAN",
            "account_with": {
              "bank_id": "DEUTDEFF",
              "bank_id_code": "SWBIC"
            },
            "address": [
              "Knesebeckstrasse 4, Breitscheidt",
              "Rheinland-Pfalz, 57539"
            ],
            "country": "DE",
            "private_identification": {
              "identification": "XY9876",
              "identification_scheme_code": "CCPT",
              "identification_scheme": "OTHER_BANK",
              "identification_issuer": "HM Passport Office"
            },
          },
          "ultimate_beneficiary": {
            "private_identification": {
                "identification": "HJ8756",
                "identification_scheme_code": "CCPT",
                "identification_scheme": "ULTIMATE_BANK",
                "identification_issuer": "HM Passport Office"
            },
          },
          "ultimate_debtor": {
            "private_identification": {
                "identification": "DR74653",
                "identification_scheme_code": "CCPT",
                "identification_scheme": "ULTIMATE_BANK",
                "identification_issuer": "HM Passport Office"
            },
          },
          "end_to_end_reference": "471682145093",
          "payment_scheme": "SEPAINSTANT"
        }
      }
    }
    
    
    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': '13.00',
          'beneficiary_party': {
            'name': 'Mdm Receiving Test',
            'account_number': 'FR1420041010050500013M02606',
            'account_number_code': 'IBAN',
            'account_with': {
              'bank_id': 'AXABFRPP',
              'bank_id_code': 'SWBIC'
            },
            'country': 'FR',
            'private_identification': {
              'identification': 'AB12345',
              'identification_scheme_code': 'CCPT',
              'identification_scheme': 'BANK',
              'identification_issuer': 'HM Passport Office'
            },
          },
          'charges_information': {
            'bearer_code': 'SLEV'
          },
          'currency': 'EUR',
          'debtor_party': {
            'name': 'Herr Sending Test',
            'account_number': 'DE89370400440532013000',
            'account_number_code': 'IBAN',
            'account_with': {
              'bank_id': 'DEUTDEFF',
              'bank_id_code': 'SWBIC'
            },
            'address': [
              'Knesebeckstrasse 4, Breitscheidt',
              'Rheinland-Pfalz, 57539'
            ],
            'country': 'DE',
            'private_identification': {
              'identification': 'XY9876',
              'identification_scheme_code': 'CCPT',
              'identification_scheme': 'OTHER_BANK',
              'identification_issuer': 'HM Passport Office'
            },
          },
          'ultimate_beneficiary': {
            'private_identification': {
                'identification': 'HJ8756',
                'identification_scheme_code': 'CCPT',
                'identification_scheme': 'ULTIMATE_BANK',
                'identification_issuer': 'HM Passport Office'
            },
          },
          'ultimate_debtor': {
            'private_identification': {
                'identification': 'DR74653',
                'identification_scheme_code': 'CCPT',
                'identification_scheme': 'ULTIMATE_BANK',
                'identification_issuer': 'HM Passport Office'
            },
          },
          'end_to_end_reference': '471682145093',
          'payment_scheme': 'SEPAINSTANT'
        }
      }
    }
    
    """
    req = requests.post('https://api.form3.tech/v1/transaction/payments', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "payments",
        "id": "20b1f7a2-83c7-45d3-a6e3-0a75b14b9f7f",
        "version": 0,
        "organisation_id": "743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb",
        "attributes": {
          "amount": "13.00",
          "beneficiary_party": {
            "name": "Mdm Receiving Test",
            "account_number": "FR1420041010050500013M02606",
            "account_number_code": "IBAN",
            "account_with": {
              "bank_id": "AXABFRPP",
              "bank_id_code": "SWBIC"
            },
            "country": "FR",
            "private_identification": {
              "identification": "AB12345",
              "identification_scheme_code": "CCPT",
              "identification_scheme": "BANK",
              "identification_issuer": "HM Passport Office"
            },
          },
          "charges_information": {
            "bearer_code": "SLEV"
          },
          "currency": "EUR",
          "debtor_party": {
            "name": "Herr Sending Test",
            "account_number": "DE89370400440532013000",
            "account_number_code": "IBAN",
            "account_with": {
              "bank_id": "DEUTDEFF",
              "bank_id_code": "SWBIC"
            },
            "address": [
              "Knesebeckstrasse 4, Breitscheidt",
              "Rheinland-Pfalz, 57539"
            ],
            "country": "DE",
            "private_identification": {
              "identification": "XY9876",
              "identification_scheme_code": "CCPT",
              "identification_scheme": "OTHER_BANK",
              "identification_issuer": "HM Passport Office"
            },
          },
          "end_to_end_reference": "471682145093",
          "payment_scheme": "SEPAINSTANT",
          "ultimate_beneficiary": {
            "private_identification": {
                "identification": "HJ8756",
                "identification_scheme_code": "CCPT",
                "identification_scheme": "ULTIMATE_BANK",
                "identification_issuer": "HM Passport Office"
            },
          },
          "ultimate_debtor": {
            "private_identification": {
                "identification": "DR74653",
                "identification_scheme_code": "CCPT",
                "identification_scheme": "ULTIMATE_BANK",
                "identification_issuer": "HM Passport Office"
            },
          },
        },
        "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": "13.00",
          "beneficiary_party": {
            "name": "Mdm Receiving Test",
            "account_number": "FR1420041010050500013M02606",
            "account_number_code": "IBAN",
            "account_with": {
              "bank_id": "AXABFRPP",
              "bank_id_code": "SWBIC"
            },
            "country": "FR",
            "private_identification": {
              "identification": "AB12345",
              "identification_scheme_code": "CCPT",
              "identification_scheme": "BANK",
              "identification_issuer": "HM Passport Office"
            },
          },
          "charges_information": {
            "bearer_code": "SLEV"
          },
          "currency": "EUR",
          "debtor_party": {
            "name": "Herr Sending Test",
            "account_number": "DE89370400440532013000",
            "account_number_code": "IBAN",
            "account_with": {
              "bank_id": "DEUTDEFF",
              "bank_id_code": "SWBIC"
            },
            "address": [
              "Knesebeckstrasse 4, Breitscheidt",
              "Rheinland-Pfalz, 57539"
            ],
            "country": "DE",
            "private_identification": {
              "identification": "XY9876",
              "identification_scheme_code": "CCPT",
              "identification_scheme": "OTHER_BANK",
              "identification_issuer": "HM Passport Office"
            },
          },
          "end_to_end_reference": "471682145093",
          "payment_scheme": "SEPAINSTANT",
          "ultimate_beneficiary": {
            "private_identification": {
                "identification": "HJ8756",
                "identification_scheme_code": "CCPT",
                "identification_scheme": "ULTIMATE_BANK",
                "identification_issuer": "HM Passport Office"
            },
          },
          "ultimate_debtor": {
            "private_identification": {
                "identification": "DR74653",
                "identification_scheme_code": "CCPT",
                "identification_scheme": "ULTIMATE_BANK",
                "identification_issuer": "HM Passport Office"
            },
          },
        },
        "relationships": {
          "payment_submission": {
            "data": []