Navbar

Topics

Introduction

OpenWrks allows your customers to seamlessly and securely share their real-time bank account information with your business.

Through the OpenWrks API you can quickly create secure, personalised and performant products for your customers. Take a look at how you can get access to our sandbox and start using Open Banking data in minutes.

Environments

We provide multiple environments that allow you to explore, develop and integrate with your applications, before progressing to your production system. Make a note of the below URLs:

Sandbox URL:

https://api.openwrks.com/surface-sandbox/

Lab URL:

https://api.openwrks.com/surface-lab/

Live URL:

https://api.openwrks.com/surface/
Environment What's it for?
Sandbox Request a token to explore our API, make requests and receive responses with sample data
Lab Once you’ve been on-boarded, you'll get access to a version of Flow that will allow your users to connect their own bank accounts. This will allow you to perform full end to end authentication and authorisation to individual banks. You can test low volumes against real banks, real customers and ensure your integration is ready ahead of a full live roll out
Live Once you’ve got it all working in the Lab, we’ll promote you to Live. Congratulations, your business is using Open Banking!

Authentication

To authorize, use this code:

curl -X <METHOD> "<api_endpoint_here>" \
  -H "Authorization: Bearer 123456789"

Make sure to replace 123456789 with your API key.

Authentication to the OpenWrks API is performed via Bearer Authentication. Every endpoint requires authentication, so you'll need to add the following header to each request:

Authorization: Bearer <APIKey>

Data Types

All of the OpenWrks API responses returned are in JSON format, with these data types defined as follows:

Type Description
string A UTF-8 encoded string
number An integer
datetime An ISO8601 encoded datetime. All date times are returned in UTC with offset +00:00 (Zulu Time)
decimal All monetary values are returned with up to two decimal places and may be positive (10.99) or negative (-2.5)

Paging

curl -X GET "https://api.openwrks.com/surface/v1/users?page=2&limit=1000&signature=E3B0C44298FC1C14" \
  -H "Authorization: Bearer 123456789"

The above command returns JSON structured like this:

{
  "data": [],
  "_meta": {
    "totalNumberOfRecords": 3000,
    "totalNumberOfPages": 6,
    "pageNumber": 2,
    "pageSize": 1000,
    "signature": "E3B0C44298FC1C14"
  },
  "_links": [
    {
      "rel": "first",
      "href": "https://api.openwrks.com/v1/users?page=1&limit=1000&signature=E3B0C44298FC1C14"
    },
    {
      "rel": "prev",
      "href": "https://api.openwrks.com/v1/users?page=1&limit=1000&signature=E3B0C44298FC1C14"
    },
    {
      "rel": "next",
      "href": "https://api.openwrks.com/v1/users?page=3&limit=1000&signature=E3B0C44298FC1C14"
    },
    {
      "rel": "last",
      "href": "https://api.openwrks.com/v1/users?page=6&limit=1000&signature=E3B0C44298FC1C14"
    }
  ]
}

For endpoints that provide several items, the response will be paged. This means that to retrieve the full set of items for a given resource you may be required to make several requests.

URL Parameters

Parameter Description
page The page number you wish to retrieve
limit The number of items to return in a page
signature Used to guarantee consistency of the data being returned to you. See Data Consistency for more information

Response

OpenWrks always returns paged data in the following format:

Field Type Description
data array The actual data items you have requested
_meta object Key/value information that is not essential to understand the resources returned, but offers additional detail
_links array A collection of links that you can use to navigate the paged data

Categorisation

OpenWrks groups transactions into categories to enable Income and Expenditure assessment. The Standard Financial Statement (SFS) is a landmark development for debt advice in the UK which delivers, for the first time, a universal income and expenditure statement, together with a single set of spending guidelines. The SFS has been used to prioritise the categories we have focused on solving for first.

Standard Categories

These are the high level categories used in the Standard Financial Statement.

