> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dhmad.tn/llms.txt
> Use this file to discover all available pages before exploring further.

# List Escrows

> Get a paginated list of escrows

<Endpoint method="GET" path="/api/v1/escrows" />

Get a paginated list of escrows for the authenticated user. You can filter by status and role.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://dhmad.tn/api/v1/escrows?status=pending&role=seller&page=1&limit=20" \
    -H "Authorization: Bearer sk_live_your_api_key_here" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://dhmad.tn/api/v1/escrows?status=pending&role=seller&page=1&limit=20', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key_here',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer sk_live_your_api_key_here',
      'Content-Type': 'application/json'
  }

  params = {
      'status': 'pending',
      'role': 'seller',
      'page': 1,
      'limit': 20
  }

  response = requests.get(
      'https://dhmad.tn/api/v1/escrows',
      params=params,
      headers=headers
  )

  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "escrows": [
      {
        "id": "507f1f77bcf86cd799439011",
        "title": "Web Development Service",
        "amount": 1000.00,
        "escrowFee": 50.00,
        "status": "pending",
        "seller": {
          "_id": "507f1f77bcf86cd799439013",
          "email": "seller@example.com",
          "firstName": "John",
          "lastName": "Doe"
        },
        "buyer": null,
        "estimatedDeliveryDays": 7,
        "paidAt": null,
        "deliveredAt": null,
        "completedAt": null,
        "cancelledAt": null,
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    }
  }
  ```
</ResponseExample>

## Query Parameters

<ParamField query="status" type="string">
  Filter by status: `pending`, `paid`, `delivered`, `completed`, `cancelled`
</ParamField>

<ParamField query="role" type="string">
  Filter by role: `seller` or `buyer`. If not specified, returns escrows where you are either seller or buyer.
</ParamField>

<ParamField query="page" type="number">
  Page number (default: 1)
</ParamField>

<ParamField query="limit" type="number">
  Items per page (default: 20, max: 100)
</ParamField>

## Response Fields

<ParamField response="escrows" type="array">
  Array of escrow objects
</ParamField>

<ParamField response="escrows[].id" type="string">
  Unique identifier for the escrow
</ParamField>

<ParamField response="escrows[].title" type="string">
  Escrow title
</ParamField>

<ParamField response="escrows[].amount" type="number">
  Transaction amount in TND
</ParamField>

<ParamField response="escrows[].escrowFee" type="number">
  Escrow fee
</ParamField>

<ParamField response="escrows[].status" type="string">
  Current escrow status
</ParamField>

<ParamField response="escrows[].mode" type="string">
  Escrow mode: `standard`, `quick`, or `instant`. See [Escrow Modes](/api-reference/escrows/overview#escrow-modes).
</ParamField>

<ParamField response="escrows[].seller" type="object">
  Seller user object with \_id, email, firstName, lastName
</ParamField>

<ParamField response="escrows[].buyer" type="object|null">
  Buyer user object if buyer exists, otherwise `null`
</ParamField>

<ParamField response="pagination.page" type="number">
  Current page number
</ParamField>

<ParamField response="pagination.limit" type="number">
  Items per page
</ParamField>

<ParamField response="pagination.total" type="number">
  Total number of escrows matching the filters
</ParamField>

<ParamField response="pagination.pages" type="number">
  Total number of pages
</ParamField>

## Examples

### Filter by Status

```bash theme={null}
GET /api/v1/escrows?status=paid
```

Returns only escrows with `paid` status.

### Filter by Role

```bash theme={null}
GET /api/v1/escrows?role=seller
```

Returns only escrows where you are the seller.

### Combined Filters

```bash theme={null}
GET /api/v1/escrows?status=pending&role=buyer&page=1&limit=10
```

Returns pending escrows where you are the buyer, first page with 10 items per page.

***

<Info>
  If no filters are provided, the endpoint returns all escrows where you are either the seller or buyer, sorted by creation date (newest first).
</Info>