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

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

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

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

    Swagger specification

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

    Form3 Financial Cloud OpenAPI specification / Swagger

    Postman

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

    Form3 Financial Cloud Postman collection

    Endpoint connection

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

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

    Actions and HTTP methods

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

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

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

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

    Headers

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

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

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

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

    URL Parameters

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

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

    Message body structure

    All endpoint request and response bodies are formatted as JSON and follow the REST conventions unless explicitly noted otherwise. Every resource that is created or returned through the API contains a standard set of JSON objects.

    Each resource contains a data and a links section.

    Data section

    The data section contains the resource data that is the subject of the call. List calls can return multiple resources, in this case the data section 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 List Subscription resources response

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
                "type": "subscriptions",
                "id": "ab6d05a8-8d41-4957-833e-fcc42126351b",
                "version": 0,
                "organisation_id": "634e3a41-26b8-49f9-a23d-26fa92061f38",
                "created_on": "2019-10-30T09:29:07.915Z",
                "modified_on": "2019-10-30T09:29:07.915Z",
                "attributes": {
                    "callback_uri": "https://example-webhook-url.com/123",
                    "callback_transport": "http",
                    "user_id": "593ee6e2-3f76-4556-9a92-21336933860b",
                    "record_type": "payment_admissions",
                    "event_type": "created",
                    "deactivated": false
                }
            },
            {
                "type": "subscriptions",
                "id": "60116836-2b02-465c-b395-850b6ef7a4ed",
                "version": 0,
                "organisation_id": "634e3a41-26b8-49f9-a23d-26fa92061f38",
                "created_on": "2020-05-06T09:28:13.843Z",
                "modified_on": "2020-05-06T09:28:13.843Z",
                "attributes": {
                    "callback_uri": "https://example-webhook-url.com/456",
                    "callback_transport": "queue",
                    "user_id": "593ee6e2-3f76-4556-9a92-21336933860b",
                    "record_type": "return_admissions",
                    "event_type": "created",
                    "deactivated": false
                }
            }
        ],
        "links": {
            "self": "/v1/notification/subscriptions?page[number]=first",
            "first": "/v1/notification/subscriptions?page[number]=first",
            "last": "/v1/notification/subscriptions?page[number]=last"
        }
    }
    
    {
        "data": [
            {
                "type": "subscriptions",
                "id": "ab6d05a8-8d41-4957-833e-fcc42126351b",
                "version": 0,
                "organisation_id": "634e3a41-26b8-49f9-a23d-26fa92061f38",
                "created_on": "2019-10-30T09:29:07.915Z",
                "modified_on": "2019-10-30T09:29:07.915Z",
                "attributes": {
                    "callback_uri": "https://example-webhook-url.com/123",
                    "callback_transport": "http",
                    "user_id": "593ee6e2-3f76-4556-9a92-21336933860b",
                    "record_type": "payment_admissions",
                    "event_type": "created",
                    "deactivated": false
                }
            },
            {
                "type": "subscriptions",
                "id": "60116836-2b02-465c-b395-850b6ef7a4ed",
                "version": 0,
                "organisation_id": "634e3a41-26b8-49f9-a23d-26fa92061f38",
                "created_on": "2020-05-06T09:28:13.843Z",
                "modified_on": "2020-05-06T09:28:13.843Z",
                "attributes": {
                    "callback_uri": "https://example-webhook-url.com/456",
                    "callback_transport": "queue",
                    "user_id": "593ee6e2-3f76-4556-9a92-21336933860b",
                    "record_type": "return_admissions",
                    "event_type": "created",
                    "deactivated": false
                }
            }
        ],
        "links": {
            "self": "/v1/notification/subscriptions?page[number]=first",
            "first": "/v1/notification/subscriptions?page[number]=first",
            "last": "/v1/notification/subscriptions?page[number]=last"
        }
    }
    
    {
        "data": [
            {
                "type": "subscriptions",
                "id": "ab6d05a8-8d41-4957-833e-fcc42126351b",
                "version": 0,
                "organisation_id": "634e3a41-26b8-49f9-a23d-26fa92061f38",
                "created_on": "2019-10-30T09:29:07.915Z",
                "modified_on": "2019-10-30T09:29:07.915Z",
                "attributes": {
                    "callback_uri": "https://example-webhook-url.com/123",
                    "callback_transport": "http",
                    "user_id": "593ee6e2-3f76-4556-9a92-21336933860b",
                    "record_type": "payment_admissions",
                    "event_type": "created",
                    "deactivated": false
                }
            },
            {
                "type": "subscriptions",
                "id": "60116836-2b02-465c-b395-850b6ef7a4ed",
                "version": 0,
                "organisation_id": "634e3a41-26b8-49f9-a23d-26fa92061f38",
                "created_on": "2020-05-06T09:28:13.843Z",
                "modified_on": "2020-05-06T09:28:13.843Z",
                "attributes": {
                    "callback_uri": "https://example-webhook-url.com/456",
                    "callback_transport": "queue",
                    "user_id": "593ee6e2-3f76-4556-9a92-21336933860b",
                    "record_type": "return_admissions",
                    "event_type": "created",
                    "deactivated": false
                }
            }
        ],
        "links": {
            "self": "/v1/notification/subscriptions?page[number]=first",
            "first": "/v1/notification/subscriptions?page[number]=first",
            "last": "/v1/notification/subscriptions?page[number]=last"
        }
    }
    
    Attribute Description
    id string, unique identifier (UUID) required always The unique ID of the resource in UUID 4 format. It identifies the resource within the system.
    organisation_id string, unique identifier (UUID) required always The organisation ID of the organisation by which this resource has been created. This is usually the organisation ID of your organisation.
    type string optional always The type of resource. This name is used in the record_type attribute of notification and audit calls to identify a type of resource. Note that you don't need to supply this object when creating a resource, it is automatically added by Form3
    version integer read-only always A read-only counter indicating how many times this resource has been modified. When you create a resource, it is automatically set to 0. Whenever the content of the resource changes, the version attribute is increased.
    You need to provide the latest version number of a resource when patching or deleting it. It is recommended to query the version of the resource immediately before sending such a request since it could have been changed by other processes since you last fetched it.
    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.

    Following the HATEOAS convention, response messages further have a links section. It contains one or more links to related endpoints:

    Attribute Description
    self string read-only always Link to this endpoint or resource.
    first string read-only sometimes Link to the first page of a paginated response. Only available in list call responses.
    last string read-only sometimes Link to the last page of a paginated response. Only available in list call responses.
    next string read-only sometimes Link to the next page of a paginated response. Only available in list call responses.
    prev string read-only sometimes Link to the previous page of a paginated response. Only available in list call responses.

    Errors and Status Codes

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

    Form3 uses the following HTTP status codes:

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

    Receiving Notifications

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

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

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

    Service health

    Example health request

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

    Response (200 OK)

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

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

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

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

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

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

    Change policy

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

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

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

    Authentication

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

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

    Description of the Form3 authentication scheme

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

    Signed Message Signature

    Signature example

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

    Example GET request

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

    Example POST request

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

    Response (401 Unauthorized)

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

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

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

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

    For requests without a body such as GET and DELETE:

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

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

    Authorization Header

    The Authorization header requires the following header parameters:

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

    Deprecated: OAuth-based Authentication

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

    Description of the Form3 authentication scheme

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

    For a complete code example see using an access token.

    Creating an access token

    Example request

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

    Response (200 OK)

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

    Response (403 Invalid)

    HTTP/1.1 403 Invalid
    
    {
        "error": "invalid_grant",
        "error_description": "Wrong email or password."
    }
    
    HTTP/1.1 403 Invalid
    
    {
        "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 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
    
    {
        "type": "AuditEntry",
        "id": "2c0d516c-980c-4779-a2ea-a6f89643693f",
        "version": 0,
        "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
        "attributes": {
            "record_type": "payment_submissions",
            "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
            "action_time": "2020-01-16T17:06:14.596Z",
            "description": "Record updated",
            "before_data": {
                "data": {
                    (Payment Submission resource appears here)
                }
            },
            "after_data": {
                "data": {
                    (Payment Submission resource appears here)
                }
            }
        }
    },
    
    {
        "type": "AuditEntry",
        "id": "2c0d516c-980c-4779-a2ea-a6f89643693f",
        "version": 0,
        "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
        "attributes": {
            "record_type": "payment_submissions",
            "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
            "action_time": "2020-01-16T17:06:14.596Z",
            "description": "Record updated",
            "before_data": {
                "data": {
                    (Payment Submission resource appears here)
                }
            },
            "after_data": {
                "data": {
                    (Payment Submission resource appears here)
                }
            }
        }
    },
    
    {
        "type": "AuditEntry",
        "id": "2c0d516c-980c-4779-a2ea-a6f89643693f",
        "version": 0,
        "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
        "attributes": {
            "record_type": "payment_submissions",
            "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
            "action_time": "2020-01-16T17:06:14.596Z",
            "description": "Record updated",
            "before_data": {
                "data": {
                    (Payment Submission resource appears here)
                }
            },
            "after_data": {
                "data": {
                    (Payment Submission resource appears here)
                }
            }
        }
    },
    
    Attribute Description
    record_type string Type of the resource that this audit entry describes. See audit record types for possible resource types.
    record_id string, unique identifier (UUID) ID of the resource that this audit entry describes
    actioned_by string, unique identifier (UUID) ID of the user who made the change this audit entry describes
    action_time string, datetime Timestamp when the resource was changed
    description string Textual description of the change being made
    before_data resource The resource before the change. Not present if description is Record created.

    For Submission and Admission resources, the relationships section links the full related resource, not only the type and id as in some GET requests.
    after_data resource The resource after the change. Not present if description is Record deleted.

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

    Fetch

    Example request

    GET v1/audit/entries/payment_submissions/2c0d516c-980c-4779-a2ea-a6f89643693f HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/audit/entries/payment_submissions/2c0d516c-980c-4779-a2ea-a6f89643693f \
    -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/audit/entries/payment_submissions/2c0d516c-980c-4779-a2ea-a6f89643693f', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "type": "AuditEntry",
        "id": "2c0d516c-980c-4779-a2ea-a6f89643693f",
        "version": 0,
        "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
        "attributes": {
            "record_type": "payment_submissions",
            "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
            "action_time": "2020-01-16T17:06:14.596Z",
            "description": "Record updated",
            "before_data": {
                "data": {
                    "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "type": "payment_submissions",
                    "version": 0,
                    "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                    "attributes": {
                        "status": "accepted",
                        "submission_datetime": "2020-01-16T17:06:14.502Z",
                        "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                    },
                    "relationships": {
                        "payment": {
                            "data": [
                                {
                                    (...)
                                }
                            ]
                        }
                    }
                }
            },
            "after_data": {
                "data": {
                    "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "type": "payment_submissions",
                    "version": 1,
                    "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                    "attributes": {
                        "status": "validation_pending",
                        "submission_datetime": "2020-01-16T17:06:14.502Z",
                        "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                    },
                    "relationships": {
                        "payment": {
                            "data": [
                                {
                                    (...)
                                }
                            ]
                        }
                    }
                }
            }
        }
    },
    
    {
        "type": "AuditEntry",
        "id": "2c0d516c-980c-4779-a2ea-a6f89643693f",
        "version": 0,
        "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
        "attributes": {
            "record_type": "payment_submissions",
            "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
            "action_time": "2020-01-16T17:06:14.596Z",
            "description": "Record updated",
            "before_data": {
                "data": {
                    "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "type": "payment_submissions",
                    "version": 0,
                    "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                    "attributes": {
                        "status": "accepted",
                        "submission_datetime": "2020-01-16T17:06:14.502Z",
                        "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                    },
                    "relationships": {
                        "payment": {
                            "data": [
                                {
                                    (...)
                                }
                            ]
                        }
                    }
                }
            },
            "after_data": {
                "data": {
                    "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "type": "payment_submissions",
                    "version": 1,
                    "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                    "attributes": {
                        "status": "validation_pending",
                        "submission_datetime": "2020-01-16T17:06:14.502Z",
                        "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                    },
                    "relationships": {
                        "payment": {
                            "data": [
                                {
                                    (...)
                                }
                            ]
                        }
                    }
                }
            }
        }
    },
    
    {
        "type": "AuditEntry",
        "id": "2c0d516c-980c-4779-a2ea-a6f89643693f",
        "version": 0,
        "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
        "attributes": {
            "record_type": "payment_submissions",
            "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
            "action_time": "2020-01-16T17:06:14.596Z",
            "description": "Record updated",
            "before_data": {
                "data": {
                    "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "type": "payment_submissions",
                    "version": 0,
                    "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                    "attributes": {
                        "status": "accepted",
                        "submission_datetime": "2020-01-16T17:06:14.502Z",
                        "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                    },
                    "relationships": {
                        "payment": {
                            "data": [
                                {
                                    (...)
                                }
                            ]
                        }
                    }
                }
            },
            "after_data": {
                "data": {
                    "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "type": "payment_submissions",
                    "version": 1,
                    "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                    "attributes": {
                        "status": "validation_pending",
                        "submission_datetime": "2020-01-16T17:06:14.502Z",
                        "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                    },
                    "relationships": {
                        "payment": {
                            "data": [
                                {
                                    (...)
                                }
                            ]
                        }
                    }
                }
            }
        }
    },
    

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

    HTTP Request

    GET /v1/audit/entries/{record_type}/{resource_id}

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

    Response Body

    Attribute Description
    record_type string Type of the resource that this audit entry describes. See audit record types for possible resource types.
    always
    record_id string, unique identifier (UUID) ID of the resource that this audit entry describes
    always
    actioned_by string, unique identifier (UUID) ID of the user who made the change this audit entry describes
    always
    action_time string, datetime Timestamp when the resource was changed
    always
    description string Textual description of the change being made
    always
    before_data resource The resource before the change. Not present if description is Record created.

    For Submission and Admission resources, the relationships section links the full related resource, not only the type and id as in some GET requests.
    sometimes
    after_data resource The resource after the change. Not present if description is Record deleted.

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

    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": "a57ef413-a788-4e8e-8541-a86c0c702639",
                "version": 0,
                "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                "attributes": {
                    "record_type": "payment_submissions",
                    "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "actioned_by": "c9286f9b-2d5c-96d9-fa7f-74c1c1a2f0ec",
                    "action_time": "2020-01-16T17:06:14.565Z",
                    "description": "Record inserted",
                    "after_data": {
                        "data": {
                            "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                            "type": "payment_submissions",
                            "version": 0,
                            "attributes": {
                                "status": "accepted",
                                "submission_datetime": "2020-01-16T17:06:14.502Z",
                                "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                            },
                            "relationships": {
                                "payment": {
                                    "data": [
                                        {
                                            (...)
                                        }
                                    ]
                                }
                            },
                            "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3"
                        }
                    }
                }
            },
            {
                "type": "AuditEntry",
                "id": "2c0d516c-980c-4779-a2ea-a6f89643693f",
                "version": 0,
                "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                "attributes": {
                    "record_type": "payment_submissions",
                    "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "action_time": "2020-01-16T17:06:14.596Z",
                    "description": "Record updated",
                    "before_data": {
                        "data": {
                            "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                            "type": "payment_submissions",
                            "version": 0,
                            "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                            "attributes": {
                                "status": "accepted",
                                "submission_datetime": "2020-01-16T17:06:14.502Z",
                                "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                            },
                            "relationships": {
                                "payment": {
                                    "data": [
                                        {
                                            (...)
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "after_data": {
                        "data": {
                            "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                            "type": "payment_submissions",
                            "version": 1,
                            "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                            "attributes": {
                                "status": "validation_pending",
                                "submission_datetime": "2020-01-16T17:06:14.502Z",
                                "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                            },
                            "relationships": {
                                "payment": {
                                    "data": [
                                        {
                                            (...)
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "type": "AuditEntry",
                "id": "a57ef413-a788-4e8e-8541-a86c0c702639",
                "version": 0,
                "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                "attributes": {
                    "record_type": "payment_submissions",
                    "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "actioned_by": "c9286f9b-2d5c-96d9-fa7f-74c1c1a2f0ec",
                    "action_time": "2020-01-16T17:06:14.565Z",
                    "description": "Record inserted",
                    "after_data": {
                        "data": {
                            "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                            "type": "payment_submissions",
                            "version": 0,
                            "attributes": {
                                "status": "accepted",
                                "submission_datetime": "2020-01-16T17:06:14.502Z",
                                "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                            },
                            "relationships": {
                                "payment": {
                                    "data": [
                                        {
                                            (...)
                                        }
                                    ]
                                }
                            },
                            "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3"
                        }
                    }
                }
            },
            {
                "type": "AuditEntry",
                "id": "2c0d516c-980c-4779-a2ea-a6f89643693f",
                "version": 0,
                "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                "attributes": {
                    "record_type": "payment_submissions",
                    "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "action_time": "2020-01-16T17:06:14.596Z",
                    "description": "Record updated",
                    "before_data": {
                        "data": {
                            "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                            "type": "payment_submissions",
                            "version": 0,
                            "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                            "attributes": {
                                "status": "accepted",
                                "submission_datetime": "2020-01-16T17:06:14.502Z",
                                "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                            },
                            "relationships": {
                                "payment": {
                                    "data": [
                                        {
                                            (...)
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "after_data": {
                        "data": {
                            "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                            "type": "payment_submissions",
                            "version": 1,
                            "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                            "attributes": {
                                "status": "validation_pending",
                                "submission_datetime": "2020-01-16T17:06:14.502Z",
                                "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                            },
                            "relationships": {
                                "payment": {
                                    "data": [
                                        {
                                            (...)
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "type": "AuditEntry",
                "id": "a57ef413-a788-4e8e-8541-a86c0c702639",
                "version": 0,
                "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                "attributes": {
                    "record_type": "payment_submissions",
                    "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "actioned_by": "c9286f9b-2d5c-96d9-fa7f-74c1c1a2f0ec",
                    "action_time": "2020-01-16T17:06:14.565Z",
                    "description": "Record inserted",
                    "after_data": {
                        "data": {
                            "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                            "type": "payment_submissions",
                            "version": 0,
                            "attributes": {
                                "status": "accepted",
                                "submission_datetime": "2020-01-16T17:06:14.502Z",
                                "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                            },
                            "relationships": {
                                "payment": {
                                    "data": [
                                        {
                                            (...)
                                        }
                                    ]
                                }
                            },
                            "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3"
                        }
                    }
                }
            },
            {
                "type": "AuditEntry",
                "id": "2c0d516c-980c-4779-a2ea-a6f89643693f",
                "version": 0,
                "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                "attributes": {
                    "record_type": "payment_submissions",
                    "record_id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                    "action_time": "2020-01-16T17:06:14.596Z",
                    "description": "Record updated",
                    "before_data": {
                        "data": {
                            "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                            "type": "payment_submissions",
                            "version": 0,
                            "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                            "attributes": {
                                "status": "accepted",
                                "submission_datetime": "2020-01-16T17:06:14.502Z",
                                "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                            },
                            "relationships": {
                                "payment": {
                                    "data": [
                                        {
                                            (...)
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "after_data": {
                        "data": {
                            "id": "7ee78abe-1227-46d9-ab61-77426d20655a",
                            "type": "payment_submissions",
                            "version": 1,
                            "organisation_id": "c37704ef-bc20-4812-956b-b97fad297ae3",
                            "attributes": {
                                "status": "validation_pending",
                                "submission_datetime": "2020-01-16T17:06:14.502Z",
                                "transaction_start_datetime": "2020-01-16T17:06:14.494Z"
                            },
                            "relationships": {
                                "payment": {
                                    "data": [
                                        {
                                            (...)
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        ]
    }
    

    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}

    URL Parameter Default Description
    record_type string required Type of resource the audit entry 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

    Response Body

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

    Record types

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

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

    Address Book

    The address book stores customer information that can be used to carry out transactions. The address book can store contacts and bank accounts associated with them.

    The principal resource of an address book is the Party, which represents the owner of the address book. Their accounts are represented by Party Account resources. A Party can have Contacts associated with it which, in turn, have registered Contact Accounts that can be used as beneficiaries in transactions.

    Parties

    A Party represents an individual or organisation who can make a transaction. All contacts stored in an address book are specific to this party.

    Resource

    Example party resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
            "type": "parties",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "modified_on": "2019-10-23T17:39:29.757Z",
            "created_on": "2019-10-23T17:39:29.757Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "bob.creditor@bobscompany.com",
                "name": [
                    "Bob's Company"
                ],
                "party_type": "organisation",
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567890"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
            "type": "parties",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "modified_on": "2019-10-23T17:39:29.757Z",
            "created_on": "2019-10-23T17:39:29.757Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "bob.creditor@bobscompany.com",
                "name": [
                    "Bob's Company"
                ],
                "party_type": "organisation",
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567890"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
            "type": "parties",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "modified_on": "2019-10-23T17:39:29.757Z",
            "created_on": "2019-10-23T17:39:29.757Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "bob.creditor@bobscompany.com",
                "name": [
                    "Bob's Company"
                ],
                "party_type": "organisation",
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567890"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    

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

    Attribute Description
    address array of string The party's address. Max 4 lines of 35 characters each.

    SEPA DD: Required if country is a non-EU country, optional otherwise.
    city string City where the party address is located
    contact_method string Preferred contact method of the party.

    SEPA DD: Only email is allowed.
    country string [2], ISO code Country the party address is located in. Has to be a ISO 3166-1 alpha-2 format country code.
    district string [35] Municipal district the address is located in
    email_address string [2048] Email address of the party
    name array of string Name of the party. If party_type is organisation, this has to be the company name. If party_type is private, the given name has to be in the first line and the family name in the second line.
    party_type string The type of party. Can either be organisation or private.

    SEPA DD: Only private is allowed.
    post_code string [16] Postal code of the party address
    province string [35] State or region the address is located in
    telephone_number string [30] Phone number of the party. Has to match \+[0-9]{1,3}-[0-9()+\-]{1,30}.
    relationships.contact.data array Array of Contact resources related to the party

    Fetch

    Example request

    GET v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50 \
    -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
            "type": "parties",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "modified_on": "2019-10-23T17:39:29.757Z",
            "created_on": "2019-10-23T17:39:29.757Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "bob.creditor@bobscompany.com",
                "name": [
                    "Bob's Company"
                ],
                "party_type": "organisation",
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567890"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
            "type": "parties",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "modified_on": "2019-10-23T17:39:29.757Z",
            "created_on": "2019-10-23T17:39:29.757Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "bob.creditor@bobscompany.com",
                "name": [
                    "Bob's Company"
                ],
                "party_type": "organisation",
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567890"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
            "type": "parties",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "modified_on": "2019-10-23T17:39:29.757Z",
            "created_on": "2019-10-23T17:39:29.757Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "bob.creditor@bobscompany.com",
                "name": [
                    "Bob's Company"
                ],
                "party_type": "organisation",
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567890"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    

    Get a single party using the party ID.

    HTTP Request

    GET v1/addressbook/parties/{party_id}

    URL Parameter Description
    party_id string, unique identifier (UUID) ID of the party to fetch

    Response Body

    Attribute Description
    address array of string The party's address. Max 4 lines of 35 characters each.

    SEPA DD: Always present if country is a non-EU country, optional otherwise.

    SEPA DD: No additional information
    sometimes
    city string City where the party address is located

    SEPA DD: No additional information
    always
    contact_method string Preferred contact method of the party.

    SEPA DD: Can only be email.
    always
    country string [2], ISO code Country the party address is located in. Always a ISO 3166-1 alpha-2 format country code.

    SEPA DD: No additional information
    always
    district string [35] Municipal district the address is located in

    SEPA DD: No additional information
    sometimes
    email_address string [2048] Email address of the party

    SEPA DD: No additional information
    always
    name array of string Name of the party. If party_type is organisation, this is the company name. If party_type is private, the given name is in the first line and the family name in the second line.

    SEPA DD: Organisation names are not supported.
    always
    party_type string The type of party. Is either organisation or private.

    SEPA DD: Always private
    always
    post_code string [16] Postal code of the party address

    SEPA DD: No additional information
    always
    province string [35] State or region the address is located in

    SEPA DD: No additional information
    sometimes
    telephone_number string [30] Phone number of the party. Matches \+[0-9]{1,3}-[0-9()+\-]{1,30} if present.

    SEPA DD: No additional information
    sometimes
    relationships.contact.data array Array of Contact resources related to the party

    SEPA DD: No additional information
    always

    List

    Example request

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

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "modified_on": "2019-10-23T17:39:29.757Z",
                "created_on": "2019-10-23T17:39:29.757Z",
                "attributes": {
                    "address": [
                        "123 Main Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "bob.creditor@bobscompany.com",
                    "name": [
                        "Bob's Company"
                    ],
                    "party_type": "organisation",
                    "post_code": "UB10 8JJ",
                    "telepohone_number": "+44-1234567890"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {}
                        ]
                    }
                }
            },
            {
                "id": "c2b1fcff-679c-4bd3-a088-23c9ab6138a6",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "modified_on": "2019-10-23T17:41:23.124Z",
                "created_on": "2019-10-23T17:41:23.124Z",
                "attributes": {
                    "address": [
                        "120 Side Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "bob.creditor@bobsothercompany.com",
                    "name": [
                        "Bob's Other Company"
                    ],
                    "party_type": "organisation",
                    "post_code": "UB10 8JJ",
                    "telephone_number": "+44-1234567890"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {}
                        ]
                    }
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "modified_on": "2019-10-23T17:39:29.757Z",
                "created_on": "2019-10-23T17:39:29.757Z",
                "attributes": {
                    "address": [
                        "123 Main Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "bob.creditor@bobscompany.com",
                    "name": [
                        "Bob's Company"
                    ],
                    "party_type": "organisation",
                    "post_code": "UB10 8JJ",
                    "telepohone_number": "+44-1234567890"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {}
                        ]
                    }
                }
            },
            {
                "id": "c2b1fcff-679c-4bd3-a088-23c9ab6138a6",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "modified_on": "2019-10-23T17:41:23.124Z",
                "created_on": "2019-10-23T17:41:23.124Z",
                "attributes": {
                    "address": [
                        "120 Side Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "bob.creditor@bobsothercompany.com",
                    "name": [
                        "Bob's Other Company"
                    ],
                    "party_type": "organisation",
                    "post_code": "UB10 8JJ",
                    "telephone_number": "+44-1234567890"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {}
                        ]
                    }
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "modified_on": "2019-10-23T17:39:29.757Z",
                "created_on": "2019-10-23T17:39:29.757Z",
                "attributes": {
                    "address": [
                        "123 Main Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "bob.creditor@bobscompany.com",
                    "name": [
                        "Bob's Company"
                    ],
                    "party_type": "organisation",
                    "post_code": "UB10 8JJ",
                    "telepohone_number": "+44-1234567890"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {}
                        ]
                    }
                }
            },
            {
                "id": "c2b1fcff-679c-4bd3-a088-23c9ab6138a6",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "modified_on": "2019-10-23T17:41:23.124Z",
                "created_on": "2019-10-23T17:41:23.124Z",
                "attributes": {
                    "address": [
                        "120 Side Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "bob.creditor@bobsothercompany.com",
                    "name": [
                        "Bob's Other Company"
                    ],
                    "party_type": "organisation",
                    "post_code": "UB10 8JJ",
                    "telephone_number": "+44-1234567890"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {}
                        ]
                    }
                }
            }
        ]
    }
    

    List parties with the ability to page.

    HTTP Request

    GET /v1/addressbook/parties?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

    Response Body

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

    Party Accounts

    A party account contains information about the party's own bank account.

    In SEPA Direct Debit via GoCardless, this is the account registered with GoCardless.

    Resource

    Example party account resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "d03ea595-8782-4ab9-8e9d-a610f9e8cceb",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "party_accounts",
            "created_on": "2019-10-23T18:41:23.475Z",
            "modified_on": "2019-10-23T18:41:23.475Z",
            "attributes": {
                "account_name": "Bob Creditor",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_type": "",
                "account_with": {
                    "bank_name": "Bob's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "party": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "d03ea595-8782-4ab9-8e9d-a610f9e8cceb",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "party_accounts",
            "created_on": "2019-10-23T18:41:23.475Z",
            "modified_on": "2019-10-23T18:41:23.475Z",
            "attributes": {
                "account_name": "Bob Creditor",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_type": "",
                "account_with": {
                    "bank_name": "Bob's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "party": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "d03ea595-8782-4ab9-8e9d-a610f9e8cceb",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "party_accounts",
            "created_on": "2019-10-23T18:41:23.475Z",
            "modified_on": "2019-10-23T18:41:23.475Z",
            "attributes": {
                "account_name": "Bob Creditor",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_type": "",
                "account_with": {
                    "bank_name": "Bob's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "party": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    

    Below is a list of all available attribute fields. The availibility of each field depends on the API call. See the Fetch call documentation for additional information for each field when performing this request.

    Attribute Description
    account_name string The name the account is registered with

    SEPA DD: Truncated after 18 characters.
    account_number string The account number

    SEPA DD: Always an IBAN
    account_number_code string [4] The type of identification provided in account_number

    SEPA DD: Always IBAN
    account_type string The type of account

    SEPA DD: Only used if currency is USD. Can be either checking or savings.
    account_with.bank_name string Financial institution name
    account_with.bank_id string [11] Financial institution identification

    SEPA DD: Always a BIC, maximum length 11 characters
    account_with.bank_id_code string [5] The type of identification provided in account_with_bank_id. Always an ISO code as listed in the External Code Sets spreadsheet.

    SEPA DD: Always SWBIC (SWIFT BIC)
    country string [2] Country where the account is held. Always an ISO 3166-1 alpha-2 format country code.
    currency string [3] Currency of the account. Always an ISO 4217 format currency code.
    relationships.party.data array Array containing the Party resource related to the account

    Fetch

    Example request

    GET v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/accounts/d03ea595-8782-4ab9-8e9d-a610f9e8cceb HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/accounts/d03ea595-8782-4ab9-8e9d-a610f9e8cceb \
    -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/accounts/d03ea595-8782-4ab9-8e9d-a610f9e8cceb', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "d03ea595-8782-4ab9-8e9d-a610f9e8cceb",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "party_accounts",
            "created_on": "2019-10-23T18:41:23.475Z",
            "modified_on": "2019-10-23T18:41:23.475Z",
            "attributes": {
                "account_name": "Bob Creditor",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "Bob's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "type": "parties",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "d03ea595-8782-4ab9-8e9d-a610f9e8cceb",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "party_accounts",
            "created_on": "2019-10-23T18:41:23.475Z",
            "modified_on": "2019-10-23T18:41:23.475Z",
            "attributes": {
                "account_name": "Bob Creditor",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "Bob's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "type": "parties",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "d03ea595-8782-4ab9-8e9d-a610f9e8cceb",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "party_accounts",
            "created_on": "2019-10-23T18:41:23.475Z",
            "modified_on": "2019-10-23T18:41:23.475Z",
            "attributes": {
                "account_name": "Bob Creditor",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "Bob's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "type": "parties",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    

    Get a single party account using the party ID and the party account ID.

    HTTP Request

    GET v1/addressbook/parties/{party_id}/accounts/{account_id}

    URL Parameter Description
    party_id string, unique identifier (UUID) ID of the party the account belongs to
    account_id string, unique identifier (UUID) ID of the account to fetch

    Response Body

    Attribute Description
    account_type string The type of account

    SEPA DD: Only used if currency is USD. Can be either checking or savings.
    sometimes
    account_name string The name the account is registered with.

    SEPA DD: Truncated after 18 characters.
    always
    account_number string The account number

    SEPA DD: Always an IBAN
    always
    account_number_code string [4] The type of identification provided in account_number

    SEPA DD: Always IBAN
    always
    account_with_bank_name string Financial institution name

    SEPA DD: No additional information
    sometimes
    account_with_bank_id string [11] Financial institution identification

    SEPA DD: Always a BIC, maximum length 11 characters
    always
    account_with_bank_id_code string [5] The type of identification provided in account_with_bank_id. Always an ISO code as listed in the External Code Sets spreadsheet.

    SEPA DD: Always SWBIC (SWIFT BIC)
    always
    country string [2] Country where the account is held. Always an ISO 3166-1 alpha-2 format country code.

    SEPA DD: No additional information
    always
    currency string [3] Currency of the account. Always an ISO 4217 format currency code.

    SEPA DD: No additional information
    sometimes
    relationships.party.data array Array containing the Party resource related to the account

    SEPA DD: No additional information
    always

    Contacts

    A Contact represents an address book entry on an entity.

    Resource

    Example contact resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contacts",
            "created_on": "2019-10-23T17:41:24.456Z",
            "modified_on": "2019-10-23T17:41:24.456Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            },
            "relationships": {
                "party": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contacts",
            "created_on": "2019-10-23T17:41:24.456Z",
            "modified_on": "2019-10-23T17:41:24.456Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            },
            "relationships": {
                "party": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contacts",
            "created_on": "2019-10-23T17:41:24.456Z",
            "modified_on": "2019-10-23T17:41:24.456Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            },
            "relationships": {
                "party": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    

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

    Attribute Description
    address array of string The contact's address. Max 4 lines of 35 characters each.

    SEPA DD: Required if country is a non-EU country, optional otherwise.
    city string City where the contact address is located
    contact_method string Preferred contact method of the contact.

    SEPA DD: Only email is allowed.
    contact_type string The type of contact. Can either be organisation or private.
    country string [2], ISO code Country the contact address is located in. Has to be a ISO 3166-1 alpha-2 format country code.
    district string [35] Municipal district the address is located in
    email_address string [2048] Email address of the contact
    name array of string Name of the contact. If contact_type is organisation, this has to be the company name. If contact_type is private, the given name has to be in the first line and the family name in the second line.
    post_code string [16] Postal code of the party address
    province string [35] State or region the address is located in
    telephone_number string [30] Phone number of the contact. Has to match \+[0-9]{1,3}-[0-9()+\-]{1,30}.
    relationships.party.data array Array containing the Party resource related to the contact

    Create

    Example request

    POST /v1/addressbook/parties/fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contact HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            }
        }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \
    https://api.form3.tech//v1/addressbook/parties/fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contact \
    -d \
    '{
         "data": {
             "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
             "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
             "attributes": {
                 "address": [
                     "123 Main Street",
                     "Payment Town"
                 ],
                 "city": "London",
                 "contact_method": "email",
                 "contact_type": "organisation",
                 "country": "GB",
                 "province": "England",
                 "district": "Greater London",
                 "email_address": "john.contact@johnscompany.com",
                 "name": [
                     "John's Company Inc."
                 ],
                 "post_code": "UB10 8JJ",
                 "telephone_number": "+44-1234567899"
             }
         }
     }'
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
        'data': {
            'id': 'ce11383a-92cc-4635-90aa-edebda4b1222',
            'organisation_id': 'edebcb14-e364-4dfb-9de3-f5dae105dac5',
            'attributes': {
                'address': [
                    '123 Main Street',
                    'Payment Town'
                ],
                'city': 'London',
                'contact_method': 'email',
                'contact_type': 'organisation',
                'country': 'GB',
                'province': 'England',
                'district': 'Greater London',
                'email_address': 'john.contact@johnscompany.com',
                'name': [
                    'John's Company Inc.'
                ],
                'post_code': 'UB10 8JJ',
                'telephone_number': '+44-1234567899'
            }
        }
    }
    """
    req = requests.post('https://api.form3.tech/v1/addressbook/parties/fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contact', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contacts",
            "created_on": "2019-10-23T17:41:24.456Z",
            "modified_on": "2019-10-23T17:41:24.456Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            },
            "relationships": {
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5"
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contacts",
            "created_on": "2019-10-23T17:41:24.456Z",
            "modified_on": "2019-10-23T17:41:24.456Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            },
            "relationships": {
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5"
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contacts",
            "created_on": "2019-10-23T17:41:24.456Z",
            "modified_on": "2019-10-23T17:41:24.456Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            },
            "relationships": {
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5"
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    

    Create a new contact.

    HTTP Request

    POST /v1/addressbook/parties/{party_id}/contact

    URL Parameter Description
    party_id string, unique identifier (UUID) ID of the party the contact should be created for

    Request Body

    Attribute Description
    address array of string The contact's address. Max 4 lines of 35 characters each.

    SEPA DD: Required if country is a non-EU country, optional otherwise.
    conditional
    city string City where the contact address is located.

    SEPA DD: No additional information
    required
    contact_method string Preferred contact method of the contact.

    SEPA DD: Only email is allowed.
    required
    contact_type string The type of contact. Can either be organisation or private.

    SEPA DD: No additional information
    required
    country string [2], ISO code Country the contact address is located in. Has to be a ISO 3166-1 alpha-2 format country code.

    SEPA DD: No additional information
    required
    district string [35] Municipal district the address is located in.

    SEPA DD: No additional information
    optional
    email_address string [2048] Email address of the contact.

    SEPA DD: No additional information
    required
    name array of string Name of the contact. If contact_type is organisation, this has to be the company name. If contact_type is private, the given name has to be in the first line and the family name in the second line.

    SEPA DD: No additional information
    required
    post_code string [16] Postal code of the contact address.

    SEPA DD: No additional information
    required
    province string [35] State or region the address is located in.

    SEPA DD: No additional information
    optional
    telephone_number string [30] Phone number of the contact. Has to match \+[0-9]{1,3}-[0-9()+\-]{1,30} if provided.

    SEPA DD: No additional information
    optional

    Response Body

    See Fetch call for a list of response body attributes.

    Fetch

    Example request

    GET v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts/ce11383a-92cc-4635-90aa-edebda4b1222 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts/ce11383a-92cc-4635-90aa-edebda4b1222 \
    -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts/ce11383a-92cc-4635-90aa-edebda4b1222', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contacts",
            "created_on": "2019-10-23T17:41:24.456Z",
            "modified_on": "2019-10-23T17:41:24.456Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            }
            "relationships": {
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "parties",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contacts",
            "created_on": "2019-10-23T17:41:24.456Z",
            "modified_on": "2019-10-23T17:41:24.456Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            }
            "relationships": {
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "parties",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    
    {
        "data": {
            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contacts",
            "created_on": "2019-10-23T17:41:24.456Z",
            "modified_on": "2019-10-23T17:41:24.456Z",
            "attributes": {
                "address": [
                    "123 Main Street",
                    "Payment Town"
                ],
                "city": "London",
                "contact_method": "email",
                "contact_type": "organisation",
                "country": "GB",
                "province": "England",
                "district": "Greater London",
                "email_address": "john.contact@johnscompany.com",
                "name": [
                    "John's Company Inc."
                ],
                "post_code": "UB10 8JJ",
                "telephone_number": "+44-1234567899"
            }
            "relationships": {
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "parties",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    

    Get a single contact from the address book using the party ID and the contact ID.

    HTTP Request

    GET v1/addressbook/parties/{party_id}/contacts/{contact_id}

    URL Parameter Description
    party_id string, unique identifier (UUID) ID of the party the contact belongs to
    contact_id string, unique identifier (UUID) ID of the contact to fetch

    Response Body

    Attribute Description
    address array The contact's address. Max 4 lines of 35 characters each.

    SEPA DD: No additional information
    sometimes
    city string City where the contact address is located

    SEPA DD: No additional information
    always
    contact_method string Preferred contact method of the contact.

    SEPA DD: If present, can only be email.
    always
    contact_type string The type of contact. Is either organisation or private.

    SEPA DD: No additional information
    always
    country string [2], ISO code Country the contact address is located in. Always a ISO 3166-1 alpha-2 format country code.

    SEPA DD: No additional information
    always
    district string [35] Municipal district the address is located in.

    SEPA DD: No additional information
    sometimes
    email_address string [2048] Email address of the contact.

    SEPA DD: No additional information
    required
    name array Name of the contact. If contact_type is organisation, this is the company name. If contact_type is private, the given name is in the first line and the family name in the second line.

    SEPA DD: No additional information
    always
    post_code string [16] Postal code of the contact address.

    SEPA DD: No additional information
    always
    province string [35] State or region the address is located in.

    SEPA DD: No additional information
    sometimes
    telephone_number string [30] Phone number of the contact. Matches \+[0-9]{1,3}-[0-9()+\-]{1,30} if present.

    SEPA DD: No additional information
    sometimes
    relationships.party.data array Array containing the Party resource related to the contact.

    SEPA DD: No additional information
    always

    List

    Example request

    GET /v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts \
    -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
                "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contacts",
                "created_on": "2019-10-23T17:41:24.456Z",
                "modified_on": "2019-10-23T17:41:24.456Z",
                "attributes": {
                    "address": [
                        "123 Main Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "contact_type": "organisation",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "john.contact@johnscompany.com",
                    "name": [
                        "John's Company Inc."
                    ],
                    "post_code": "UB10 8JJ",
                    "telephone_number": "+44-1234567899"
                },
                "relationships": {
                    "party": {
                        "data": [
                            {
                                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            },
            {
                "id": "06f5d135-62cf-4da1-82d0-143f128753b6",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contacts",
                "created_on": "2019-10-23T18:03:01.123Z",
                "modified_on": "2019-10-23T18:03:01.123Z",
                "attributes": {
                    "address": [
                        "124 Side Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "contact_type": "organisation",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "jim.contact@jimscompany.com",
                    "name": [
                        "Jim's Company Inc."
                    ],
                    "post_code": "UB10 8JJ",
                    "telephone_number": "+44-1234567898"
                },
                "relationships": {
                    "party": {
                        "data": [
                            {
                                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contacts",
                "created_on": "2019-10-23T17:41:24.456Z",
                "modified_on": "2019-10-23T17:41:24.456Z",
                "attributes": {
                    "address": [
                        "123 Main Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "contact_type": "organisation",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "john.contact@johnscompany.com",
                    "name": [
                        "John's Company Inc."
                    ],
                    "post_code": "UB10 8JJ",
                    "telephone_number": "+44-1234567899"
                },
                "relationships": {
                    "party": {
                        "data": [
                            {
                                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            },
            {
                "id": "06f5d135-62cf-4da1-82d0-143f128753b6",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contacts",
                "created_on": "2019-10-23T18:03:01.123Z",
                "modified_on": "2019-10-23T18:03:01.123Z",
                "attributes": {
                    "address": [
                        "124 Side Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "contact_type": "organisation",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "jim.contact@jimscompany.com",
                    "name": [
                        "Jim's Company Inc."
                    ],
                    "post_code": "UB10 8JJ",
                    "telephone_number": "+44-1234567898"
                },
                "relationships": {
                    "party": {
                        "data": [
                            {
                                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contacts",
                "created_on": "2019-10-23T17:41:24.456Z",
                "modified_on": "2019-10-23T17:41:24.456Z",
                "attributes": {
                    "address": [
                        "123 Main Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "contact_type": "organisation",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "john.contact@johnscompany.com",
                    "name": [
                        "John's Company Inc."
                    ],
                    "post_code": "UB10 8JJ",
                    "telephone_number": "+44-1234567899"
                },
                "relationships": {
                    "party": {
                        "data": [
                            {
                                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            },
            {
                "id": "06f5d135-62cf-4da1-82d0-143f128753b6",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contacts",
                "created_on": "2019-10-23T18:03:01.123Z",
                "modified_on": "2019-10-23T18:03:01.123Z",
                "attributes": {
                    "address": [
                        "124 Side Street",
                        "Payment Town"
                    ],
                    "city": "London",
                    "contact_method": "email",
                    "contact_type": "organisation",
                    "country": "GB",
                    "province": "England",
                    "district": "Greater London",
                    "email_address": "jim.contact@jimscompany.com",
                    "name": [
                        "Jim's Company Inc."
                    ],
                    "post_code": "UB10 8JJ",
                    "telephone_number": "+44-1234567898"
                },
                "relationships": {
                    "party": {
                        "data": [
                            {
                                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    

    List contacts with the ability to page.

    HTTP Request

    GET /v1/addressbook/parties/{party_id}/contacts?page[number]={page_number}&page[size]={page_size}

    URL Parameter Description
    party_id string, unique identifier (UUID) ID of the party the contacts belong to

    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

    Response Body

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

    Contact Accounts

    A Contact Account represents a bank account of an address book contact. A Contact can have multiple accounts.

    Resource

    Example contact account resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contact_accounts",
            "created_on": "2019-10-23T18:40:23.475Z",
            "modified_on": "2019-10-23T18:40:23.475Z",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB60BARC20040491991431",
                "account_number_code": "IBAN",
                "account_type": "",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contact_accounts",
            "created_on": "2019-10-23T18:40:23.475Z",
            "modified_on": "2019-10-23T18:40:23.475Z",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB60BARC20040491991431",
                "account_number_code": "IBAN",
                "account_type": "",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contact_accounts",
            "created_on": "2019-10-23T18:40:23.475Z",
            "modified_on": "2019-10-23T18:40:23.475Z",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB60BARC20040491991431",
                "account_number_code": "IBAN",
                "account_type": "",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {}
                    ]
                }
            }
        }
    }
    

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

    Attribute Description
    account_name string The name the account is registered with.

    SEPA DD: Truncated after 18 characters.
    account_number string The account number

    SEPA DD: Has to be a valid IBAN
    account_number_code string [4] The type of identification provided in account_number

    SEPA DD: Has to be IBAN
    account_type string The type of account

    SEPA DD: Only used if currency is USD. Can be either checking or savings.
    account_with.bank_name string Financial institution name
    account_with.bank_id string [11] Financial institution identification

    SEPA DD: Must be a valid BIC, maximum length 11 characters
    account_with.bank_id_code string [5] The type of identification provided in account_with_bank_id. Always an ISO code as listed in the External Code Sets spreadsheet.

    SEPA DD: Must be SWBIC (SWIFT BIC)
    country string [2] Country where the account is held. Always an ISO 3166-1 alpha-2 format country code.
    currency string [3] Currency of the account. Always an ISO 4217 format currency code.
    relationships.contact.data array Array containing the Contact resource related to the account
    relationships.party.data array Array containing the Party resource related to the account

    Create

    Example request

    POST /v1/addressbook/parties/fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contact/ce11383a-92cc-4635-90aa-edebda4b1222/accounts HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            }
        }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \
    https://api.form3.tech//v1/addressbook/parties/fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contact/ce11383a-92cc-4635-90aa-edebda4b1222/accounts \
    -d \
    '{
         "data": {
             "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
             "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
             "attributes": {
                 "account_name": "John Doe",
                 "account_number": "GB27BARC20038434956869",
                 "account_number_code": "IBAN",
                 "account_with": {
                     "bank_name": "John's Bank",
                     "bank_id": "AXABFRPP",
                     "bank_id_code": "SWBIC"
                 },
                 "country": "GB",
                 "currency": "GBP"
             }
         }
     }'
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
        'data': {
            'id': 'c0d45c02-9cfe-4955-95e4-1438e5386431',
            'organisation_id': 'edebcb14-e364-4dfb-9de3-f5dae105dac5',
            'attributes': {
                'account_name': 'John Doe',
                'account_number': 'GB27BARC20038434956869',
                'account_number_code': 'IBAN',
                'account_with': {
                    'bank_name': 'John's Bank',
                    'bank_id': 'AXABFRPP',
                    'bank_id_code': 'SWBIC'
                },
                'country': 'GB',
                'currency': 'GBP'
            }
        }
    }
    """
    req = requests.post('https://api.form3.tech/v1/addressbook/parties/fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contact/ce11383a-92cc-4635-90aa-edebda4b1222/accounts', json=json, headers=headers)
    print(req.json())
    

    Response (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contact_accounts",
            "created_on": "2019-10-23T18:40:23.475Z",
            "modified_on": "2019-10-23T18:40:23.475Z",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {
                            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "contacts",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                },
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "parties",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contact_accounts",
            "created_on": "2019-10-23T18:40:23.475Z",
            "modified_on": "2019-10-23T18:40:23.475Z",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {
                            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "contacts",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                },
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "parties",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contact_accounts",
            "created_on": "2019-10-23T18:40:23.475Z",
            "modified_on": "2019-10-23T18:40:23.475Z",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {
                            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "contacts",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                },
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "parties",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    

    Create a new account for an existing contact.

    HTTP Request

    POST /v1/addressbook/parties/{party_id}/contacts/{contact_id}/accounts

    URL Parameter Description
    party_id string, unique identifier (UUID) ID of the party the contact belongs to
    contact_id string, unique identifier (UUID) ID of the contact the account belongs to

    Request Body

    Attribute Description
    account_name string The name the account is registered with.

    SEPA DD: Truncated after 18 characters.
    required
    account_number string The account number

    SEPA DD: Has to be a valid IBAN
    required
    account_number_code string [4] The type of identification provided in account_number

    SEPA DD: Must be IBAN
    required
    account_type string The type of account

    SEPA DD: Required if currency is USD. Can be either checking or savings.
    conditional
    account_with.bank_name string Financial institution name.

    SEPA DD: No additional information
    optional
    account_with.bank_id string [11] Financial institution identification

    SEPA DD: Must be a valid BIC, maximum length 11 characters
    required
    account_with.bank_id_code string [5] The type of identification provided in account_with_bank_id. Must be an ISO code as listed in the External Code Sets spreadsheet.

    SEPA DD: Must be SWBIC (SWIFT BIC)
    required
    country string [2] Country where the account is held. Must be an ISO 3166-1 alpha-2 format country code.

    SEPA DD: No additional information
    required
    currency string [3] Currency of the account. Must be an ISO 4217 format currency code if provided.

    SEPA DD: No additional information
    required

    Response Body

    See Fetch call for a list of response body attributes.

    Fetch

    Example request

    GET v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts/ce11383a-92cc-4635-90aa-edebda4b1222/accounts/c0d45c02-9cfe-4955-95e4-1438e5386431 HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts/ce11383a-92cc-4635-90aa-edebda4b1222/accounts/c0d45c02-9cfe-4955-95e4-1438e5386431 \
    -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech/v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts/ce11383a-92cc-4635-90aa-edebda4b1222/accounts/c0d45c02-9cfe-4955-95e4-1438e5386431', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contact_accounts",
            "created_on": "2019-10-23T18:40:23.475Z",
            "modified_on": "2019-10-23T18:40:23.475Z",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {
                            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "contacts",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                },
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "parties",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contact_accounts",
            "created_on": "2019-10-23T18:40:23.475Z",
            "modified_on": "2019-10-23T18:40:23.475Z",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {
                            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "contacts",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                },
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "parties",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    
    {
        "data": {
            "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
            "version": 0,
            "type": "contact_accounts",
            "created_on": "2019-10-23T18:40:23.475Z",
            "modified_on": "2019-10-23T18:40:23.475Z",
            "attributes": {
                "account_name": "John Doe",
                "account_number": "GB27BARC20038434956869",
                "account_number_code": "IBAN",
                "account_with": {
                    "bank_name": "John's Bank",
                    "bank_id": "AXABFRPP",
                    "bank_id_code": "SWBIC"
                },
                "country": "GB",
                "currency": "GBP"
            },
            "relationships": {
                "contact": {
                    "data": [
                        {
                            "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "contacts",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                },
                "party": {
                    "data": [
                        {
                            "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                            "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                            "type": "parties",
                            "attributes": {
                                (...)
                            }
                        }
                    ]
                }
            }
        }
    }
    

    Get a single contact account using the party ID, the contact ID and the contact account ID.

    HTTP Request

    GET v1/addressbook/parties/{party_id}/contacts/{contact_id}/accounts/{account_id}

    URL Parameter Description
    party_id string, unique identifier (UUID) ID of the party the contact belongs to
    contact_id string, unique identifier (UUID) ID of the contact the account belongs to
    account_id string, unique identifier (UUID) ID of the account to fetch

    Response Body

    Attribute Description
    account_name string The name the account is registered with.

    SEPA DD: Truncated after 18 characters.
    always
    account_number string The account number

    SEPA DD: Always a valid IBAN
    always
    account_number_code string [4] The type of identification provided in account_number

    SEPA DD: Always IBAN
    always
    account_type string The type of account

    SEPA DD: Required if currency is USD. Can be either checking or savings.
    sometimes
    account_with.bank_name string Financial institution name

    SEPA DD: No additional information
    sometimes
    account_with.bank_id string [11] Financial institution identification

    SEPA DD: No additional information
    always
    account_with.bank_id_code string [5] The type of identification provided in account_with_bank_id. Always an ISO code as listed in the External Code Sets spreadsheet.

    SEPA DD: Always a BIC, maximum length 11 characters
    always
    country string [2] Country where the account is held. Always an ISO 3166-1 alpha-2 format country code.

    SEPA DD: Always SWBIC (SWIFT BIC)
    always
    currency string [3] Currency of the account. Always an ISO 4217 format currency code.

    SEPA DD: No additional information
    always
    relationships.contact.data array Array containing the Contact resource related to the account.

    SEPA DD: No additional information
    always
    relationships.party.data array Array containing the Party resource related to the account.

    SEPA DD: No additional information
    always

    List

    Example request

    GET /v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts/ce11383a-92cc-4635-90aa-edebda4b1222/accounts HTTP/1.1
    Accept: application/vnd.api+json
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech//v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts/ce11383a-92cc-4635-90aa-edebda4b1222/accounts \
    -H "Accept: application/vnd.api+json"
    
    import requests
    headers = {'accept': 'vnd.api+json'}
    req = requests.get('https://api.form3.tech//v1/addressbook/parties/2fa9a27c9-d2e5-416e-bf10-61f2edb55b50/contacts/ce11383a-92cc-4635-90aa-edebda4b1222/accounts', headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
                "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contact_accounts",
                "created_on": "2019-10-23T18:40:23.475Z",
                "modified_on": "2019-10-23T18:40:23.475Z",
                "attributes": {
                    "account_name": "John Doe",
                    "account_number": "GB27BARC20038434956869",
                    "account_number_code": "IBAN",
                    "account_with": {
                        "bank_name": "John's Bank",
                        "bank_id": "AXABFRPP",
                        "bank_id_code": "SWBIC"
                    },
                    "country": "GB",
                    "currency": "GBP"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {
                                "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "contacts",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    },
                    "party": {
                        "data": [
                            {
                                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            },
            {
                "id": "f32c0ba1-cd3d-4109-863c-9fc2af8311dc",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contact_accounts",
                "created_on": "2019-10-23T18:41:20.455Z",
                "modified_on": "2019-10-23T18:41:20.455Z",
                "attributes": {
                    "account_name": "John Doe",
                    "account_number": "GB60BARC20040491991431",
                    "account_number_code": "IBAN",
                    "account_with": {
                        "bank_name": "John's Bank",
                        "bank_id": "AXABFRPP",
                        "bank_id_code": "SWBIC"
                    },
                    "country": "GB",
                    "currency": "GBP"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {
                                "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "contacts",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    },
                    "party": {
                        "data": [
                            {
                                "id": "0d35de9b-96f8-4878-9754-54c05e884f18",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contact_accounts",
                "created_on": "2019-10-23T18:40:23.475Z",
                "modified_on": "2019-10-23T18:40:23.475Z",
                "attributes": {
                    "account_name": "John Doe",
                    "account_number": "GB27BARC20038434956869",
                    "account_number_code": "IBAN",
                    "account_with": {
                        "bank_name": "John's Bank",
                        "bank_id": "AXABFRPP",
                        "bank_id_code": "SWBIC"
                    },
                    "country": "GB",
                    "currency": "GBP"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {
                                "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "contacts",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    },
                    "party": {
                        "data": [
                            {
                                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            },
            {
                "id": "f32c0ba1-cd3d-4109-863c-9fc2af8311dc",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contact_accounts",
                "created_on": "2019-10-23T18:41:20.455Z",
                "modified_on": "2019-10-23T18:41:20.455Z",
                "attributes": {
                    "account_name": "John Doe",
                    "account_number": "GB60BARC20040491991431",
                    "account_number_code": "IBAN",
                    "account_with": {
                        "bank_name": "John's Bank",
                        "bank_id": "AXABFRPP",
                        "bank_id_code": "SWBIC"
                    },
                    "country": "GB",
                    "currency": "GBP"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {
                                "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "contacts",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    },
                    "party": {
                        "data": [
                            {
                                "id": "0d35de9b-96f8-4878-9754-54c05e884f18",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    
    {
        "data": [
            {
                "id": "c0d45c02-9cfe-4955-95e4-1438e5386431",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contact_accounts",
                "created_on": "2019-10-23T18:40:23.475Z",
                "modified_on": "2019-10-23T18:40:23.475Z",
                "attributes": {
                    "account_name": "John Doe",
                    "account_number": "GB27BARC20038434956869",
                    "account_number_code": "IBAN",
                    "account_with": {
                        "bank_name": "John's Bank",
                        "bank_id": "AXABFRPP",
                        "bank_id_code": "SWBIC"
                    },
                    "country": "GB",
                    "currency": "GBP"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {
                                "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "contacts",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    },
                    "party": {
                        "data": [
                            {
                                "id": "fa9a27c9-d2e5-416e-bf10-61f2edb55b50",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            },
            {
                "id": "f32c0ba1-cd3d-4109-863c-9fc2af8311dc",
                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                "version": 0,
                "type": "contact_accounts",
                "created_on": "2019-10-23T18:41:20.455Z",
                "modified_on": "2019-10-23T18:41:20.455Z",
                "attributes": {
                    "account_name": "John Doe",
                    "account_number": "GB60BARC20040491991431",
                    "account_number_code": "IBAN",
                    "account_with": {
                        "bank_name": "John's Bank",
                        "bank_id": "AXABFRPP",
                        "bank_id_code": "SWBIC"
                    },
                    "country": "GB",
                    "currency": "GBP"
                },
                "relationships": {
                    "contact": {
                        "data": [
                            {
                                "id": "ce11383a-92cc-4635-90aa-edebda4b1222",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "contacts",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    },
                    "party": {
                        "data": [
                            {
                                "id": "0d35de9b-96f8-4878-9754-54c05e884f18",
                                "organisation_id": "edebcb14-e364-4dfb-9de3-f5dae105dac5",
                                "type": "parties",
                                "attributes": {
                                    (...)
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    

    List contact accounts with the ability to page.

    HTTP Request

    GET /v1/addressbook/parties/{party_id}/contacts/{contact_id}/accounts?page[number]={page_number}&page[size]={page_size}

    URL Parameter Description
    party_id string, unique identifier (UUID) ID of the party the contact belongs to
    contact_id string, unique identifier (UUID) ID of the contact the accounts belong to

    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

    Response Body

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

    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

    For security reasons, we require you to whitelist the domain of your webhook URLs and the AWS account ID used for your SQS queues with us. This can be done via the Form3 Portal. Speak to your implementation manager for more information on how to whitelist a specific domain or AWS account ID.

    SQS

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

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

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

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

    2. Add the required permission to the queue:

    For a test environment

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

    For a production environment

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

    For more information about AWS permissions, see here.

    SQS with SSE (Server Side Encryption)

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

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

    For the staging environment:

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

    For the production environment:

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

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

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

    Webhooks

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

    Description of the Form3 webhook scheme

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

    Form3 validates the certificate based on the following criteria:

    Reputable certificate providers include:

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

    Our client certificate details

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

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

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

    Handling delivery errors

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

     Exponential backoff

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

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

    The delay is calculated based on the following formula:

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

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

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

    Reactivate subscriptions

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

    If the callback_uri or filter fields of the Subscription resource are modified before the subscription is reactivated, all notifications that were stored while the subscription was inactive will be filtered using the new filter value and delivered to the new callback_uri.

    Note that reactivating a subscription that has been deactivated because the domain of the callback URL is not whitelisted is possible, but will lead to another deactivation since notification delivery will continue to fail. Speak with your implementation manager to whitelist a domain.

    Subscriptions

    Resource

    Example subscription

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

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

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

    Create

    Example request

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

    Example response (201 Created)

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

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

    HTTP Request

    POST /v1/notification/subscriptions

    Request Body

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

    Response Body

    See Fetch call for a list of response body attributes.

    Fetch

    Example request

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

    Example response (200 OK)

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

    Get a single subscription using the subscription ID.

    HTTP Request

    GET /v1/notification/subscriptions/{id}

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

    Response Body

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

    List

    Example request

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

    Example response (200 OK)

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

    List subscriptions with the ability to filter and page.

    HTTP Request

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

    Page parameters

    All parameters are optional.

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

    Filter parameters

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

    Response Body

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

    Patch

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

    Example request

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

    Response (201 Created)

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

    HTTP Request

    PATCH /v1/notification/subscriptions/{subscription_id}

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

    Request Body

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

    Response Body

    See Fetch call for a list of response body attributes.

    Delete

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

    Example request

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

    Response (204 No Content)

    HTTP Request

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

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

    HTTP Response

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

    Events

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

    Event types

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

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

    Record types

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

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

    Filters

    Subscription for updating Payment Admissions to failed only

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

    Notification that matches the filter for failed Payment Admissions

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

    Subscription for FPS Admissions only

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

    Notification matching filter for FPS-only Admissions

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

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

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

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

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

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

    Nested arrays

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

    Common use cases

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

    Common subscription routings include:

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

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

    Event notification format

    Example event payment admission with payment in relationship section

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

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

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

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

    Common event subscriptions

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

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

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

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

    Reports

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

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

    Download a report

    Example download request

    GET /v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a HTTP/1.1
    Accept: application/xml
    Host: api.form3.tech
    
    curl -X GET https://api.form3.tech/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a \
       -H "Accept: application/xml" --output report.xml
    
    import requests
    headers = {
        'authorization': "bearer YOUR_TOKEN_HERE",
        'accept': "application/xml",
        }
    req = requests.get('https://api.form3.tech/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a', headers=headers)
    open('report.xml', '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": "Input",
              "generation_time": "2019-01-16T16:04:31.194Z",
              "processing_date": "2019-01-16",
              "report_source": "BACS_SERVICE_USER",
              "formats": [
                  "xml",
                  "zipped_xhtml"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "xml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
       }   
    }
    
    
    {
       "data": { 
          "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
          "type": "reports",
          "version": 1,    
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "created_on": "2019-01-16T16:04:31.486Z",
          "modified_on": "2019-01-16T16:05:45.984Z",    
          "attributes": {
              "report_type": "2013",
              "report_type_description": "Input",
              "generation_time": "2019-01-16T16:04:31.194Z",
              "processing_date": "2019-01-16",
              "report_source": "BACS_SERVICE_USER",
              "formats": [
                  "xml",
                  "zipped_xhtml"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "xml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
       }   
    }
    
    
    {
       "data": { 
          "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
          "type": "reports",
          "version": 1,    
          "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
          "created_on": "2019-01-16T16:04:31.486Z",
          "modified_on": "2019-01-16T16:05:45.984Z",    
          "attributes": {
              "report_type": "2013",
              "report_type_description": "Input",
              "generation_time": "2019-01-16T16:04:31.194Z",
              "processing_date": "2019-01-16",
              "report_source": "BACS_SERVICE_USER",
              "formats": [
                  "xml",
                  "zipped_xhtml"
              ]
          },    
          "relationships": {
              "report_admission": {
                  "data": [
                      {
                          "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
                          "type": "report_admissions",
                          "version": 0,    
                          "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                          "modified_on": "2019-01-16T16:05:03.261Z",
                          "created_on": "2019-01-16T16:05:03.261Z",
                          "attributes": {
                              "admission_datetime": "2019-01-16T16:05:03.261Z",
                              "status": "delivery_confirmed"
                          }
                      }
                  ]
              }
          }    
       },
       "links": {
          "self": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a"
          },
          "xml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xml"
            }
          },
          "zipped_xhtml": {
            "href": "/v1/notification/reports/bdbcc3df-183c-43ef-b1e4-fdd6f3cf589a",
            "meta": {
              "content-type": "application/xhtml+zip"
            }
          }
       }   
    }
    
    
    Attribute Description
    report_type string The type of report, usually a scheme-specific code

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

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

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

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

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

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

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

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

    FPS: Always FPS

    FPS MIDEP: Always FPS_MIDEP

    Bacs: Always BACS_SERVICE_USER

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

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

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

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

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

    Fetch

    Example request

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

    Response (200 OK)

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

    Get a report using the report ID.

    HTTP Request

    GET v1/notification/reports/{report_id}

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

    Response Body

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

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

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

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

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

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

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

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

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

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

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

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

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

    FPS: Always FPS
    always

    FPS MIDEP: Always FPS_MIDEP
    always

    Bacs: Always BACS_SERVICE_USER
    always

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

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

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

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

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

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

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

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

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

    FPS & MIDEP: No additional information
    always

    Bacs: No additional information
    always

    SEPA Instant & SCT: No additional information
    always

    List

    Example request

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

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
        "data": [
            {
                "id": "2e885451-3089-4e84-bf0e-0646b99697c2",
                "type": "reports",
                "version": 0,
                "created_on": "2019-01-16T16:03:37.617Z",
                "modified_on": "2019-01-16T16:03:37.617Z",
                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                "attributes": {
                    "report_type": "Balance",
                    "report_type_description": "Example of a Balance Report",
                    "report_source": "FPS",
                    "generation_time": "2019-01-16T16:03:37.515Z",
                    "processing_date": "2019-01-16"
                },
                "relationships": {
                    "report_admission": {
                        "data": [
                            {
                                "id": "ab740c4a-bc6b-4ff7-a092-d74b8c00e683",
                                "type": "report_admissions",
                                "version": 0,
                                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                                "created_on": "2019-01-16T16:03:37.617Z",
                                "modified_on": "2019-01-16T16:03:37.617Z",
                                "attributes": {
                                    "admission_datetime": "2019-01-16T16:03:37.617Z",
                                    "status": "delivery_confirmed"
                                }
                            }
                        ]
                    }
                }
            },
            {
                "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": "Input",
                    "report_source": "BACS_SERVICE_USER",
                    "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",
                                    "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": "ab740c4a-bc6b-4ff7-a092-d74b8c00e683",
                                "type": "report_admissions",
                                "version": 0,
                                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                                "created_on": "2019-01-16T16:03:37.617Z",
                                "modified_on": "2019-01-16T16:03:37.617Z",
                                "attributes": {
                                    "admission_datetime": "2019-01-16T16:03:37.617Z",
                                    "status": "delivery_confirmed"
                                }
                            }
                        ]
                    }
                }
            },
            {
                "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": "Input",
                    "report_source": "BACS_SERVICE_USER",
                    "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",
                                    "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": "ab740c4a-bc6b-4ff7-a092-d74b8c00e683",
                                "type": "report_admissions",
                                "version": 0,
                                "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
                                "created_on": "2019-01-16T16:03:37.617Z",
                                "modified_on": "2019-01-16T16:03:37.617Z",
                                "attributes": {
                                    "admission_datetime": "2019-01-16T16:03:37.617Z",
                                    "status": "delivery_confirmed"
                                }
                            }
                        ]
                    }
                }
            },
            {
                "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": "Input",
                    "report_source": "BACS_SERVICE_USER",
                    "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",
                                    "status": "delivery_confirmed"
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
    
    

    List reports with the ability to filter and page.

    HTTP Request

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

    Page parameters

    All fields are optional.

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

    Response Body

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

    Report Admissions

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

    Resource

    Example report admission resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "id": "bdd9d57d-4350-498f-8647-4c7a6dfba760",
      "type": "report_admissions",
      "version": 0,
      "organisation_id": "ed68f4ab-9e74-e010-a83a-a1b3e3496613",
      "created_on": "2019-01-16T16:05:03.261Z",
      "modified_on": "2019-01-16T16:05:03.261Z",
      "attributes": {
        "admission_datetime": "2019-01-16T16:05:03.261Z",
        "status": "delivery_confirmed"
      },
      "relationships": {
        "report": {
          "data": [
            {
              "id": "3c0e4b24-b1fc-4d6a-9ec7-5cf49fc70c99",
              "type": "reports",
              "version": 1,    
              "organisation_id": "d3cd3546-6d33-410e-9df4-a61dc3e8e9f5",
              "created_on": "2019-01-16T16:04:31.486Z",
              "modified_on": "2019-01-16T16:05:45.984Z",    
              "attributes": {
                "report_type": "2013",
                "report_type_description": "Input",
                "generation_time": "2019-01-16T16:04:31.194Z",
                "processing_date": "2019-01-16",
                "report_source": "BACS_SERVICE_USER",
                "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": "Input",
                "generation_time": "2019-01-16T16:04:31.194Z",
                "processing_date": "2019-01-16",
                "report_source": "BACS_SERVICE_USER",
                "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": "Input",
                "generation_time": "2019-01-16T16:04:31.194Z",
                "processing_date": "2019-01-16",
                "report_source": "BACS_SERVICE_USER",
                "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": "Input",
                "generation_time": "2019-01-16T16:04:31.194Z",
                "processing_date": "2019-01-16",
                "report_source": "BACS_SERVICE_USER",
                "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": "Input",
                "generation_time": "2019-01-16T16:04:31.194Z",
                "processing_date": "2019-01-16",
                "report_source": "BACS_SERVICE_USER",
                "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": "Input",
                "generation_time": "2019-01-16T16:04:31.194Z",
                "processing_date": "2019-01-16",
                "report_source": "BACS_SERVICE_USER",
                "formats": [
                    "pdf"
                ]
              }
            }
          ]
        }
      }
    }
    
    

    Get a single report admission using the admission ID.

    HTTP Request

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

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

    Scheme Messages

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

    A list of supported scheme messages is provided below

    Scheme Message

    Resource

    Example scheme message resource

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

    Fetch

    Example request

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

    Response (200 OK)

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

    Get a single scheme message using the scheme message ID.

    HTTP Request

    GET v1/notification/schememessages/{scheme_message_id}

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

    List

    Example request

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

    Response (200 OK)

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

    List scheme messages with the ability to filter and page.

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

    Page parameters

    All fields are optional.

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

    Scheme Message Admissions

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

    Resource

    Example scheme message admission resource

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

    Fetch

    Example request

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

    Response (200 OK)

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

    Get a single scheme message admission using the admission ID.

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

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

    Organisation

    Accounts

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

    Resource

    Example account resource

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "switched": false,
          "private_identification": {
            "birth_date": "2017-07-23",
            "birth_country": "GB",
            "identification": "13YH458762",
            "address": "[10 Avenue des Champs]",
            "city": "London",
            "country": "GB"
          },
          "organisation_identification": {
            "identification": "123654",
            "actors": [
              {
                "name": [
                  "Jeff Page"
                ],
                "birth_date": "1970-01-01",
                "residency": "GB"
              }
            ],
            "address": ["10 Avenue des Champs"],
            "city": "London",
            "country": "GB"
          },
          "status": "confirmed"
        },
        "relationships": {
          "master_account": {
            "data": [{
              "type": "accounts",
              "id": "a52d13a4-f435-4c00-cfad-f5e7ac5972df"
            }]
          },
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "switched": false,
          "private_identification": {
            "birth_date": "2017-07-23",
            "birth_country": "GB",
            "identification": "13YH458762",
            "address": "[10 Avenue des Champs]",
            "city": "London",
            "country": "GB"
          },
          "organisation_identification": {
            "identification": "123654",
            "actors": [
              {
                "name": [
                  "Jeff Page"
                ],
                "birth_date": "1970-01-01",
                "residency": "GB"
              }
            ],
            "address": ["10 Avenue des Champs"],
            "city": "London",
            "country": "GB"
          },
          "status": "confirmed"
        },
        "relationships": {
          "master_account": {
            "data": [{
              "type": "accounts",
              "id": "a52d13a4-f435-4c00-cfad-f5e7ac5972df"
            }]
          },
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "switched": false,
          "private_identification": {
            "birth_date": "2017-07-23",
            "birth_country": "GB",
            "identification": "13YH458762",
            "address": "[10 Avenue des Champs]",
            "city": "London",
            "country": "GB"
          },
          "organisation_identification": {
            "identification": "123654",
            "actors": [
              {
                "name": [
                  "Jeff Page"
                ],
                "birth_date": "1970-01-01",
                "residency": "GB"
              }
            ],
            "address": ["10 Avenue des Champs"],
            "city": "London",
            "country": "GB"
          },
          "status": "confirmed"
        },
        "relationships": {
          "master_account": {
            "data": [{
              "type": "accounts",
              "id": "a52d13a4-f435-4c00-cfad-f5e7ac5972df"
            }]
          },
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    

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

    Attribute Description
    country string, ISO code ISO 3166-1 code used to identify the domicile of the account, e.g. 'GB', 'FR'
    base_currencystring, ISO code ISO 4217 code used to identify the base currency of the account, e.g. 'GBP', 'EUR'
    bank_id string, maximum length 11 Local country bank identifier. Format depends on the country. Required for most countries.
    bank_id_code string Identifies the type of bank ID being used, see here for allowed value for each country. Required value depends on country attribute.
    account_numberstring Account number. A unique account number will automatically be generated if not provided. If provided, the account number is not validated.
    bic string, 8 or 11 character code SWIFT BIC in either 8 or 11 character format e.g. 'NWBKGB22'
    iban string IBAN of the account. Will be calculated from other fields if not supplied.
    customer_id string A free-format reference that can be used to link this account to an external system
    name array [4] of string [140] Name of the account holder, up to four lines possible.

    CoP: Primary account name. For concatenated personal names, joint account names and organisation names, use the first line. If first and last names of a personal name are separated, the first line is used for first names, the second line for last names. Titles are ignored and should not be entered.

    SEPA Indirect: Can be a person or organisation. Only the first line is used, minimum 5 characters.
    alternative_names array [3] of string [140] Alternative primary account names, only used for UK Confirmation of Payee

    CoP: Up to 3 alternative account names, one in each line of the array.
    account_classification string Classification of account, only used for Confirmation of Payee (CoP)

    CoP: Can be either Personal or Business. Defaults to Personal.
    joint_account boolean Flag to indicate if the account is a joint account, only used for Confirmation of Payee (CoP)

    CoP: Set to true is this is a joint account. Defaults to false.
    account_matching_opt_out boolean Flag to indicate if the account has opted out of account matching, only used for Confirmation of Payee

    CoP: Set to true if the account has opted out of account matching. Defaults to false.
    secondary_identification string [140] Additional information to identify the account and account holder, only used for Confirmation of Payee (CoP)

    CoP: Can be any type of additional identification, e.g. a building society roll number
    switched boolean Flag to indicate if the account has been switched away from this organisation, only used for Confirmation of Payee (CoP)

    CoP: Set to true if the account has been switched using the Current Account Switching Service (CASS), false otherwise. Defaults to false.
    status string Status of the account. Inferred from the status field of the newest Account Event resource associated with the account. Always confirmed for older accounts where no Account Event resources are present.

    All services except SEPA & FPS Indirect (LHV): Can be pending or confirmed. pending is a virtual state and is immediately superseded by confirmed.

    SEPA Indirect: Can be either pending, confirmed or failed.
    private_identification string Account holder identification if the account holder is a private entity

    SEPA & FPS Indirect (LHV): Either this structure or organisation_identification can be present, but never both.
    private_identification.birth_date string The birth date of the account holder

    SEPA & FPS Indirect (LHV): Date must use the format YYYY-MM-DD
    private_identification.birth_country string The birth country of the account holder

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    private_identification.identification string The number of the document used to identify the account holder

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    private_identification.address array of string The street name and house number of the postal address of the account holder.

    SEPA & FPS Indirect (LHV): One array item, between 1 and 140 characters long.
    private_identification.city string The city where the postal address of the account holder is located

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    private_identification.country string The country where the postal address of the account holder is located

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    organisation_identification string Account holder identification if the account holder is an organisation

    SEPA & FPS Indirect (LHV): Either this structure or private_identification can be present, but never both.
    organisation_identification.identification string The registration number used to identify the account holding organisation.

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    organisation_identification.actors.name array [4] of string [255] The name of a person representing the account holding organisation

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long, only the first array line is used.
    organisation_identification.actors.birth_date string The birth date of the person named in organisation_identification.actors.name

    SEPA & FPS Indirect (LHV): Date must use the format YYYY-MM-DD
    organisation_identification.actors.residency string The country of residency of the person named in organisation_identification.actors.name

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    organisation_identification.address array of string The street name and house number of the postal address of the account holding organisation.

    SEPA & FPS Indirect (LHV): One array item, between 1 and 140 characters long.
    organisation_identification.city string The city where address of the account holding organisation is located

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    organisation_identification.country string The country where address of the account holding organisation is located

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    relationships.account_events array The Account Event resources related to this account. Not present in List calls.

    All services except SEPA & FPS Indirect (LHV): 2 Account Event resource are created when the Account resource is created. For older accounts that were created before the introduction of Account Events, no resources are listed.

    SEPA Indirect (LHV): One Account Event is created upon creation of the Account resource, another once the account creation with LHV has succeeded or failed.
    relationships.master_account array The master account related to this account

    SEPA & FPS Indirect (LHV): Used in virtual accounts to define which master account the virtual account is assigned to.
    title string [40]
    Deprecated
    The account holder's title, e.g. Ms, Dr, Mr. Only used for UK Confirmation of Payee (CoP). Superseded by name.
    first_name string [40]
    Deprecated
    The account holder's first name, only used for UK Confirmation of Payee (CoP). Superseded by name.

    CoP: Only used for personal accounts and when joint_account is false.
    bank_account_name string [140]
    Deprecated
    Primary account name, only used for UK Confirmation of Payee (CoP). Superseded by name.

    CoP: Required if Confirmation of Payee is enabled for the organisation.
    alternative_bank_account_names array [3] of string [140]
    Deprecated
    Alternative primary account names, only used for UK Confirmation of Payee. Superseded by alternative_names.

    CoP: Up to 3 alternative account names, one in each line of the array.
    private_identification.title string
    Deprecated
    The title of the account holder, e.g. Ms, Dr, Mr. Superseded by name.
    private_identification.first_name string
    Deprecated
    The first name of the account holder. Superseded by name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    private_identification.last_name string
    Deprecated
    The last name of the account holder. Superseded by name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    private_identification.document_number string
    Deprecated
    The number of the document used to identify the account holder. Superseded by private_identification.identification.

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    organisation_identification.name string
    Deprecated
    The name of the account holding organisation. Superseded by name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    organisation_identification.registration_number string
    Deprecated
    The registration number used to identify the account holding organisation. Superseded by organisation_identification.identification.

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    organisation_identification.representative.name string
    Deprecated
    The name of a person representing the account holding organisation. Superseded by organisation_identification.actors.name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    organisation_identification.representative.birth_date string
    Deprecated
    The birth date of the person named in organisation_identification.representative.name. Superseded by organisation_identification.actors.birth_date.

    SEPA & FPS Indirect (LHV): Date must use the format YYYY-MM-DD
    organisation_identification.representative.residency string
    Deprecated
    The country of residency of the person named in organisation_identification.representative.name. Superseded by organisation_identification.actors.residency.

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'

    Create

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

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

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

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

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

    Example request to create a UK account without CoP (non SEPA Indirect)

    POST /v1/organisation/accounts HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22"
        }
      }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \
    https://api.form3.tech//v1/organisation/accounts \
    -d \
    '{
       "data": {
         "type": "accounts",
         "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
         "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
         "attributes": {
           "country": "GB",
           "base_currency": "GBP",
           "bank_id": "400300",
           "bank_id_code": "GBDSC",
           "bic": "NWBKGB22"
         }
       }
     }'
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'type': 'accounts',
        'id': 'ad27e265-9605-4b4b-a0e5-3003ea9cc4dc',
        'organisation_id': 'eb0bd6f5-c3f5-44b2-b677-acd23cdde73c',
        'attributes': {
          'country': 'GB',
          'base_currency': 'GBP',
          'bank_id': '400300',
          'bank_id_code': 'GBDSC',
          'bic': 'NWBKGB22'
        }
      }
    }
    """
    req = requests.post('https://api.form3.tech/v1/organisation/accounts', json=json, headers=headers)
    print(req.json())
    

    Response for creating a UK account without CoP (non SEPA Indirect) (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    

    Example request to create a UK account with CoP (non SEPA Indirect)

    POST /v1/organisation/accounts HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "name": [
            "Samantha Holder"
          ],
          "alternative_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 \
    -d \
    '{
       "data": {
         "type": "accounts",
         "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
         "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
         "attributes": {
           "country": "GB",
           "base_currency": "GBP",
           "bank_id": "400300",
           "bank_id_code": "GBDSC",
           "bic": "NWBKGB22",
           "name": [
             "Samantha Holder"
           ],
           "alternative_names": [
             "Sam Holder"
           ],
           "account_classification": "Personal",
           "joint_account": false,
           "account_matching_opt_out": false,
           "secondary_identification": "A1B2C3D4"
         }
       }
     }
    '
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'type': 'accounts',
        'id': 'ad27e265-9605-4b4b-a0e5-3003ea9cc4dc',
        'organisation_id': 'eb0bd6f5-c3f5-44b2-b677-acd23cdde73c',
        'attributes': {
          'country': 'GB',
          'base_currency': 'GBP',
          'bank_id': '400300',
          'bank_id_code': 'GBDSC',
          'bic': 'NWBKGB22',
          'name': [
            'Samantha Holder'
          ],
          'alternative_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 for creating a UK account with CoP (non SEPA Indirect) (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    

    Example request SEPA Indirect

    POST /v1/organisation/accounts HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "name": [
            "Samantha Holder"
          ],
          "private_identification": {
            "birth_date": "2017-07-23",
            "birth_country": "GB",
            "identification": "13YH458762",
            "address": ["10 Avenue des Champs"],
            "city": "London",
            "country": "GB"
          }
        },
        "relationships": {
          "master_account": {
            "data": [{
              "type": "accounts",
              "id": "a52d13a4-f435-4c00-cfad-f5e7ac5972df"
            }]
          }
        }
      }
    }
    
    curl -X POST -H "Content-Type: application/vnd.api+json" \
    https://api.form3.tech//v1/organisation/accounts \
    -d \
    '{
       "data": {
         "type": "accounts",
         "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
         "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
         "attributes": {
           "country": "GB",
           "base_currency": "GBP",
           "account_number": "41426819",
           "bank_id": "400300",
           "bank_id_code": "GBDSC",
           "bic": "NWBKGB22",
           "name": [
             "Samantha Holder"
           ],
           "private_identification": {
             "birth_date": "2017-07-23",
             "birth_country": "GB",
             "identification": "13YH458762",
             "address": ["10 Avenue des Champs"],
             "city": "London",
             "country": "GB"
           }
         },
         "relationships": {
           "master_account": {
             "data": [{
               "type": "accounts",
               "id": "a52d13a4-f435-4c00-cfad-f5e7ac5972df"
             }]
           }
         }
       }
     }'
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'type': 'accounts',
        'id': 'ad27e265-9605-4b4b-a0e5-3003ea9cc4dc',
        'organisation_id': 'eb0bd6f5-c3f5-44b2-b677-acd23cdde73c',
        'attributes': {
          'country': 'GB',
          'base_currency': 'GBP',
          'account_number': '41426819',
          'bank_id': '400300',
          'bank_id_code': 'GBDSC',
          'bic': 'NWBKGB22',
          'name': [
            'Samantha Holder'
          ],
          'private_identification': {
            'birth_date': '2017-07-23',
            'birth_country': 'GB',
            'identification': '13YH458762',
            'address': ['10 Avenue des Champs'],
            'city': 'London',
            'country': 'GB'
          }
        },
        'relationships': {
          'master_account': {
            'data': [{
              'type': 'accounts',
              'id': 'a52d13a4-f435-4c00-cfad-f5e7ac5972df'
            }]
          }
        }
      }
    }
    """
    req = requests.post('https://api.form3.tech/v1/organisation/accounts', json=json, headers=headers)
    print(req.json())
    

    Response SEPA Indirect (201 Created)

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "name": [
            "Samantha Holder"
          ],
          "private_identification": {
            "birth_date": "2017-07-23",
            "birth_country": "GB",
            "identification": "13YH458762",
            "address": ["10 Avenue des Champs"],
            "city": "London",
            "country": "GB"
          },
          "status": "pending"
        },
        "relationships": {
          "master_account": {
            "data": [{
              "type": "accounts",
              "id": "a52d13a4-f435-4c00-cfad-f5e7ac5972df"
            }]
          },
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              }
            ]
          }
        }
      }
    }
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "name": [
            "Samantha Holder"
          ],
          "private_identification": {
            "birth_date": "2017-07-23",
            "birth_country": "GB",
            "identification": "13YH458762",
            "address": ["10 Avenue des Champs"],
            "city": "London",
            "country": "GB"
          },
          "status": "pending"
        },
        "relationships": {
          "master_account": {
            "data": [{
              "type": "accounts",
              "id": "a52d13a4-f435-4c00-cfad-f5e7ac5972df"
            }]
          },
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              }
            ]
          }
        }
      }
    }
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "version": 0,
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "name": [
            "Samantha Holder"
          ],
          "private_identification": {
            "birth_date": "2017-07-23",
            "birth_country": "GB",
            "identification": "13YH458762",
            "address": ["10 Avenue des Champs"],
            "city": "London",
            "country": "GB"
          },
          "status": "pending"
        },
        "relationships": {
          "master_account": {
            "data": [{
              "type": "accounts",
              "id": "a52d13a4-f435-4c00-cfad-f5e7ac5972df"
            }]
          },
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              }
            ]
          }
        }
      }
    }
    

    HTTP Request

    POST /v1/organisation/accounts

    Request Body

    Attribute Description
    country string, ISO code ISO 3166-1 code used to identify the domicile of the account, e.g. 'GB', 'FR'
    required
    base_currencystring, ISO code ISO 4217 code used to identify the base currency of the account, e.g. 'GBP', 'EUR'
    optional
    bank_id string, maximum length 11 Local country bank identifier. Format depends on the country. Required for most countries.
    optional
    bank_id_code string Identifies the type of bank ID being used, see here for allowed value for each country. Required value depends on country attribute.
    conditional
    account_numberstring Account number. A unique account number will automatically be generated if not provided. If provided, the account number is not validated.
    optional
    bic string, 8 or 11 character code SWIFT BIC in either 8 or 11 character format e.g. 'NWBKGB22'
    optional
    iban string IBAN of the account. Will be calculated from other fields if not supplied. Ignored in SEPA Indirect, provided by LHV after account generation is successful.
    optional
    customer_id string A free-format reference that can be used to link this account to an external system
    optional
    name array [4] of string [140] Name of the account holder, up to four lines possible.

    CoP: Primary account name. For concatenated personal names, joint account names and organisation names, use the first line. If first and last names of a personal name are separated, use the first line for first names, the second line for last names. Titles are ignored and should not be entered.
    required

    SEPA Indirect: Can be a person or organisation. Only the first line is used, mininum 5 characters.
    required
    alternative_names array [3] of string [140] Alternative primary account names, only used for UK Confirmation of Payee

    CoP: Up to 3 alternative account names, one in each line of the array.
    optional
    account_classification string Classification of account, only used for Confirmation of Payee (CoP)

    CoP: Can be either Personal or Business. Defaults to Personal if not provided.
    optional
    joint_account boolean Flag to indicate if the account is a joint account, only used for Confirmation of Payee (CoP)

    CoP: Set to true is this is a joint account. Defaults to false if not provided.
    optional
    account_matching_opt_out boolean Flag to indicate if the account has opted out of account matching, only used for Confirmation of Payee

    CoP: Set to true if the account has opted out of account matching. Defaults to false if not provided.
    optional
    secondary_identification string [140] Additional information to identify the account and account holder, only used for Confirmation of Payee (CoP)

    CoP: Can be any type of additional identification, e.g. a building society roll number
    optional
    switched boolean Flag to indicate if the account has been switched away from this organisation, only used for Confirmation of Payee (CoP)

    CoP: Set to true if the account has been switched using the Current Account Switching Service (CASS), false otherwise.
    optional
    private_identification string Account holder identification if the account holder is a private entity

    SEPA & FPS Indirect (LHV): Either this structure or organisation_identification can be present, but never both.
    conditional
    private_identification.birth_date string The birth date of the account holder

    SEPA & FPS Indirect (LHV): Date must use the format YYYY-MM-DD
    optional
    private_identification.birth_country string The birth country of the account holder

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    optional
    private_identification.identification string The number of the document used to identify the account holder

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    required
    private_identification.address array of string The street name and house number of the postal address of the account holder.

    SEPA & FPS Indirect (LHV): One array item allowed, string must be between 1 and 140 characters long.
    optional
    private_identification.city string The city where the address of the account holder is located

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    optional
    private_identification.country string The country where the address of the account holder is located

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    optional
    organisation_identification string Account holder identification if the account holder is an organisation

    SEPA & FPS Indirect (LHV): Either this structure or private_identification can be present, but never both.
    conditional
    organisation_identification.identification string The registration number used to identify the account holding organisation.

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    optional
    organisation_identification.address array of string The street name and house number of the postal address of the account holding organisation.

    SEPA & FPS Indirect (LHV): One array item allowed, string must be between 1 and 140 characters long.
    optional
    organisation_identification.city string The city where the postal address of the account holding organisation is located

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    optional
    organisation_identification.country string The country where the postal address of the account holding organisation is located

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    optional
    organisation_identification.actors.name array [4] of string [255] The name of a person representing the account holding organisation

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long. Only the first array line is used.
    optional
    organisation_identification.actors.birth_date string The birth date of the person named in organisation_identification.actors.name

    SEPA & FPS Indirect (LHV): Date must use the format YYYY-MM-DD
    optional
    organisation_identification.actors.residency string The country of residency of the person named in organisation_identification.actors.name

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    optional
    relationships.master_account array The master account related to this account

    SEPA & FPS Indirect (LHV): Required if the account to be created is a virtual account, not used if it is a master account.
    conditional
    title string [40]
    Deprecated
    The account holder's title, e.g. Ms, Dr, Mr. Only used for UK Confirmation of Payee (CoP). Superseded by name.
    optional
    first_name string [40]
    Deprecated
    The account holder's first name, only used for UK Confirmation of Payee (CoP). Superseded by name.

    CoP: Only used for personal accounts and when joint_account is false.
    optional
    bank_account_name string [140]
    Deprecated
    Primary account name, only used for UK Confirmation of Payee (CoP). Superseded by name.

    CoP: Required if Confirmation of Payee is enabled for the organisation.
    optional
    alternative_bank_account_names array [3] of string [140]
    Deprecated
    Alternative primary account names, only used for UK Confirmation of Payee. Superseded by alternative_names.

    CoP: Up to 3 alternative account names, one in each line of the array.
    optional
    private_identification.title string
    Deprecated
    The title of the account holder, e.g. Ms, Dr, Mr. Superseded by name.

    SEPA & FPS Indirect (LHV): No additional information
    optional
    private_identification.first_name string
    Deprecated
    The first name of the account holder. Superseded by name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    optional
    private_identification.last_name string
    Deprecated
    The last name of the account holder. Superseded by name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    optional
    private_identification.document_number string
    Deprecated
    The number of the document used to identify the account holder. Superseded by private_identification.identification.

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    optional
    organisation_identification.name string
    Deprecated
    The name of the account holding organisation. Superseded by name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    optional
    organisation_identification.registration_number string
    Deprecated
    The registration number used to identify the account holding organisation. Superseded by organisation_identification.identification.

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    optional
    organisation_identification.representative.name string
    Deprecated
    The name of a person representing the account holding organisation. Superseded by organisation_identification.actors.name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    optional
    organisation_identification.representative.birth_date string
    Deprecated
    The birth date of the person named in organisation_identification.representative.name. Superseded by organisation_identification.actors.birth_date.

    SEPA & FPS Indirect (LHV): Date must use the format YYYY-MM-DD
    optional
    organisation_identification.representative.residency string
    Deprecated
    The country of residency of the person named in organisation_identification.representative.name. Superseded by organisation_identification.actors.residency.

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    optional

    Response Body

    See Fetch call for a list of response body attributes.

    Fetch

    Example request

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

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "aca32528-d4cf-4d54-93fe-5d80d27ab773"
              }
            ]
          }
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "aca32528-d4cf-4d54-93fe-5d80d27ab773"
              }
            ]
          }
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 0,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "aca32528-d4cf-4d54-93fe-5d80d27ab773"
              }
            ]
          }
        }
      }
    }
    
    

    Get a single account using the account ID.

    HTTP Request

    GET /v1/organisation/accounts/{account_id}

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

    Response Body

    Attribute Description
    country string, ISO code ISO 3166-1 code used to identify the domicile of the account, e.g. 'GB', 'FR'
    always
    base_currencystring, ISO code ISO 4217 code used to identify the base currency of the account, e.g. 'GBP', 'EUR'
    sometimes
    bank_id string, maximum length 11 Local country bank identifier. Format depends on the country. Used for most countries.
    sometimes
    bank_id_code string Identifies the type of bank ID being used, see here for allowed value for each country. Value depends on country attribute.
    sometimes
    account_numberstring Account number. A unique account number will automatically be generated if not provided. If provided, the account number is not validated.
    sometimes
    bic string, 8 or 11 character code SWIFT BIC in either 8 or 11 character format e.g. 'NWBKGB22'
    sometimes
    iban string IBAN of the account. Will be calculated from other fields if not supplied.
    sometimes
    customer_id string A free-format reference that can be used to link this account to an external system
    sometimes
    name array [4] of string [140] Name of the account holder, up to four lines possible.

    CoP: Primary account name. Concatenated personal names, joint account names and organisation names only use the first line. IF two lines are used, first names of a personal name appear in the first line, last names in the second line. Titles are ignored and should not be entered.
    always

    SEPA Indirect: Can be a person or organisation. Only the first line is used, minimum 5 characters.
    always
    alternative_names array [3] of string [140] Alternative primary account names, only used for UK Confirmation of Payee

    CoP: Up to 3 alternative account names, one in each line of the array.
    sometimes
    account_classification string Classification of account, only used for Confirmation of Payee (CoP)

    CoP: Can be either Personal or Business
    always
    joint_account boolean Flag to indicate if the account is a joint account, only used for Confirmation of Payee (CoP)

    CoP: Set to true is this is a joint account, false otherwise.
    always
    account_matching_opt_out boolean Flag to indicate if the account has opted out of account matching, only used for Confirmation of Payee

    CoP: Set to true if the account has opted out of account matching, false otherwise
    always
    secondary_identification string [140] Additional information to identify the account and account holder, only used for Confirmation of Payee (CoP)

    CoP: Can be any type of additional identification, e.g. a building society roll number
    sometimes
    switched boolean Flag to indicate if the account has been switched away from this organisation, only used for Confirmation of Payee (CoP)

    CoP: Set to true if the account has been switched using the Current Account Switching Service (CASS), false otherwise.
    always
    status string Status of the account. Inferred from the status field of the newest Account Event resource associated with the account. Always confirmed for older accounts where no Account Event resources are present.

    All services except SEPA & FPS Indirect (LHV): Can be pending or confirmed. pending is a virtual state and is immediately superseded by confirmed.
    always

    SEPA & FPS Indirect (LHV): Can be either pending, confirmed or failed.
    always
    private_identification string Account holder identification if the account holder is a private entity

    SEPA & FPS Indirect (LHV): Either this structure or organisation_identification can be present, but never both.
    sometimes
    private_identification.birth_date string The birth date of the account holder

    SEPA & FPS Indirect (LHV): Date must use the format YYYY-MM-DD
    sometimes
    private_identification.birth_country string The birth country of the account holder

    SEPA & FPS Indirect (LHV): Must be an ISO 3166-1 country code, e.g. 'GB', 'FR'
    sometimes
    private_identification.identification string The number of the document used to identify the account holder

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    always
    private_identification.address array of string The street name and house number of the postal address of the account holder.

    SEPA & FPS Indirect (LHV): One array item, between 1 and 140 characters long.
    sometimes
    private_identification.city string The city where the postal address of the account holder is located

    SEPA & FPS Indirect (LHV): Between 5 and 255 characters long
    sometimes
    private_identification.country string The country where the postal address of the account holder is located

    SEPA & FPS Indirect (LHV): Always an ISO 3166-1 country code, e.g. 'GB', 'FR'
    sometimes
    organisation_identification string Account holder identification if the account holder is an organisation

    SEPA & FPS Indirect (LHV): Either this structure or private_identification can be present, but never both.
    sometimes
    organisation_identification.identification string The registration number used to identify the account holding organisation.

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    sometimes
    organisation_identification.address array of string The street name and house number of the postal address of the account holding organisation.

    SEPA & FPS Indirect (LHV): One array item, between 1 and 140 characters long.
    sometimes
    organisation_identification.city string The city where the postal address of the account holding organisation is located

    SEPA & FPS Indirect (LHV): Between 5 and 255 characters long
    sometimes
    organisation_identification.country string The country where the postal address of the account holding organisation is located

    SEPA & FPS Indirect (LHV): Always an ISO 3166-1 country code, e.g. 'GB', 'FR'
    sometimes
    organisation_identification.actors.name array [4] of string [255] The name of a person representing the account holding organisation

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long, only the first array line is used.
    sometimes
    organisation_identification.actors.birth_date string The birth date of the person named in organisation_identification.actors.name

    SEPA & FPS Indirect (LHV): Date must use the format YYYY-MM-DD
    sometimes
    organisation_identification.actors.residency string The country of residency of the person named in organisation_identification.actors.name

    SEPA & FPS Indirect (LHV): Always an ISO 3166-1 country code, e.g. 'GB', 'FR'
    sometimes
    relationships.account_events array The Account Event resources related to this account. Not present in List calls.

    All services except SEPA & FPS Indirect (LHV): 2 Account Event resource are created when the Account resource is created. For older accounts that were created before the introduction of Account Events, no resources are listed.
    sometimes

    SEPA & FPS Indirect (LHV): One Account Event is created upon creation of the Account resource, another once the account creation with LHV has succeeded or failed.
    always
    relationships.master_account array The master account related to this account

    SEPA & FPS Indirect (LHV): Always present if the account is a virtual account, not used if it is a master account.
    sometimes
    title string [40]
    Deprecated
    The account holder's title, e.g. Ms, Dr, Mr. Only used for UK Confirmation of Payee (CoP). Superseded by name.
    sometimes
    first_name string [40]
    Deprecated
    The account holder's first name, only used for UK Confirmation of Payee (CoP). Superseded by name.

    CoP: Only used for personal accounts and when joint_account is false.
    sometimes
    bank_account_name string [140]
    Deprecated
    Primary account name, only used for UK Confirmation of Payee (CoP). Superseded by name.

    CoP: Required if Confirmation of Payee is enabled for the organisation.
    sometimes
    alternative_bank_account_names array [3] of string [140]
    Deprecated
    Alternative primary account names, only used for UK Confirmation of Payee. Superseded by alternative_names.

    CoP: Up to 3 alternative account names, one in each line of the array.
    sometimes
    private_identification.title string
    Deprecated
    The title of the account holder, e.g. Ms, Dr, Mr. Superseded by name.

    SEPA & FPS Indirect (LHV): No additional information
    sometimes
    private_identification.first_name string
    Deprecated
    The first name of the account holder. Superseded by name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    sometimes
    private_identification.last_name string
    Deprecated
    The last name of the account holder. Superseded by name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    sometimes
    private_identification.document_number string
    Deprecated
    The number of the document used to identify the account holder. Superseded by private_identification.identification.

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    sometimes
    organisation_identification.name string
    Deprecated
    The name of the account holding organisation. Superseded by name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    sometimes
    organisation_identification.registration_number string
    Deprecated
    The registration number used to identify the account holding organisation. Superseded by organisation_identification.identification.

    SEPA & FPS Indirect (LHV): Must be between 5 and 20 characters long
    sometimes
    organisation_identification.representative.name string
    Deprecated
    The name of a person representing the account holding organisation. Superseded by organisation_identification.actors.name.

    SEPA & FPS Indirect (LHV): Must be between 5 and 255 characters long
    sometimes
    organisation_identification.representative.birth_date string
    Deprecated
    The birth date of the person named in organisation_identification.representative.name. Superseded by organisation_identification.actors.birth_date.

    SEPA & FPS Indirect (LHV): Date must use the format YYYY-MM-DD
    sometimes
    organisation_identification.representative.residency string
    Deprecated
    The country of residency of the person named in organisation_identification.representative.name. Superseded by organisation_identification.actors.residency.

    SEPA & FPS Indirect (LHV): Always an ISO 3166-1 country code, e.g. 'GB', 'FR'
    sometimes

    List

    Example request

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

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": [
        {
          "type": "accounts",
          "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "country": "GB",
            "base_currency": "GBP",
            "account_number": "41426819",
            "bank_id": "400300",
            "bank_id_code": "GBDSC",
            "bic": "NWBKGB22",
            "iban": "GB11NWBK40030041426819",
            "account_classification": "Personal",
            "joint_account": false,
            "switched": false,
            "account_matching_opt_out": false,
            "status": "confirmed"
          }
        },
        {
          "type": "accounts",
          "id": "ea6239c1-99e9-42b3-bca1-92f5c068da6b",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "country": "GB",
            "base_currency": "GBP",
            "account_number": "76357283",
            "bank_id": "400305",
            "bank_id_code": "GBDSC",
            "bic": "LHVBEE22",
            "iban": "EE209642394169415743",
            "account_classification": "Personal",
            "joint_account": false,
            "switched": false,
            "account_matching_opt_out": false,
            "status": "confirmed"
          }
        }
      ]
    }
    
    {
      "data": [
        {
          "type": "accounts",
          "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "country": "GB",
            "base_currency": "GBP",
            "account_number": "41426819",
            "bank_id": "400300",
            "bank_id_code": "GBDSC",
            "bic": "NWBKGB22",
            "iban": "GB11NWBK40030041426819",
            "account_classification": "Personal",
            "joint_account": false,
            "switched": false,
            "account_matching_opt_out": false,
            "status": "confirmed"
          }
        },
        {
          "type": "accounts",
          "id": "ea6239c1-99e9-42b3-bca1-92f5c068da6b",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "country": "GB",
            "base_currency": "GBP",
            "account_number": "76357283",
            "bank_id": "400305",
            "bank_id_code": "GBDSC",
            "bic": "LHVBEE22",
            "iban": "EE209642394169415743",
            "account_classification": "Personal",
            "joint_account": false,
            "switched": false,
            "account_matching_opt_out": false,
            "status": "confirmed"
          }
        }
      ]
    }
    
    {
      "data": [
        {
          "type": "accounts",
          "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "country": "GB",
            "base_currency": "GBP",
            "account_number": "41426819",
            "bank_id": "400300",
            "bank_id_code": "GBDSC",
            "bic": "NWBKGB22",
            "iban": "GB11NWBK40030041426819",
            "account_classification": "Personal",
            "joint_account": false,
            "switched": false,
            "account_matching_opt_out": false,
            "status": "confirmed"
          }
        },
        {
          "type": "accounts",
          "id": "ea6239c1-99e9-42b3-bca1-92f5c068da6b",
          "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
          "version": 0,
          "attributes": {
            "country": "GB",
            "base_currency": "GBP",
            "account_number": "76357283",
            "bank_id": "400305",
            "bank_id_code": "GBDSC",
            "bic": "LHVBEE22",
            "iban": "EE209642394169415743",
            "account_classification": "Personal",
            "joint_account": false,
            "switched": false,
            "account_matching_opt_out": false,
            "status": "confirmed"
          }
        }
      ]
    }
    

    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

    Response Body

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

    Patch

    Example request

    PATCH /v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc HTTP/1.1
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 1,
        "attributes": {
          "alternative_names": [
            "Sam Holder",
            "SM"
          ]
        }
      }
    }
    
    
    curl -X PATCH -H "Content-Type: application/vnd.api+json" \  
    https://api.form3.tech//v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc \
    -d \
    '{
       "data": {
         "type": "accounts",
         "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
         "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
         "version": 1,
         "attributes": {
           "alternative_names": [
             "Sam Holder",
             "SM"
           ]
         }
       }
     }
    '
    
    import requests
    headers = {'Accept': 'vnd.api+json', 'Content-Type': 'application/vnd.api+json'}
    json = """
    {
      'data': {
        'type': 'accounts',
        'id': 'ad27e265-9605-4b4b-a0e5-3003ea9cc4dc',
        'organisation_id': 'eb0bd6f5-c3f5-44b2-b677-acd23cdde73c',
        'version': 1,
        'attributes': {
          'alternative_names': [
            'Sam Holder',
            'SM'
          ]
        }
      }
    }
    
    """
    req = requests.patch('https://api.form3.tech/v1/organisation/accounts/ad27e265-9605-4b4b-a0e5-3003ea9cc4dc', json=json, headers=headers)
    print(req.json())
    

    Response (200 OK)

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 2,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder",
            "SM"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 2,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder",
            "SM"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    
    {
      "data": {
        "type": "accounts",
        "id": "ad27e265-9605-4b4b-a0e5-3003ea9cc4dc",
        "organisation_id": "eb0bd6f5-c3f5-44b2-b677-acd23cdde73c",
        "version": 2,
        "attributes": {
          "country": "GB",
          "base_currency": "GBP",
          "account_number": "41426819",
          "bank_id": "400300",
          "bank_id_code": "GBDSC",
          "bic": "NWBKGB22",
          "iban": "GB11NWBK40030041426819",
          "name": [
            "Samantha Holder"
          ],
          "alternative_names": [
            "Sam Holder",
            "SM"
          ],
          "account_classification": "Personal",
          "joint_account": false,
          "account_matching_opt_out": false,
          "secondary_identification": "A1B2C3D4",
          "status": "confirmed"
        },
        "relationships": {
          "account_events": {
            "data": [
              {
                "type": "account_events",
                "id": "c1023677-70ee-417a-9a6a-e211241f1e9c"
              },
              {
                "type": "account_events",
                "id": "437284fa-62a6-4f1d-893d-2959c9780288"
              }
            ]
          }
        }
      }
    }
    
    

    Update an individual account.

    HTTP Request

    PATCH /v1/organisation/accounts/{account_id}

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

    Request Body

    Attribute Description
    version integer Version number of the resource to patch. Has to be the latest version of the resource.
    Note that the attribute is located on the top level of the resource, not on the attributes sub level (see code example).
    required
    country string, ISO code ISO 3166-1 code used to identify the domicile of the account, e.g. 'GB', 'FR'
    optional
    base_currencystring, ISO code