Category Description
BENEFITS AND TAX CREDITS Any form of government paid benefits or tax credits e.g. Universal credit
CARE AND HEALTH COSTS Spend associated with looking after you or your family e.g. Childcare
COMMUNICATIONS AND LEISURE Spend associated with TV
COUNCIL TAX / RATES Mandatory payments direct to the council
DEBTS Transactions associated with lending not categorised elsewhere
EARNINGS Salaries and fixed regular income excluding Benefits
FOOD AND HOUSEKEEPING Transactions associated with maintaining your home e.g. Supermarket spend
MORTGAGE Transactions associated with paying your mortgage
OTHER COSTS Any other costs not categorised elsewhere
OTHER INCOME Any other income not categorised elsewhere
PENSIONS AND INSURANCES Transactions associated with pensions and insurances not categorised elsewhere
PERSONAL COSTS Personal discretionary spend not categorised elsewhere e.g. Clothes
RENT Transactions associated with paying your rent
SAVINGS Transactions identified as to or from savings accounts
TRANSPORT AND TRAVEL Transactions associated with using transport e.g. Road tax
UTILITIES Transactions associated with the consumption of utilities e.g. Electricity

OpenWrks Categories

The below OpenWrks categories will be returned as part of the response from the transaction endpoint.

Standard Category OpenWrks Category
BENEFITS AND TAX CREDITS ADOPTION PAY
BENEFITS AND TAX CREDITS ATTENDANCE ALLOWANCE
BENEFITS AND TAX CREDITS BEREAVEMENT ALLOWANCE
BENEFITS AND TAX CREDITS BEREAVEMENT PAYMENT
BENEFITS AND TAX CREDITS CARERS ALLOWANCE
BENEFITS AND TAX CREDITS CHRISTMAS BONUS
BENEFITS AND TAX CREDITS COLD WEATHER PAY
BENEFITS AND TAX CREDITS CONTRIBUTORY ESA
BENEFITS AND TAX CREDITS DISABILITY LIVING ALLOWANCE
BENEFITS AND TAX CREDITS EESA
BENEFITS AND TAX CREDITS ESA
BENEFITS AND TAX CREDITS HOUSING BENEFIT
BENEFITS AND TAX CREDITS INCAPACITY BENEFIT
BENEFITS AND TAX CREDITS INCOME SUPPORT
BENEFITS AND TAX CREDITS INDUSTRIAL INJURIES BENEFIT
BENEFITS AND TAX CREDITS INDUSTRIAL INJURIES DISABLEMENT BENEFIT
BENEFITS AND TAX CREDITS JSA
BENEFITS AND TAX CREDITS MATERNITY ALLOWANCE
BENEFITS AND TAX CREDITS MATERNITY PAY
BENEFITS AND TAX CREDITS PATERNITY PAY
BENEFITS AND TAX CREDITS PENSION CREDIT
BENEFITS AND TAX CREDITS PERSONAL INDEPENDENCE PAYMENTS
BENEFITS AND TAX CREDITS SHARED PARENTAL LEAVE PAYMENTS
BENEFITS AND TAX CREDITS SICK PAY
BENEFITS AND TAX CREDITS TAX CREDITS
BENEFITS AND TAX CREDITS CHILD MAINTENANCE
CARE AND HEALTH COSTS CHILD MAINTENANCE
CARE AND HEALTH COSTS CHILDCARE
CARE AND HEALTH COSTS HEALTH
COMMUNICATIONS AND LEISURE HOME COMMUNICATIONS
COMMUNICATIONS AND LEISURE MOBILE PHONES
COMMUNICATIONS AND LEISURE TV LICENCE
COUNCIL TAX / RATES COUNCIL TAX
DEBTS COURT FINES
DEBTS CREDIT CARD
DEBTS DCA
DEBTS HIRE PURCHASE
DEBTS SECURED LOAN
DEBTS UNSECURED LOAN
EARNINGS SALARY
FOOD AND HOUSEKEEPING GROCERIES
FOOD AND HOUSEKEEPING HOME REPAIRS
MORTGAGE MORTGAGE
OTHER COSTS BANK TRANSFERS
OTHER COSTS TAX
OTHER INCOME BANK REWARDS
OTHER INCOME BANK TRANSFERS
OTHER INCOME BURSERY
OTHER INCOME DIVIDENDS
OTHER INCOME INTEREST
OTHER INCOME OTHER INCOME
OTHER INCOME TAX
PENSIONS AND INSURANCES BUILDING AND CONTENTS INSURANCE
PENSIONS AND INSURANCES HEALTH INSURANCE
PENSIONS AND INSURANCES LIFE INSURANCE
PENSIONS AND INSURANCES PRIVATE PENSION
PENSIONS AND INSURANCES STATE PENSION
PERSONAL COSTS AIRLINES
PERSONAL COSTS BANK CHARGES
PERSONAL COSTS CASH WITHDRAWAL
PERSONAL COSTS CHARITY
PERSONAL COSTS OTHER EXPENDITURE
PERSONAL COSTS PETCARE
PERSONAL COSTS RETURNED CHEQUE OR DD
RENT RENT
SAVINGS SAVINGS
TRANSPORT AND TRAVEL BUSES
TRANSPORT AND TRAVEL CAR INSURANCE
TRANSPORT AND TRAVEL FUEL
TRANSPORT AND TRAVEL MECHANICS
TRANSPORT AND TRAVEL ROAD TAX
TRANSPORT AND TRAVEL TAXI
TRANSPORT AND TRAVEL TOLL ROADS
TRANSPORT AND TRAVEL TRAINS
UTILITIES UTILITIES

