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
get
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
post
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
get
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
patch
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.
delete
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.

PreviousIntroductionNextTransactions

Last updated