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"

Other query parameters

The list endpoint also supports:

Parameter	Description
filter[origin-type][eq]	Return only holds with the given origin type (card-transaction).
filter[updated-at][gte]	Return only holds updated at or after the given timestamp.
sort	Sort by creation time: created-at (oldest first) or -created-at (newest first).
page[size]	Maximum number of holds to return per page.
page[after] / page[before]	Opaque pagination cursors taken from the links of a paginated response.

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",
  "origin-type": "card-transaction",
  "created-at": "2026-04-15T10:30:00Z",
  "updated-at": "2026-04-16T14:00:00Z",
  "account-transactions": [
    {
      "account-transaction-url": "/v0/bank/transactions/pt.def456",
      "updated-hold-at": "2026-04-16T14:00:00Z"
    }
  ]
}

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-transactions	array	(Optional) Account transactions associated with this hold; each has account-transaction-url and updated-hold-at, the time that transaction updated the hold. Absent until a transaction touches the hold.
origin-type	string	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.