Data Consistency

OpenWrks periodically refreshes your customers' transactions. We take care of handling changes to the underlying data you request to ensure that you always receive a consistent data set.

Signature

curl -X GET "https://api.openwrks.com/surface/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68 \
   /accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c \
   /transactions?page=2&limit=1000" \
  -H "Authorization: Bearer 123456789"

The above command returns JSON structured like this:

{
  "data": [],
  "_meta": {
    "totalNumberOfRecords": 3000,
    "totalNumberOfPages": 6,
    "pageNumber": 2,
    "pageSize": 1000,
    "signature": "E3B0C44298FC1C14"
  },
  "_links": [
    {
      "rel": "first",
      "href": "https://api.openwrks.com/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68/accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c/transactions?page=1&limit=1000&signature=E3B0C44298FC1C14"
    },
    {
      "rel": "prev",
      "href": "https://api.openwrks.com/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68/accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c/transactions?page=1&limit=1000&signature=E3B0C44298FC1C14"
    },
    {
      "rel": "next",
      "href": "https://api.openwrks.com/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68/accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c/transactions?page=3&limit=1000&signature=E3B0C44298FC1C14"
    },
    {
      "rel": "last",
      "href": "https://api.openwrks.com/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68/accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c/transactions?page=6&limit=1000&signature=E3B0C44298FC1C14"
    }
  ]
}

To ensure data consistency, a signature parameter is appended to each of the links included in a paged response, and is also included in the meta data. You will not need to change or provide a value for this parameter yourself. If you remove this parameter from a link provided to you, we cannot ensure that the data you are receiving is consistent.

Handling data changes

curl -X GET "https://api.openwrks.com/surface/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68 \
   /accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c \
   /transactions?page=2&limit=1000&signature=E3B0C44298FC1C14" \
  -H "Authorization: Bearer 123456789"

Example Conflict Error Response body:

{
  "message": "The underyling data for this request has changed.",
  "status": 409,
  "errorCode": 3000013,
  "_links": [
    {
      "rel": "first",
      "href": "https://api.openwrks.com/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68/accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c/transactions?page=1&limit=1000&signature=6B86B273FF34FCE1"
    }
  ]
}

On the rare occasion that the signature in a request no longer represents the current state of the data (i.e. the data has changed during paging), you will receive an error response with HTTP status code 409 (Conflict) informing you of this inconsistency, and a link to restart paging at the first page. The link will contain a new signature representing the new state of the data.

Errors

