Leases

Initiate amendment electronic signature

Initiate the electronic signature workflow for an amendment.

Prerequisites:

  • Amendment must be in DRAFT or PENDING_SIGNATURE status
  • No active signature process already in progress

Flow:

  1. Generates the amendment PDF (Typst template)
  2. Uploads the PDF to secure storage
  3. Creates a DocumentSignature record with document_type: AMENDMENT
  4. Creates SignatureRequest for each signer (owner + tenants)
  5. Publishes signature events (Scaleway Topics)
  6. Transitions amendment to PENDING_SIGNATURE

Returns the signature process details including PDF URL and signer list.

post/leases/{lease_id}/amendments/{amendment_id}/initiate-signature

Request

  • Base URL: https://api.faireplace.com/api
  • URL: https://api.faireplace.com/api/leases/{lease_id}/amendments/{amendment_id}/initiate-signature
  • Auth: HTTP bearer

Path parameters

lease_idstring uuid required

Lease ID

amendment_idstring uuid required

Amendment ID

Request body

initiator_idstring uuid required

ID of the user initiating the signature process

initiator_signer_type'proprietaire' | 'locataire' | 'agent_immobilier' | 'caution'

Who is signing. Always lowercase on the wire.

caution is deliberately distinct from locataire: a surety does not sign the lease, they sign their own surety deed, on which they must themselves write the mention required by article 2297 of the Civil Code: without it their undertaking is void.

Example request

{
  "initiator_id": "550e8400-e29b-41d4-a716-446655440000",
  "initiator_signer_type": "proprietaire"
}

Response

Signature process initiated successfully

document_signature_idstring uuid required

Unique ID of the signature process

event_idstring required

Unique event ID for traceability

pdf_urlstring uri required

Absolute URL of the PDF document to sign

media_idstring uuid required

Reference to the media table (PDF document)

status'READY' | 'SIGNING' | 'COMPLETED' | 'FAILED' | 'ARCHIVED' required

Status of the document signature process

Example response

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "signature_550e8400-e29b-41d4-a716-446655440001_1704985200",
  "pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002",
  "media_id": "550e8400-e29b-41d4-a716-446655440002",
  "signature_requests": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signer_type": "proprietaire",
      "signer_email": "jean.dupont@example.com",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    }
  ],
  "status": "READY"
}

Changes

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