# Hold Token

## uuid
**required**  
Globally unique identifier for the hold.

## Response Structure
### `200 OK`
**object**  
Base class for all transaction types in the ledger service

- **status**  
  - `string`  
  - **enum**  
  - **required**  
  - Status of a hold transaction  
  - Options: `PENDING`, `SETTLED`, `EXPIRED`, `VOIDED`

- **token**  
  - `uuid`  
  - **required**  
  - Unique identifier for the transaction

- **created**  
  - `date-time`  
  - **required**  
  - ISO 8601 timestamp of when the transaction was created

- **updated**  
  - `date-time`  
  - **required**  
  - ISO 8601 timestamp of when the transaction was last updated

- **family**  
  - **const**  
  - **enum**  
  - **required**  
  - HOLD - Hold Transaction  
  - Value: `HOLD`

- **result**  
  - `string`  
  - **enum**  
  - **required**  
  - Options: `APPROVED`, `DECLINED`

- **financial_account_token**  
  - `uuid`  
  - **required**

- **pending_amount**  
  - `integer`  
  - **required**  
  - Current pending amount (0 when resolved)

- **currency**  
  - `string`  
  - **required**

- **events**  
  - `array of objects`  
  - **required**

#### Events Object
- **events**  
  - `object`  
  - Event representing a lifecycle change to a hold  
  - Properties:
    - **token**  
      - `uuid`  
      - **required**  
    - **type**  
      - `string`  
      - **enum**  
      - **required**  
      - Type of hold lifecycle event: `HOLD_INITIATED`, `HOLD_VOIDED`, `HOLD_EXPIRED`, `HOLD_SETTLED`
    - **result**  
      - `string`  
      - **enum**  
      - **required**  
      - Options: `APPROVED`, `DECLINED`
    - **detailed_results**  
      - `array of objects`  
      - **required**  
      - Options: `APPROVED`, `INSUFFICIENT_FUNDS`
    - **amount**  
      - `integer`  
      - **required**  
      - Amount in cents
    - **created**  
      - `date-time`  
      - **required**  
    - **memo**  
      - `string | null`  
      - **required**  
    - **settling_transaction_token**  
      - `uuid | null`  
      - **required**  
      - Transaction token of the payment that settled this hold (only populated for HOLD_SETTLED events)
    - **user_defined_id**  
      - `string | null`  
      - **required**  
    - **expiration_datetime**  
      - `date-time | null`  
      - **required**  
      - When the hold will auto-expire if not resolved.

## Error Handling
### `400` Bad Request  
A parameter in the query given in the request does not match the valid queries for the endpoint.

### `401` Unauthorized  
User has not been authenticated due to:
- Invalid or missing API key.
- API key is not active.
- Could not find API key associated with any user.
- Authorization header is not formatted properly.
- Insufficient privileges. Issuing API key required.

### `404` Not Found  
The specified resource was not found.

### `429` Too Many Requests  
Client has exceeded the number of allowed requests in a given time period.
- Rate limited, user has exceeded their per second or daily rate limit.

## Example Request
```bash
curl --request GET \
     --url https://sandbox.lithic.com/v1/holds/hold_token \
     --header 'accept: application/json'
```

## Example Response
```json
{
  "status": "PENDING",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created": "2026-07-18T00:25:36.012Z",
  "updated": "2026-07-18T00:25:36.012Z",
  "family": "string",
  "result": "APPROVED",
  "financial_account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "pending_amount": 0,
  "currency": "string",
  "events": [
    {
      "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "HOLD_INITIATED",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "amount": 0,
      "created": "2026-07-18T00:25:36.012Z",
      "memo": "string",
      "settling_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "user_defined_id": "string",
  "expiration_datetime": "2026-07-18T00:25:36.012Z"
}
```