Example Error Response Body

{
  "message": "The specified user does not exist",
  "status": 400,
  "errorCode": 3000001
}

Errors in the OpenWrks API are expressed as a combination of HTTP status codes and an accompanying JSON body providing detail where appropriate. In most cases, you will be able to rely on the HTTP status code alone to determine the cause of the problem.

Error Response Fields

Field Type
message string A human-readable message as to the specifics of the problem. For example, it may contain the value in your request that caused the problem
status number The HTTP status code used in the response
errorCode number The specific OpenWrks error code for the problem. You should provide this value if you have to contact support regarding the problem
_links array A collection of links that may be be useful for re-issuing a failed request, or for performing a new request based on the error

Flow

Flow is our Open Banking connection, authentication and authorisation journey. Quickly add our seamless, fully white labelled and GDPR compliant bank connection flow to any of your existing products or processes.

Requesting consent to view your customer's bank account is simple:

  1. Request a unique invite link from our /invite endpoint
  2. Redirect your customer to the link
  3. Your customer selects their bank and is handed off to them to provide consent
  4. The bank redirects them back to OpenWrks
  5. We'll confirm whether the consent was successful, then redirect your customer back to your redirect URL

Invite

curl -X POST "https://api.openwrks.com/surface/v1/invite" \
 -H "Authorization: Bearer 123456789" \
 -H "Content-Type: application/json" \
 -d '{"customerReference": "LTbhI7AkSe0Nh55Mn6ENrreS22EecgC22w", "redirectUrl": "https://www.test.com/"}'

The above command returns JSON structured like this:

{
  "invitationId": "e919353a-8dd0-4ae6-b9c3-99c49c6e209b",
  "customerReference": "LTbhI7AkSe0Nh55Mn6ENrreS22EecgC22w",
  "userId": "e2301481-4517-4fe0-8273-38ec4f0c12b2",
  "flowUrl": "https://flow.openwrks.com/invite/CfDJ8LNbxiNjlEv0n...",
  "expirationDate": "2018-02-11T13:11:24.1175463+00:00"
}

Example MetaData for request body:

{
  "customerReference": "LTbhI7AkSe0Nh55Mn6ENrreS22EecgC22w",
  "redirectUrl": "https://www.test.com/",
  "metaData": {
    "firstname": "John",
    "surname": "Doe",
    "email": "[email protected]",
    "businessName": "John's Business"
  }
}

The Invite endpoint allows you to generate a unique link for a customer. You can provide additional information such as their name, email and business name. The invite endpoint returns a response object that contains a unique URL for your user to connect through to Flow.

Request Body Fields

Field Type Description
customerReference string A unique string you use to identify your customer
metaData (optional) object Key/value data used to provide further details about your customer to help personalise their journey through Flow
redirectUrl string The URL that you want to redirect the customer back to. The redirectUrl must match the redirectUrl registered for your chosen Flow configuration

Meta Data

The following meta data fields are viewable on your customer's record in the Surface Dashboard when provided via the /invite endpoint:

*businessName will also be displayed on the customer's e-statement - available to download through the Surface Dashboard.

Response Body Fields

Field Type Description
invitationId string A unique identifier for your invitation
customerReference string The customer reference provided as part of the request
userId string A unique identifier for your user
flowUrl string A unique invite URL - provide this to your user so that they can consent to share their account and transaction details
expirationDate datetime The date and time that the flowUrl will no longer be valid

Redirect

Success - redirect query string:

?invitationId=<invitationId>&customerReference=<customerReference>

We'll attempt to fetch and display your customer's consented accounts, if this works correctly we'll redirect back to your provided redirect URL with the following query string

Field Type Description
invitationId string The unique identifier generated for your customer's invite.
customerReference string The unique reference that you provided for this customer in the /invite endpoint

Failure - redirect query string:

?invitationId=<invitationId>&customerReference=<customerReference>&errorCode=<errorCode>

If we receive an error from the bank or something goes wrong when fetching your customer's data, we'll redirect back to your provided redirect URL with an additional errorCode parameter

