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.
released	The hold is no longer reducing the available balance. Reached when the hold is resolved by a transaction (e.g. a card clearing), explicitly released, or automatically released on expiry.

Once a hold moves to 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",
      "status": "placed",
      "amount": {
        "currency": "GBP",
        "value": "25.00"
      },
      "direction": "debit",
      "created-at": "2026-04-15T10:30:00Z",
      "updated-at": "2026-04-15T10:30:00Z",
      "expires-at": "2026-04-22T10:30:00Z",
      "origin-type": "card-transaction",
      "origin-metadata": {
        "some-id": "abc-123",
        "some-customer-reference": "xyz-789"
      }
    }
  ],
  "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][]=released" \
  -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",
  "status": "released",
  "amount": {
    "currency": "GBP",
    "value": "25.00"
  },
  "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.
status	string	One of placed or released.
amount	object	The reserved amount, with currency and value.
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 it is still placed.
account-transaction-url	string	(Optional) URL of the transaction that resolved this hold, when applicable.
origin-type	string	(Optional) The type of activity that created the hold, e.g. card-transaction.
origin-metadata	object	(Optional) Identifiers from the system that originated the hold. Contents are originator-specific.

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 is resolved by one or more transactions.

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