---
title: "List mandates"
method: GET
path: "/mandates"
tags: ["Mandates"]
---

# List mandates

`GET /mandates`

## Request

- Base URL: `https://api.faireplace.com/api`
- URL: `https://api.faireplace.com/api/mandates`
- Auth: HTTP bearer

Lists the mandates visible to the authenticated user, filtered by their role.

## Role filter

The `role` query parameter controls which mandates are returned:
- `mandataire` (default): mandates where the user is the **delegate**
- `principal`: mandates where the user is the **principal** (the person who granted the mandate)

An empty or missing `role` is treated as `mandataire`. Any other value returns `400`.

## Multi-tenant isolation

Mandates are automatically scoped to the `tenant_id` extracted from the JWT.

## Usage Example

```bash
curl -X GET "https://api.faireplace.com/api/mandates?role=mandataire" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**:
```json
[
  {
    "id": "770e8400-e29b-41d4-a716-446655440222",
    "tenant_id": "tenant_123",
    "mandataire_auth_user_id": "user_456",
    "principal": {
      "person_id": "550e8400-e29b-41d4-a716-446655440000",
      "kind": "owner",
      "display_name": "Jean Dupont"
    },
    "scope": ["initiate_signature", "sign_on_behalf"],
    "valid_from": "2026-01-01",
    "valid_until": "2026-12-31",
    "mandate_document": { "media_id": null, "signed": false },
    "status": "draft",
    "created_at": "2026-01-01T10:00:00Z",
    "updated_at": "2026-01-01T10:00:00Z",
    "revoked_at": null,
    "revoke_reason": null
  }
]
```

## Query parameters

- `role` 'mandataire' | 'principal'

## Response `200`

List of mandates (empty array if none).

- Mandate[]
  - `id` string, uuid, required: Unique mandate identifier.
  - `tenant_id` string, required: Tenant identifier (multi-tenant isolation).
  - `mandataire_auth_user_id` string, required: Auth user ID of the mandataire (extracted from the JWT).
  - `principal` PrincipalDto, required: The principal (person) on whose behalf the mandate is held.
    - `person_id` string, uuid, required: Identifier of the principal person (owner or lessee).
    - `kind` 'owner' | 'lessee', required: Kind of principal (the person granting the mandate).
    - `display_name` string, required: Display name of the principal. On creation this is a placeholder (`(à charger)`) until the principal details are loaded.
  - `scope` MandateScope[], required: Ordered list of delegated permissions.
  - `valid_from` string, date, required: Start date of validity (ISO 8601, `YYYY-MM-DD`).
  - `valid_until` string, date, nullable: End date of validity (ISO 8601). `null` means no end date. When set, must be strictly after `valid_from`.
  - `mandate_document` MandateDocumentDto, required: The document backing the mandate.
    - `media_id` string, uuid, nullable: Identifier of the attached media (the signed mandate document).
    - `signed` boolean, required: Whether the mandate document has been signed.
  - `status` 'draft' | 'active' | 'revoked' | 'expired', required: Lifecycle status of a mandate. Valid transitions: `draft → active`, `draft → revoked`, `active → revoked`, `active → expired`.
  - `created_at` string, date-time, required: Creation timestamp (ISO 8601).
  - `updated_at` string, date-time, required: Last update timestamp (ISO 8601).
  - `revoked_at` string, date-time, nullable: Revocation timestamp, or `null` if not revoked.
  - `revoke_reason` string, nullable: Free-text reason for revocation (max 500 chars), or `null`.

## Other responses

- `400`: Invalid `role` value.
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

---

[API](https://skmtc.dev/faireplace/apis/faireplace-property-management-api.md) · [All operations](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/revisions/69de39762919?raw)