Holds

A hold is a temporary reservation of funds on a bank account. Holds are placed when a transaction is pending — for example, a card authorisation — and reduce the account's available balance without affecting the account balance.

You can use the holds API to list and inspect holds on an account. Holds are managed by the system and cannot be created or modified through the API.

Hold lifecycle

Every hold has a status indicating where it is in its lifecycle:

Status	Description
placed	The hold is active and reducing the available balance.
settled	The hold has been consumed by a completed transaction. The response includes an account-transaction-url linking to the settling transaction.
released	The hold was cancelled — either because it expired or was explicitly released.

Once a hold moves to settled or released, it no longer affects the available balance.

List holds on an account

To list all holds on a bank account:

Request

curl "https://api.griffin.com/v0/bank/accounts/{account-id}/holds" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

Response

{
  "holds": [
    {
      "hold-url": "/v0/bank/holds/ho.abc123",
      "account-url": "/v0/bank/accounts/ba.xyz789",
      "hold-status": "placed",
      "hold-amount": {
        "currency": "GBP",
        "value": "25.00"
      },
      "hold-direction": "debit",
      "created-at": "2026-04-15T10:30:00Z",
      "updated-at": "2026-04-15T10:30:00Z",
      "expires-at": "2026-04-22T10:30:00Z",
      "hold-origin-type": "card-transaction",
      "hold-origin-reference": "ref-12345"
    }
  ],
  "links": {
    "prev": null,
    "next": null
  }
}

Filtering by status

You can filter holds by status using the filter[status][in][] query parameter. For example, to list only active holds:

curl "https://api.griffin.com/v0/bank/accounts/{account-id}/holds?filter[status][in][]=placed" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

You can include multiple statuses:

curl "https://api.griffin.com/v0/bank/accounts/{account-id}/holds?filter[status][in][]=placed&filter[status][in][]=settled" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

Get a hold

To retrieve a specific hold:

Request

curl "https://api.griffin.com/v0/bank/holds/{hold-id}" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

Response

{
  "hold-url": "/v0/bank/holds/ho.abc123",
  "account-url": "/v0/bank/accounts/ba.xyz789",
  "hold-status": "settled",
  "hold-amount": {
    "currency": "GBP",
    "value": "25.00"
  },
  "hold-direction": "debit",
  "created-at": "2026-04-15T10:30:00Z",
  "updated-at": "2026-04-16T14:00:00Z",
  "account-transaction-url": "/v0/bank/transactions/pt.def456"
}

Response fields

Field	Type	Description
hold-url	string	URL of this hold.
account-url	string	URL of the bank account the hold is placed on.
hold-status	string	One of placed, settled, or released.
hold-amount	object	The reserved amount, with currency and value.
hold-direction	string	debit or credit.
created-at	string	Timestamp when the hold was placed.
updated-at	string	Timestamp when the hold last changed state.
expires-at	string	(Optional) When the hold will automatically release if not settled.
account-transaction-url	string	(Optional) URL of the transaction that settled this hold. Present only on settled holds.
hold-origin-type	string	(Optional) The type of activity that created the hold, e.g. card-transaction.
hold-origin-reference	string	(Optional) An external reference identifier for the originating activity.

How holds affect balances

When a hold is placed, its amount is subtracted from the account's available balance. The account balance is unaffected until the hold settles into a transaction.

Multiple holds can be active on the same account simultaneously — their amounts accumulate. When a hold is settled or released, it stops affecting the available balance.