FairePlace Owners API

openapi: 3.2.0
info:
  title: FairePlace Property Management Owners API
  description: 'Comprehensive API for managing properties, leases, tenants, and all aspects of real estate management.

    Built with Rust and Actix-web following hexagonal architecture principles.


    ## Authentication

    This API uses API keys for authentication with tenant-based isolation.


    ## Base URL

    - Production: `https://api.faireplace.com/api`'
  version: 1.0.0
  contact:
    name: FairePlace API Support
    email: api-support@faireplace.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.faireplace.com/api
  description: Production server
security:
- BearerAuth: []
tags:
- name: Owners
  description: Owner management
paths:
  /owners:
    get:
      operationId: listOwners
      summary: List owners
      tags:
      - Owners
      security:
      - BearerAuth: []
      parameters:
      - name: search
        in: query
        required: false
        description: Free-text search over last name, first name, legal name, email and phone numbers.
        schema:
          type: string
      - name: email
        in: query
        required: false
        description: Exact match.
        schema:
          type: string
      - name: first_name
        in: query
        required: false
        description: Partial match, case-insensitive.
        schema:
          type: string
      - name: last_name
        in: query
        required: false
        description: Partial match, case-insensitive.
        schema:
          type: string
      - name: legal_name
        in: query
        required: false
        description: Partial match on the company name.
        schema:
          type: string
      - name: registration_number
        in: query
        required: false
        description: SIRET or equivalent.
        schema:
          type: string
      - name: mobile_phone
        in: query
        required: false
        description: Normalised before matching.
        schema:
          type: string
      - name: landline_phone
        in: query
        required: false
        description: Normalised before matching.
        schema:
          type: string
      - name: owner_category
        in: query
        required: false
        description: individual, sc/sci or company.
        schema:
          type: string
      - name: city
        in: query
        required: false
        schema:
          type: string
      - name: postal_code
        in: query
        required: false
        schema:
          type: string
      - name: country
        in: query
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/SortBy'
      - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Owner'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createOwner
      summary: Create owner
      tags:
      - Owners
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOwner'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Owner'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /owners/{id}:
    get:
      operationId: getOwner
      summary: Get owner
      tags:
      - Owners
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Owner'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: updateOwner
      summary: Update owner
      tags:
      - Owners
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOwner'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Owner'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteOwner
      summary: Delete owner
      tags:
      - Owners
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /owners/bulk:
    delete:
      operationId: deleteOwnersBulk
      summary: Delete owners in bulk
      tags:
      - Owners
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                format: uuid
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /owners/places/{id}/owner:
    get:
      operationId: getOwnerPlace
      summary: Get owner by place
      tags:
      - Owners
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Owner'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /owners/estates/{id}/owner:
    get:
      operationId: getOwnerEstate
      summary: Get owner by estate
      tags:
      - Owners
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Owner'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /owners/{owner_id}/claim/start:
    post:
      operationId: startOwnerClaim
      summary: Start an owner claim
      description: 'Starts an owner-claim workflow for the given `owner_id`. The backend

        generates a token, persists the claim session, and the targeted owner

        receives an email containing the confirmation link.


        ## Authentication

        This endpoint **requires authentication** (Bearer JWT, `properties:write`

        permission): it modifies the account ↔ owner association. The initiator

        identity (auth user id + email) and tenant are taken from the JWT.


        The claim TTL defaults to 7 days (168 hours).


        ## Example

        ```bash

        curl -X POST https://api.faireplace.com/api/owners/550e8400-e29b-41d4-a716-446655440000/claim/start \

        -H "Authorization: Bearer YOUR_API_KEY"

        ```


        **Response** (`201 Created`):

        ```json

        {

        "frontend_url": "https://app.faireplace.com/owner-claim/3f8b1c2d-...-9a0e",

        "owner_email": "owner@example.com"

        }

        ```'
      tags:
      - Owners
      security:
      - BearerAuth: []
      parameters:
      - name: owner_id
        in: path
        required: true
        description: Identifier of the owner to start a claim for.
        schema:
          type: string
          format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '201':
          description: Claim started; the link has been issued for the owner.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartOwnerClaimResponse'
              example:
                frontend_url: https://app.faireplace.com/owner-claim/3f8b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d
                owner_email: owner@example.com
        '400':
          description: Validation error (e.g. invalid owner_id or claim parameters).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerClaimError'
              example:
                error_code: OWNER_CLAIM_VALIDATION
                message: Requête invalide.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The authenticated user is not allowed to start a claim for this owner (generic message).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerClaimError'
              example:
                error_code: OWNER_CLAIM_FORBIDDEN
                message: Vous n'êtes pas autorisé à effectuer cette action.
        '404':
          description: Owner not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerClaimError'
              example:
                error_code: OWNER_CLAIM_NOT_FOUND
                message: Demande introuvable.
        '409':
          description: 'Conflict: the owner has already been claimed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerClaimError'
              example:
                error_code: OWNER_CLAIM_CONFLICT
                message: Cet owner a déjà été revendiqué.
        '500':
          description: Internal error (no infra details leaked).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerClaimError'
              example:
                error_code: OWNER_CLAIM_INTERNAL
                message: Une erreur est survenue, veuillez réessayer.
        '502':
          description: Downstream notifier/service unavailable (email could not be dispatched).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerClaimError'
              example:
                error_code: OWNER_CLAIM_NOTIFIER_DOWN
                message: Service temporairement indisponible.
