Accounts

An account represents a bank account, or virtual wallet of some kind, capable of holding a sum of transactions.

Attribute	Description
name	An account name of your choice.
visibility	One of "PUBLIC", "PRIVATE" or "UNLISTED" - see Discovery.

Relationship	Description
currency	A supported currency for this account.

Meta	Description
externalId	An external ID to tie this account with a resource from your side.
createdAt	The timestamp (UTC) (ISO8601) when the account was created.
updatedAt	The timestamp (UTC) (ISO8601) when the account was updated.

---

List accounts

get

List all accounts.

Authorizations

Query parameters

filter[name]stringOptional

Filter all accounts where the name contains a specific substring.

Example: My Account

filter[visibility]string · enumOptional

Filter all accounts where the currency matches a specific Currency Code.

Default: UNLISTEDExample: PUBLICPossible values:

filter[currency]string · money-currencyOptional

Filter all accounts where the currency matches a specific Currency Code.

Example: USD

filter[externalId]stringOptional

Filter all accounts where the externalId matches a specific string.

Example: cb8ff63f-cb92-4328-b3c7-b54e2b6dbc5f

page[page]integerOptional

Set the page number of resources to return.

Default: 1

page[limit]integer · max: 100Optional

Set the maximum number of resources to return.

Default: 20

Responses

200

List of Accounts

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

500

An error occurred

application/json

get

HTTPcURLJavaScriptPython

GET /accounts HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "type": "accounts",
      "id": "a1b2c3d4e5",
      "attributes": {
        "name": "My Account",
        "visibility": "PUBLIC"
      },
      "relationships": {
        "currency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        }
      },
      "meta": {
        "externalId": "cb8ff63f-cb92-4328-b3c7-b54e2b6dbc5f",
        "balanceTotal": "100.00",
        "createdAt": "2023-07-12T19:00:00.000Z",
        "updatedAt": "2023-07-12T19:00:00.000Z"
      }
    }
  ],
  "meta": {
    "prev": "/resource?page[count]=2&page[limit]=100",
    "next": "/resource?page[count]=4&page[limit]=100",
    "first": "/resource?page[count]=1&page[limit]=100",
    "last": "/resource?page[count]=10&page[limit]=100"
  }
}

---

Create account

post

Create a new account, with a name, visibility & currency. Optionally include an external ID so you can tie this account with a resource from your side. Optionally include an initial transaction to set the opening balance.

Authorizations

Body

Responses

200

Created account

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

404

Resource not found

application/json

500

An error occurred

application/json

post

HTTPcURLJavaScriptPython

POST /accounts HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 319

{
  "data": {
    "type": "accounts",
    "attributes": {
      "name": "My Account",
      "visibility": "PUBLIC"
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currencies",
          "id": "USD"
        }
      },
      "initialBalance": {
        "data": {
          "type": "transactions",
          "attributes": {
            "amount": "100.00",
            "reference": "text"
          }
        }
      }
    },
    "meta": {
      "externalId": "cb8ff63f-cb92-4328-b3c7-b54e2b6dbc5f"
    }
  }
}

{
  "data": {
    "type": "accounts",
    "id": "a1b2c3d4e5",
    "attributes": {
      "name": "My Account",
      "visibility": "PUBLIC"
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currencies",
          "id": "USD"
        }
      },
      "initialTransaction": {
        "data": {
          "type": "transactions",
          "id": "c3d4e5f6g7"
        }
      }
    },
    "meta": {
      "externalId": "cb8ff63f-cb92-4328-b3c7-b54e2b6dbc5f",
      "balanceTotal": "100.00",
      "createdAt": "2023-07-12T19:00:00.000Z",
      "updatedAt": "2023-07-12T19:00:00.000Z"
    }
  }
}

• You cannot change an account's currencyCode once created.

---

Get account by ID

get

Get a specific account by ID.

Authorizations

Path parameters

accountIdstringRequired

Account ID

Example: a1b2c3d4e5

Responses

200

Found account.

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

404

Resource not found

application/json

500

An error occurred

application/json

get

HTTPcURLJavaScriptPython

GET /accounts/{accountId} HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "type": "accounts",
    "id": "a1b2c3d4e5",
    "attributes": {
      "name": "My Account",
      "visibility": "PUBLIC"
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currencies",
          "id": "USD"
        }
      }
    },
    "meta": {
      "externalId": "cb8ff63f-cb92-4328-b3c7-b54e2b6dbc5f",
      "balanceTotal": "100.00",
      "createdAt": "2023-07-12T19:00:00.000Z",
      "updatedAt": "2023-07-12T19:00:00.000Z"
    }
  }
}

---

Update account

patch

Update an account's name, visibility & external ID. You cannot change an account's currency once opened.

Authorizations

Path parameters

accountIdstringRequired

Account ID

Example: a1b2c3d4e5

Body

Responses

200

Updated account

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

404

Resource not found

application/json

500

An error occurred

application/json

patch

HTTPcURLJavaScriptPython

PATCH /accounts/{accountId} HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 146

{
  "data": {
    "type": "accounts",
    "attributes": {
      "name": "My Account",
      "visibility": "PUBLIC"
    },
    "meta": {
      "externalId": "cb8ff63f-cb92-4328-b3c7-b54e2b6dbc5f"
    }
  }
}

{
  "data": {
    "type": "accounts",
    "id": "a1b2c3d4e5",
    "attributes": {
      "name": "My Account",
      "visibility": "PUBLIC"
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currencies",
          "id": "USD"
        }
      }
    },
    "meta": {
      "externalId": "cb8ff63f-cb92-4328-b3c7-b54e2b6dbc5f",
      "balanceTotal": "100.00",
      "createdAt": "2023-07-12T19:00:00.000Z",
      "updatedAt": "2023-07-12T19:00:00.000Z"
    }
  }
}

---

Delete account

delete

Delete an account & all data related to the account. Please note: This may not delete all account & transaction data - other accounts' transactions will retain the account ID. All other attributes will cleared.

Authorizations

Path parameters

accountIdstringRequired

Account ID

Example: a1b2c3d4e5

Header parameters

If-Unmodified-Sincestring · date-time-gmt-stringOptional

A Last-Modified header from a previous response to this endpoint. If the Last Modified date of the resource matches this value, then the resource will be successfully deleted.

Example: Tue, 03 May 2022 10:00:00 GMT

Responses

204

Confirmation the account is deleted.

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

404

Resource not found

application/json

412

Please confirm deletion using `Last-Modified`

application/json

500

An error occurred

application/json

delete

HTTPcURLJavaScriptPython

DELETE /accounts/{accountId} HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

• When deleting an account, you will first receive a 412 Precondition Failed response. You should then take the Last-Modified header included with the error response, set it as the If-Unmodified-Since request header & repeat the request.

  • On successful delete, you'll receive a 204 No Content response.

  • If you receive a 412 Precondition Failed response again, use the new Last-Modified header received & repeat.

---

The root account

The root account for Testbank is special. You can credit your account from the root account to generate a balance to play with, or you can empty your account to the root account to clear your account out.