Error Code Description
bankAuthorisationFailed The user's bank has returned an error during the bank's authentication process.
consentDeclined The user has declined to provide consent to connect to their bank account.
expiredInvite The invite is no longer valid. This can occur when a user has clicked the link (FlowUrl) after completing an activation or the link has expired

Resource Endpoints

Users

Get All Users

curl -X GET "https://api.openwrks.com/surface/v1/users" \
  -H "Authorization: Bearer 123456789"

The above command returns JSON structured like this:

{
  "data": [
    {
      "userId": "50012098-3234-4b25-a13c-e0eecfd46e68",
      "reference": "Reference1234"
    },
    {
      "userId": "0c742c2f-9bdd-4e18-88fd-ad13cb88fd93",
      "reference": "Reference4567"
    }
  ],
  "_meta": {},
  "_links": []
}

This endpoint retrieves all users.

HTTP Request

GET https://api.openwrks.com/surface/v1/users/

Get a Specific User

curl -X GET "https://api.openwrks.com/surface/v1/users/0c742c2f-9bdd-4e18-88fd-ad13cb88fd93" \
  -H "Authorization: Bearer 123456789"

The above command returns JSON structured like this:

{
  "userId": "0c742c2f-9bdd-4e18-88fd-ad13cb88fd93",
  "reference": "Reference4567"
}

This endpoint retrieves a specific user.

HTTP Request

GET https://api.openwrks.com/surface/v1/users/<userId>

URL Parameters

Parameter Description
userId The ID of the user to retrieve

Response Body Fields

Field Type Description
userId string A unique identifier for your user.
reference string The unique Customer Reference that you provided as part of the /invite request

Accounts

Get All Accounts

curl -X GET "https://api.openwrks.com/surface/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68/accounts" \
  -H "Authorization: Bearer 123456789"

The above command returns JSON structured like this:

{
  "data": [
    {
      "accountId": "a54b2ba6-8605-4c07-b5d4-5c384d5a691c",
      "accountNumber": "12345678",
      "sortCode": "889900",
      "accountName": "Current Account",
      "iban": null,
      "provider": "Natwest",
      "balance": 240.85,
      "currency": "GBP",
      "collectedDate": "2018-07-17T12:58:52.2155584+00:00"
    },
    {
      "accountId": "eee5c034-c9fd-4f9f-a08f-ef3225b638a3",
      "accountNumber": "98765432",
      "sortCode": "112233",
      "accountName": "Savings Account",
      "iban": null,
      "provider": "Natwest",
      "balance": 1534.62,
      "currency": "GBP",
      "collectedDate": "2018-07-17T12:58:52.2155584+00:00"
    }
  ],
  "_meta": {},
  "_links": []
}

This endpoint retrieves all accounts.

HTTP Request

GET https://api.openwrks.com/surface/v1/users/<userId>/accounts

URL Parameters

Parameter Description
userId The ID of the user to retrieve

Get a Specific Account

curl -X GET "https://api.openwrks.com/surface/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68 \
  /accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c" \
  -H "Authorization: Bearer 123456789"

The above command returns JSON structured like this:

{
  "accountId": "a54b2ba6-8605-4c07-b5d4-5c384d5a691c",
  "accountNumber": "12345678",
  "sortCode": "889900",
  "accountName": "Current Account",
  "iban": null,
  "provider": "Natwest",
  "balance": 240.85,
  "currency": "GBP",
  "collectedDate": "2018-07-17T12:58:52.2155584+00:00"
}

This endpoint retrieves a specific account.

HTTP Request

GET https://api.openwrks.com/surface/v1/users/<userId>/accounts/<accountId>

URL Parameters

Parameter Description
userId The ID of the user to retrieve
accountId The ID of the account to retrieve

Response Body Fields

