---
title: "Read one escrow"
method: GET
path: "/escrow/{escrowId}"
tags: ["escrow"]
---

# Read one escrow

`GET /escrow/{escrowId}`

## Request

- The document declares no server URL.
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/hevn-inc/apis/hevn-api/docs/escrow/:escrowId/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve one escrow, its current balances, deadlines, available actions and last reconciled chain state.

## Path parameters

- `escrowId` string, required

## Headers

- `X-Hevn-Account` string, nullable: The client account to act for, as a `cl_…` id. Omit it to act as yourself.

## Response `200`

Successful Response

- EscrowView
  - `id` string, required: Stable public identifier for this escrow.
  - `status` 'draft' | 'authorized' | 'charged' | 'partiallyCaptured' | 'captured' | 'voided' | 'reclaimed' | 'partiallyRefunded' | 'refunded', required
  - `availableActions` EscrowAction[], required: Actions permitted by current state and deadlines.
  - `sender` EscrowPartyView, required
    - `clientId` string, required: Account represented by this escrow party.
  - `receiver` EscrowPartyView, required
    - `clientId` string, required: Account represented by this escrow party.
  - `onchainEscrowUrl` string, required: Block explorer URL for the shared escrow contract.
  - `description` string, nullable: Off-chain escrow description.
  - `completionConditions` string, nullable: Off-chain conditions reviewed before capture.
  - `token` string, required: Digital asset held in escrow.
  - `maxAmount` string, required: Maximum token amount that may be authorized.
  - `authorizedAmount` string, required: Token amount currently authorized for capture.
  - `capturableAmount` string, required: Token amount that may currently be captured.
  - `refundableAmount` string, required: Token amount that may currently be refunded.
  - `windows` EscrowWindowsView, required
    - `approveBy` string, date-time, required: UTC deadline for escrow approval.
    - `holdUntil` string, date-time, required: UTC timestamp until which captured funds remain held.
    - `refundableUntil` string, date-time, required: UTC deadline for a refund.
  - `action` EscrowActionView
    - `action` 'approve' | 'authorize' | 'charge' | 'capture' | 'reject' | 'void' | 'reclaim' | 'refund', required
    - `idempotencyKey` string, required: Key that binds retries to the prepared action.
    - `status` 'awaitingSignature' | 'signing' | 'submitted' | 'confirmed' | 'reverted' | 'failed' | 'superseded' | 'dropped', required
    - `amount` string, nullable: Token amount affected by the action.
    - `feeBps` integer, nullable: Variable fee in basis points, when charged.
    - `transactionHash` string, nullable: On-chain transaction hash, when broadcast.
    - `approval` EscrowApprovalView
      - `id` string, uuid, required: Single-use approval identifier.
      - `payload` string, required: Base64 canonical authorization payload to sign with the developer key.
      - `expiresAt` string, date-time, required: UTC timestamp after which this approval is refused.
  - `consistent` boolean, nullable: Whether persisted state matches the latest chain state.
  - `createdAt` string, date-time, required: UTC timestamp when the escrow was created.
  - `updatedAt` string, date-time, required: UTC timestamp when the escrow was last updated.

## Other responses

- `422`: Request validation failed

## Changes

- **2026-11-12** `299a3aa6f521`: 1 warning, 2 info
  - added the new `verification_not_applicable` enum value to the `error/code` response property for the response status `422`
  - removed the `phone_required` enum value from the `error/code` response property for the response status `422`
  - removed the `rail_requirements_unmet` enum value from the `error/code` response property for the response status `422`
- **2026-10-23** `a02795de2d2b`: 9 warning, 8 info
  - deleted the `header` request parameter `x-api-key`
  - added the new `client_already_linked` enum value to the `error/code` response property for the response status `422`
  - added the new `kyb_documents_processing` enum value to the `error/code` response property for the response status `422`
  - added the new `link_code_expired` enum value to the `error/code` response property for the response status `422`
  - …13 more
- **2026-10-20** `19eb00e9f258`: 1 info
  - removed the `phone_in_use` enum value from the `error/code` response property for the response status `422`
- **2026-10-20** `bd6c9d69540e`: 1 warning
  - added the new `phone_in_use` enum value to the `error/code` response property for the response status `422`
- **2026-10-20** `19eb00e9f258`: 1 info
  - removed the `document_fields_missing` enum value from the `error/code` response property for the response status `422`

[Operation history](https://skmtc.dev/hevn-inc/apis/hevn-api/changes/escrow/:escrowId/get.md)

---

[API](https://skmtc.dev/hevn-inc/apis/hevn-api.md) - [All operations](https://skmtc.dev/hevn-inc/apis/hevn-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hevn-inc/apis/hevn-api/revisions/299a3aa6f521?raw)