Mandates

Create a mandate

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

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"
  }'
post/mandates

Request

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

Request body

principal_person_idstring uuid required

Identifier of the principal (owner or lessee) person.

principal_kind'owner' | 'lessee' required

Kind of principal (the person granting the mandate).

scopeMandateScope[] required

Non-empty list of delegated permissions.

valid_fromstring date required

Start date of validity (ISO 8601).

valid_untilstring date nullable

Optional end date. Must be strictly after valid_from when provided.

Example request

{
  "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"
}

Response

Mandate created (status draft).

idstring uuid required

Unique mandate identifier.

tenant_idstring required

Tenant identifier (multi-tenant isolation).

mandataire_auth_user_idstring required

Auth user ID of the mandataire (extracted from the JWT).

scopeMandateScope[] required

Ordered list of delegated permissions.

valid_fromstring date required

Start date of validity (ISO 8601, YYYY-MM-DD).

valid_untilstring date nullable

End date of validity (ISO 8601). null means no end date. When set, must be strictly after valid_from.

status'draft' | 'active' | 'revoked' | 'expired' required

Lifecycle status of a mandate.

Valid transitions: draft → active, draft → revoked, active → revoked, active → expired.

created_atstring date-time required

Creation timestamp (ISO 8601).

updated_atstring date-time required

Last update timestamp (ISO 8601).

revoked_atstring date-time nullable

Revocation timestamp, or null if not revoked.

revoke_reasonstring nullable

Free-text reason for revocation (max 500 chars), or null.

Example response

{
  "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": "660e8400-e29b-41d4-a716-446655440111"
  },
  "status": "draft",
  "created_at": "2026-01-01T10:00:00Z",
  "updated_at": "2026-01-01T10:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.