# Request to create a new hold on a financial account

## Parameters

### financial_account_token
- **Type:** uuid  
- **Required:** Yes  
- **Description:** Globally unique identifier for the financial account.

### amount
- **Type:** integer  
- **Required:** Yes  
- **Constraints:** ≥ 1  
- **Description:** Amount to hold in cents.

### memo
- **Type:** string | null  
- **Description:** Reason for the hold.

### token
- **Type:** uuid  
- **Description:** Customer-provided token for idempotency. Becomes the hold token.

### expiration_datetime
- **Type:** date-time  
- **Description:** When the hold should auto-expire.

### user_defined_id
- **Type:** string  
- **Description:** User-provided identifier for the hold.

## Response Codes

### 201 Created
- **Type:** object  
- **Description:** Base class for all transaction types in the ledger service.

#### Properties
- **status**
  - **Type:** string  
  - **Enum:** `PENDING`, `SETTLED`, `EXPIRED`, `VOIDED`
- **token**
  - **Type:** uuid  
  - **Required:** Yes  
  - **Description:** Unique identifier for the transaction.
- **created**
  - **Type:** date-time  
  - **Required:** Yes  
  - **Description:** ISO 8601 timestamp of when the transaction was created.
- **updated**
  - **Type:** date-time  
  - **Required:** Yes  
  - **Description:** ISO 8601 timestamp of when the transaction was last updated.
- **family**
  - **Type:** enum  
  - **Required:** Yes  
  - **Const:** `HOLD` - Hold Transaction
- **result**
  - **Type:** enum  
  - **Required:** Yes  
  - **Enum:** `APPROVED`, `DECLINED`
- **financial_account_token**
  - **Type:** uuid  
  - **Required:** Yes  
- **pending_amount**
  - **Type:** integer  
  - **Required:** Yes  
  - **Description:** Current pending amount (0 when resolved).
- **currency**
  - **Type:** string  
  - **Required:** Yes  
- **events**
  - **Type:** array of objects  
  - **Required:** Yes

### Events

- **Type:** object  
- **Description:** Event representing a lifecycle change to a hold.

#### Properties
- **token**
  - **Type:** uuid  
  - **Required:** Yes  
- **type**
  - **Type:** string  
  - **Enum:** `HOLD_INITIATED`, `HOLD_VOIDED`, `HOLD_EXPIRED`, `HOLD_SETTLED`  
  - **Required:** Yes  
- **result**
  - **Type:** string  
  - **Enum:** `APPROVED`, `DECLINED`  
  - **Required:** Yes  
- **detailed_results**
  - **Type:** array of objects  
  - **Required:** Yes  
- **amount**
  - **Type:** integer  
  - **Required:** Yes  
  - **Description:** Amount in cents.
- **created**
  - **Type:** date-time  
  - **Required:** Yes  
- **memo**
  - **Type:** string | null  
- **settling_transaction_token**
  - **Type:** uuid | null  
- **user_defined_id**
  - **Type:** string | null  
- **expiration_datetime**
  - **Type:** date-time | null

## Example Request

```bash
curl --request POST \
     --url https://sandbox.lithic.com/v1/financial_accounts/financial_account_token/holds \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "amount": 0,
  "memo": "string",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "expiration_datetime": "2026-07-18T00:25:35.898Z",
  "user_defined_id": "string"
}'
```

## Example Response

```json
{
  "status": "PENDING",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created": "2026-07-18T00:25:35.898Z",
  "updated": "2026-07-18T00:25:35.898Z",
  "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:35.898Z",
      "memo": "string",
      "settling_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "user_defined_id": "string",
  "expiration_datetime": "2026-07-18T00:25:35.898Z"
}
```