---
title: "Create a mandate"
method: POST
path: "/mandates"
tags: ["Mandates"]
---

# Create a mandate

`POST /mandates`

## Request

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

Creates a new mandate in `draft` status.

The `tenant_id` and `mandataire_auth_user_id` are derived from the JWT and
must not be supplied in the body.

## Validations

- `principal_kind` must be `owner` or `lessee`
- `scope` must be a non-empty array of valid scope values
- `valid_until`, when present, must be strictly after `valid_from`

## Usage Example

```bash
curl -X POST https://api.faireplace.com/api/mandates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_person_id": "550e8400-e29b-41d4-a716-446655440000",
    "principal_kind": "owner",
    "scope": ["initiate_signature", "sign_on_behalf"],
    "valid_from": "2026-01-01",
    "valid_until": "2026-12-31"
  }'
```

## Request body

- CreateMandateRequest: Request to create a new mandate. The created mandate starts in `draft` status. The `tenant_id` and `mandataire_auth_user_id` are derived from the JWT, never from the body.
  - `principal_person_id` string, uuid, required: Identifier of the principal (owner or lessee) person.
  - `principal_kind` 'owner' | 'lessee', required: Kind of principal (the person granting the mandate).
  - `scope` MandateScope[], required: Non-empty list of delegated permissions.
  - `valid_from` string, date, required: Start date of validity (ISO 8601).
  - `valid_until` string, date, nullable: Optional end date. Must be strictly after `valid_from` when provided.

## Response `201`

Mandate created (status `draft`).

- Mandate: A mandate delegating one or more permissions from a principal (owner or lessee) to a mandataire (the authenticated user). A mandate becomes `active` once a signed document is attached and it is within its validity window.
  - `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`: Validation error (invalid `principal_kind`, empty/unknown `scope`, or `valid_until` not after `valid_from`).
- `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)