components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Rows per page. Defaults to 50.
      schema:
        type: integer
        minimum: 1
        default: 50
    SortBy:
      name: sort_by
      in: query
      required: false
      description: Field to sort on (`created_at`, `last_name`, `email`, …).
      schema:
        type: string
    SortOrder:
      name: sort_order
      in: query
      required: false
      schema:
        type: string
        enum:
        - asc
        - desc
    Page:
      name: page
      in: query
      required: false
      description: Zero-based page index. The first page is `0`.
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    CreateOwner:
      type: object
      required:
      - last_name
      - owner_category
      - email
      properties:
        title:
          type: string
          maxLength: 10
        last_name:
          type: string
          maxLength: 255
        first_name:
          type:
          - string
          - 'null'
          maxLength: 255
        owner_category:
          type: string
          enum:
          - individual
          - company
          - sc/sci
        legal_name:
          type:
          - string
          - 'null'
          maxLength: 255
        registration_number:
          type:
          - string
          - 'null'
          maxLength: 50
        country:
          type: string
          maxLength: 50
        address_complement:
          type:
          - string
          - 'null'
          maxLength: 255
        street_number:
          type:
          - string
          - 'null'
          maxLength: 50
        street_name:
          type: string
          maxLength: 255
        locality:
          type:
          - string
          - 'null'
          maxLength: 255
        postal_code:
          type: string
          maxLength: 20
        city:
          type: string
          maxLength: 255
        postal_box:
          type:
          - string
          - 'null'
          maxLength: 20
        mobile_phone:
          type: string
          maxLength: 20
        landline_phone:
          type:
          - string
          - 'null'
          maxLength: 20
        email:
          type: string
          format: email
        auth_user_id:
          type:
          - string
          - 'null'
      oneOf:
      - title: Individual owner
        properties:
          owner_category:
            type: string
            enum:
            - individual
      - title: Company or SC/SCI owner
        allOf:
        - properties:
            owner_category:
              type: string
              enum:
              - company
              - sc/sci
        - required:
          - legal_name
          - registration_number
    Error:
      type: object
      description: "The error envelope returned by every authenticated endpoint.\n\nTwo things are worth knowing before you write your error handling:\n\n- **`code` is a symbolic string, not a number.** The numeric HTTP status is\n  in `status`. Branch on `code`: it is stable, and show `message`, which\n  is written for humans and may be reworded without notice.\n- The public guest-signature endpoints use a **different, flatter shape**\n  (`{ \"error_code\": …, \"message\": … }`, no `error` wrapper), because they\n  are consumed by a page that has no session. Their responses document it\n  inline.\n\nThe `X-Request-Id` response header carries the request identifier: quote it\nwhen reporting a problem. It is a header, not a body field.\n"
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - status
          properties:
            code:
              type: string
              description: Stable symbolic code. Branch on this.
              enum:
              - NOT_FOUND
              - UNAUTHORIZED
              - VALIDATION_ERROR
              - DATABASE_ERROR
              - BUSINESS_ERROR
              - STORAGE_ERROR
              - CONFIG_ERROR
              - FORBIDDEN
              - CONFLICT
              - PARSE_ERROR
              - SERIALIZATION_ERROR
              - AUTHENTICATION_ERROR
              - AUTHORIZATION_ERROR
              - EXTERNAL_SERVICE_ERROR
              - RATE_LIMIT_EXCEEDED
              - PAYMENT_REQUIRED
              - PLAN_LIMIT_REACHED
              - GONE
              - BAD_REQUEST
              - INTERNAL_ERROR
              - INTERNAL_SERVER_ERROR
              example: NOT_FOUND
            message:
              type: string
              description: 'Human-readable explanation, most often in French. Safe to display,

                not safe to parse.

                '
              example: Lease not found
            status:
              type: integer
              description: The HTTP status code, repeated in the body.
              example: 404
            details:
              type: object
              additionalProperties: true
              description: 'Extra machine-readable context. Only present on some errors: on

                `RATE_LIMIT_EXCEEDED` it carries `retry_after_seconds`.

                '
              example:
                retry_after_seconds: 12
    Owner:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          format: uuid
        title:
          type:
          - string
          - 'null'
          maxLength: 10
        last_name:
          type:
          - string
          - 'null'
        first_name:
          type:
          - string
          - 'null'
          maxLength: 255
        owner_category:
          type:
          - string
          - 'null'
          enum:
          - individual
          - company
          - sc/sci
          - null
        legal_name:
          type:
          - string
          - 'null'
          maxLength: 255
        registration_number:
          type:
          - string
          - 'null'
          maxLength: 50
        country:
          type:
          - string
          - 'null'
          maxLength: 50
        address_complement:
          type:
          - string
          - 'null'
          maxLength: 255
        street_number:
          type:
          - string
          - 'null'
          maxLength: 50
        street_name:
          type:
          - string
          - 'null'
          maxLength: 255
        locality:
          type:
          - string
          - 'null'
          maxLength: 255
        postal_code:
          type:
          - string
          - 'null'
          maxLength: 20
        city:
          type:
          - string
          - 'null'
          maxLength: 255
        postal_box:
          type:
          - string
          - 'null'
          maxLength: 20
        mobile_phone:
          type:
          - string
          - 'null'
          maxLength: 20
        landline_phone:
          type:
          - string
          - 'null'
          maxLength: 20
        email:
          type:
          - string
          - 'null'
          format: email
        auth_user_id:
          type:
          - string
          - 'null'
        created_at:
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
    UpdateOwner:
      type: object
      description: 'All fields are optional. If `owner_category` is `company` or `sc/sci`,

        then `legal_name` and `registration_number` must be provided.

        '
      properties:
        title:
          type: string
          maxLength: 10
        last_name:
          type: string
          maxLength: 255
        first_name:
          type:
          - string
          - 'null'
          maxLength: 255
        owner_category:
          type: string
          enum:
          - individual
          - company
          - sc/sci
        legal_name:
          type:
          - string
          - 'null'
          maxLength: 255
        registration_number:
          type:
          - string
          - 'null'
          maxLength: 50
        country:
          type: string
          maxLength: 50
        address_complement:
          type:
          - string
          - 'null'
          maxLength: 255
        street_number:
          type:
          - string
          - 'null'
          maxLength: 50
        street_name:
          type: string
          maxLength: 255
        locality:
          type:
          - string
          - 'null'
          maxLength: 255
        postal_code:
          type: string
          maxLength: 20
        city:
          type: string
          maxLength: 255
        postal_box:
          type:
          - string
          - 'null'
          maxLength: 20
        mobile_phone:
          type: string
          maxLength: 20
        landline_phone:
          type:
          - string
          - 'null'
          maxLength: 20
        email:
          type: string
          format: email
        auth_user_id:
          type:
          - string
          - 'null'
    StartOwnerClaimResponse:
      type: object
      description: Response after starting an owner claim. The targeted owner receives the link by email.
      required:
      - frontend_url
      - owner_email
      properties:
        frontend_url:
          type: string
          description: Frontend URL (containing the claim token) sent to the owner by email.
          example: https://app.faireplace.com/owner-claim/3f8b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d
        owner_email:
          type: string
          format: email
          description: Email address of the owner the claim was started for.
          example: owner@example.com
    OwnerClaimError:
      type: object
      description: 'Error payload for the owner-claim endpoints.


        Like the guest-signature flow, this uses a minimal `{ error_code, message }`

        shape (NOT the global `Error` envelope), with generic messages on purpose

        (anti-oracle / anti-leak).

        '
      required:
      - error_code
      - message
      properties:
        error_code:
          type: string
          example: OWNER_CLAIM_NOT_FOUND
        message:
          type: string
          example: Demande introuvable.
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key with fp_* prefix, passed as Bearer token
    WorkerApiKey:
      type: apiKey
      in: header
      name: X-API-Key
    WorkerBearer:
      type: http
      scheme: bearer
      bearerFormat: Worker