Field Type Description
accountId string A unique identifier for the account
accountNumber number (optional) The bank's account number
sortCode number (optional) The bank's sort code
iban string (optional) The bank's International Bank Account Number (only provided when account number and sort code are empty)
accountName string (optional) The name of the account, typically set by the account owner via their bank
provider string The name of the bank that the account is with
balance decimal The balance of the account
currency string A 3 character code that represents the currency
collectedDate datetime The date and time that the account data was retrieved from the bank

Transactions

Get All Transactions

curl -X GET "https://api.openwrks.com/surface/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68 \
  /accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c \
  /transactions" \
  -H "Authorization: Bearer 123456789"

The above command returns JSON structured like this:

{
  "data": [
    {
      "transactionId": "5051b33d-0da0-446d-8ad7-8033f11bc649",
      "amount": -20,
      "description": "1234 14JUL18    UPPER PARLIAMENT ST CD  NOTTS GB",
      "currency": "GBP",
      "merchantName": null,
      "merchantCategoryCode": null,
      "timestamp": "2018-07-15T23:00:00Z",
      "type": "Debit",
      "category": "CASH WITHDRAWAL"
    },
    {
      "transactionId": "741ff373-d824-49ff-8c5d-7b611469121b",
      "amount": -33.14,
      "description": "5678 15JUL18      MORRISONS PETROL  NOTTS GB",
      "currency": "GBP",
      "merchantName": null,
      "merchantCategoryCode": null,
      "timestamp": "2018-07-15T23:00:00Z",
      "type": "Debit",
      "category": "FUEL"
    }
  ],
  "_meta": {},
  "_links": []
}

This endpoint retrieves all transactions.

OpenWrks periodically refreshes your customers' transactions. This means that a TransactionId will change and should not be relied on.

HTTP Request

GET https://api.openwrks.com/surface/v1/users/<userId>/accounts/<accountId>/transactions

URL Parameters

Parameter Description
userId The ID of the user to retrieve
accountId The ID of the account to retrieve
from (optional) The ISO8601 encoded datetime to filter transactions from. The default is the earliest transaction available
to (optional) The ISO8601 encoded datetime to filter transactions to. The default is the date of the request
signature (optional) Used to guarantee consistency of the data being returned to you

The signature is included in the meta data of the response, and is appended to each of the paging links.

Get a Specific Transaction

curl -X GET "https://api.openwrks.com/surface/v1/users/50012098-3234-4b25-a13c-e0eecfd46e68 \
  /accounts/a54b2ba6-8605-4c07-b5d4-5c384d5a691c \
  /transactions/741ff373-d824-49ff-8c5d-7b611469121b" \
  -H "Authorization: Bearer 123456789"

The above command returns JSON structured like this:

{
  "transactionId": "741ff373-d824-49ff-8c5d-7b611469121b",
  "amount": -33.14,
  "description": "5678 15JUL18      MORRISONS PETROL  NOTTS GB",
  "currency": "GBP",
  "merchantName": null,
  "merchantCategoryCode": null,
  "timestamp": "2018-07-15T23:00:00Z",
  "type": "Debit",
  "category": "FUEL"
}

This endpoint retrieves a specific transaction.

OpenWrks periodically refreshes your customers' transactions. This means that a TransactionId will change and should not be relied on.

HTTP Request

GET https://api.openwrks.com/surface/v1/users/<userId>/accounts/<accountId>/transactions/<transactionId>

URL Parameters

Parameter Description
userId The ID of the user to retrieve
accountId The ID of the account to retrieve
transactionId The ID of the transaction to retrieve

Response Body Fields

Field Type Description
transactionId string A unique identifier for the account (does not persist beyond refreshes)
amount decimal The transaction amount (debits will be negative, credits will be positive)
description string (optional) The transaction description provided by the bank
currency string A 3 character code that represents the currency
merchantName string (optional) The merchant name provided by the bank
merchantCategoryCode string (optional) The merchant category code provided by the bank
timestamp datetime The date and time that the transaction occurred. Where no time is provided by the banks, the datetime defaults to midnight of the provided timezone
type string An indication of whether the transaction was a debit or credit
category string The category of the transaction, determined by OpenWrks