FairePlace Property Management API

Signatures

Endpointhttps://api.faireplace.com/api

Electronic lease signing.

These endpoints allow you to:

Initiate a signature process for a lease
List contracts pending signature
Request a signature (send OTP)
Validate an OTP and apply the signature
Track signature status

List leases pending signature for the tenant

GET

https://api.faireplace.com/api

/lessee/leases/pending-signatures

Retrieves the list of leases where the user is a tenant and where a signature is pending on their part.

Filtering criteria

The lease must have an initiated signature document
The document status must not be COMPLETED
There must be a signature request of type TENANT with a non-COMPLETED status

Required permissions

lessee:leases:read

List leases pending signature for the tenant › Responses

Leases pending signature list

object[]

Complete lease

id

string · uuid · required

Unique lease identifier

Example: 550e8400-e29b-41d4-a716-446655440000

estate_id

string · uuid · required

Rented property unit ID

Example: 550e8400-e29b-41d4-a716-446655440001

lease_type_id

string · uuid · required

Lease type ID

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

version

integer · required

Lease version (incremented with each amendment)

Example: 1

start_date

string · date · required

Lease start date

Example: 2024-01-01

rent_amount

number · decimal · required

Lease rent amount (in EUR). Automatically synchronized with the associated Estate's rent_amount.

Example: 1200

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

is_subject_to_rent_evolution_decree

boolean · required

Subject to rent evolution decree at re-letting

Default: false

is_subject_to_reference_rent_cap

boolean · required

Subject to increased reference rent by prefectural decree

Default: false

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Example: 5

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

template_id

string | null · uuid

Template ID used to generate the lease

agent_id

string | null · uuid

Agent ID (real estate agent)

reference_number

string | null · maxLength: 500

Lease reference number

Example: BAIL-2024-001

end_date

string | null · date

Lease end date

Example: 2025-01-01

deposit_amount

number | null · decimal

Security deposit amount

Example: 1200

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

last_revision_date

string | null · date

Date of the last rent revision

next_revision_date

string | null · date

Date of the next rent revision

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

Furniture list ID (for furnished leases)

notes

string | null · maxLength: 5000

Internal notes

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

Example: 20.5

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

Example: 22.55

base_rent_amount

number | null · decimal

Base rent (equal to increased reference rent if supplement)

Example: 1000

rent_complement_amount

number | null · decimal

Rent supplement

Example: 200

rent_complement_justification

string | null · maxLength: 5000

Rent supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

Example: 1150

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter (e.g., Q1 2024)

Example: T1 2024

irl_reference_value

number | null · decimal

IRL reference index value

Example: 142.35

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Regulation compliance status

rent_regulation_last_check

string | null · date-time

Date of last compliance check

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal

Rent increase amount due to landlord's work

rent_increase_work_description

string | null

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null

Application duration in months

solidarity_clause

string | null

Solidarity clause between co-tenants

termination_clause

string | null

Termination clause (termination conditions)

visit_clause

string | null

Clause for visits to re-let or sell

furniture_provision_clause

string | null

Clause regarding provided furniture

pet_clause

string | null

Pet clause

insurance_clause

string | null

Tenant home insurance clause

maintenance_clause

string | null

Annual appliance maintenance clause

damage_clause

string | null

Tenant damage clause

regularization_waiver_clause

string | null

Charge regularization waiver clause

rent_free_clause

string | null

Rent-free clause

custom_clause

string | null

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null

Details of services performed

landlord_fees_inventory_entry

number | null · decimal

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null

Move-in inspection service details

landlord_fees_other

number | null · decimal

Other services

landlord_fees_other_description

string | null

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null

Details of services performed

tenant_fees_inventory_entry

number | null · decimal

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null

Move-in inspection service details

tenant_fees_other

number | null · decimal

Other fees

tenant_fees_other_description

string | null

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null

Agency/professional name

fees_agency_registration_number

string | null

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision per Articles L145-33 to L145-38)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

GET/lessee/leases/pending-signatures

curl --request GET \
  --url https://api.faireplace.com/api/lessee/leases/pending-signatures

shell

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "estate_id": "550e8400-e29b-41d4-a716-446655440001",
    "reference_number": "BAIL-2024-001",
    "status": "ACTIVE",
    "start_date": "2024-01-01",
    "end_date": "2025-12-31",
    "rent_amount": 1200
  }
]

json

application/json

Get signature status of a lease for the tenant

GET

https://api.faireplace.com/api

/lessee/leases/{id}/signature/status

Retrieves the signature status of a specific lease for the authenticated tenant.

Returns:

The signature document status (READY, SIGNING, COMPLETED, FAILED, ARCHIVED)
The signed media ID (signed_media_id) if the document is signed, allowing retrieval of the signed PDF URL
The details of all associated signature requests
Information about the signers and their status

Required permissions

lessee:leases:read

Get signature status of a lease for the tenant › path Parameters

id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

Get signature status of a lease for the tenant › Responses

Signature status retrieved successfully

lease_id

string · uuid

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

document_signature_id

string · uuid

Signature document ID

Example: 550e8400-e29b-41d4-a716-446655440001

status

string · enum

Signature document status

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: SIGNING

signed_media_id

string | null · uuid

Signed PDF media ID (available after full signature completion)

Example: 550e8400-e29b-41d4-a716-446655440002

object[]

Signature requests list

GET/lessee/leases/{id}/signature/status

curl --request GET \
  --url https://api.faireplace.com/api/lessee/leases/:id/signature/status

shell

Example Responses

No example specified for this content type

application/json

Sign a lease as a tenant

POST

https://api.faireplace.com/api

/lessee/leases/{id}/signature/sign

Allows the authenticated tenant to sign a lease by validating the OTP received via SMS/email.

Signing process

The user must have received an OTP via SMS or email
The OTP is validated via the DO Global service
The signature is applied to the PDF document
The signature request status is updated

Security validations

Verifies that the user is indeed a tenant of the lease
Verifies that the person_id derived from the JWT matches the lease signers
Validates the OTP before applying the signature

Required permissions

lessee:leases:sign

Sign a lease as a tenant › path Parameters

id

string · uuid · required

Lease ID to sign

Example: 550e8400-e29b-41d4-a716-446655440000

Sign a lease as a tenant › Request Body

document_signature_id

string · uuid · required

Signature document ID to sign

Example: 550e8400-e29b-41d4-a716-446655440001

otp

string · minLength: 4 · maxLength: 8 · required

OTP code received via SMS or email

Example: 123456

Sign a lease as a tenant › Responses

Signature initiated successfully (asynchronous processing)

success

boolean

Indicates whether the request was accepted

Example: true

message

string

Confirmation message

Example: OTP validation sent to processing queue

document_signature_id

string · uuid

Signature document ID

Example: 550e8400-e29b-41d4-a716-446655440001

signed_media_id

string | null · uuid

Signed PDF media ID (available after processing)

Example: 550e8400-e29b-41d4-a716-446655440002

signed_pdf_url

string | null

Signed PDF URL (available after processing)

Example: https://storage.example.com/signed/lease-550e8400.pdf

POST/lessee/leases/{id}/signature/sign

curl --request POST \
  --url https://api.faireplace.com/api/lessee/leases/:id/signature/sign \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440001",
  "otp": "123456"
}
'

shell

Example Request Body

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440001",
  "otp": "123456"
}

json

application/json

Example Responses

No example specified for this content type

application/json

Download the signed lease (PDF)

GET

https://api.faireplace.com/api

/lessee/leases/{id}/pdf

Downloads the signed lease PDF, only if the document has been fully signed by all signers.

Required conditions

The signature document must have the status COMPLETED
All signature requests must have the status COMPLETED
The user must be a tenant of the lease

Response format

Content-Type: application/pdf
Content-Disposition: attachment; filename="lease-{id}.pdf"
The file may be encrypted (SSE-C) depending on the security level

Required permissions

lessee:leases:download

Download the signed lease (PDF) › path Parameters

id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

Download the signed lease (PDF) › Responses

Signed lease PDF

string

GET/lessee/leases/{id}/pdf

curl --request GET \
  --url https://api.faireplace.com/api/lessee/leases/:id/pdf

shell

Example Responses

PDF binary content

plain

application/pdf

Initiate electronic signature (global level)

POST

https://api.faireplace.com/api

/leases/signatures/initiate

Initiates the electronic signature process for a lease.

Signer identification

The system automatically identifies the initiating signer via:

The auth_user_id extracted from the JWT (claim sub)
Matching with an owner_id or lessee_id in the database
The signer type (owner or tenant) is determined automatically

Verification at individual signer level

The system now verifies at the individual signer level rather than at the global document level:

If you have already signed: you cannot restart (error 409)
If the document is fully signed: you cannot restart (error 409)
If a signature is in progress for you: you must wait (error 409)
If another signer has signed: you can continue the process (partial restart allowed)

Partial restart

If only one signer has signed, the other signer can initiate a new signature. This allows continuing the process even if one signer has already completed their signature.

Generates the PDF, creates signature requests for all signers (owner + tenants).

Initiate electronic signature (global level) › Request Body

lease_id

string · uuid · required

Lease ID to be signed

Example: 550e8400-e29b-41d4-a716-446655440000

Initiate electronic signature (global level) › Responses

Signature initiated successfully

Response after initiating a signature

document_signature_id

string · uuid · required

Unique ID of the signature process

Example: 550e8400-e29b-41d4-a716-446655440000

event_id

string · required

Unique event ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

pdf_url

string · uri · required

Absolute URL of the PDF document to sign

Example: https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002

media_id

string · uuid · required

Reference to the media table (PDF document)

Example: 550e8400-e29b-41d4-a716-446655440002

object[] · minItems: 1 · required

List of created signature requests

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

POST/leases/signatures/initiate

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/initiate \
  --header 'Content-Type: application/json' \
  --data '
{
  "lease_id": "550e8400-e29b-41d4-a716-446655440000"
}
'

shell

Example Request Body

{
  "lease_id": "550e8400-e29b-41d4-a716-446655440000"
}

json

Example Responses

{
  "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-446655440003",
      "signer_type": "PROPRIETAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "signer_type": "LOCATAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    }
  ],
  "status": "SIGNING"
}

json

application/json

deprecated

Get signature status (global route - deprecated)

GET

https://api.faireplace.com/api

/leases/signatures/status

Retrieves the current status of an electronic signature process. Note: This global route requires a lease_id as a query parameter. It is recommended to use the specific route /leases/{lease_id}/signature/status instead.

Get signature status (global route - deprecated) › query Parameters

lease_id

string · uuid · required

Lease ID

Get signature status (global route - deprecated) › Responses

Status retrieved successfully

Status of a signature process (returned by get_signature_status with DO Global)

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

object · required

Signature state from DO Global (dynamic structure)

Example: {"status":"SIGNING","signers":[{"signer_type":"PROPRIETAIRE","status":"COMPLETED"},{"signer_type":"LOCATAIRE","status":"PENDING"}]}

GET/leases/signatures/status

curl --request GET \
  --url 'https://api.faireplace.com/api/leases/signatures/status?lease_id=%3Cstring%3E'

shell

Example Responses

{
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": {
    "status": "SIGNING",
    "signers": [
      {
        "signer_type": "PROPRIETAIRE",
        "status": "COMPLETED"
      },
      {
        "signer_type": "LOCATAIRE",
        "status": "PENDING"
      }
    ]
  }
}

json

application/json

Status of a specific document

GET

https://api.faireplace.com/api

/leases/signatures/document/{document_signature_id}/status

Retrieves the detailed status of a signature process by its ID (global route)

Status of a specific document › path Parameters

document_signature_id

string · uuid · required

Signature process ID

Status of a specific document › Responses

Status retrieved successfully

Detailed status of a signature document (returned by get_document_signature_status)

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

event_id

string · required

Unique ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

pdf_url

string · uri · required

PDF document URL

Example: https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002

media_id

string · uuid · required

Reference to the media table

Example: 550e8400-e29b-41d4-a716-446655440002

object[] · required

List of signature requests

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

GET/leases/signatures/document/{document_signature_id}/status

curl --request GET \
  --url https://api.faireplace.com/api/leases/signatures/document/:document_signature_id/status

shell

Example Responses

{
  "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": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    }
  ],
  "status": "READY"
}

json

application/json

List all contracts pending signature

GET

https://api.faireplace.com/api

/leases/signatures/pending

Retrieves the paginated list of all contracts pending signature for the tenant.

Access

This endpoint is for users with the "owner" role in the tenant. It returns all contracts where at least one signer has a PENDING or SIGNING status.

Automatic filtering

Only contracts from the authenticated user's tenant are returned (multi-tenant isolation)
Contracts with COMPLETED, EXPIRED, or CANCELLED status are excluded
Only contracts with at least one pending signer are returned

Returned information

For each contract, you receive:

Document information (ID, lease, status, dates, URLs)
Complete list of all signers with their individual statuses
The URL of the PDF document to sign
The URL of the signed PDF (if available)

Pagination

Use limit and offset to paginate results. The total_count field indicates the total number of matching contracts.

List all contracts pending signature › query Parameters

limit

integer · min: 1 · max: 100

Maximum number of results per page (default: 50, max: 100)

Default: 50

offset

integer · min: 0

Number of results to skip for pagination (default: 0)

Default: 0

List all contracts pending signature › Responses

Pending contracts list retrieved successfully

Paginated response containing the list of contracts pending signature for the tenant. Used by the `GET /leases/signatures/pending` endpoint. ## Pagination Use the `limit` and `offset` fields in the request to navigate through results. The `total_count` field indicates the total number of contracts matching the criteria, allowing you to calculate the number of pages. ## Page calculation example ``` total_pages = ceil(total_count / limit) current_page = floor(offset / limit) + 1 ```

object[] · required

List of contracts pending signature (for the current page)

total_count

integer · int64 · min: 0 · required

Total number of pending contracts (all combined, before pagination)

Example: 25

limit

integer · min: 1 · max: 100 · required

Maximum number of results per page (value used for the request)

Example: 50

Default: 50

offset

integer · min: 0 · required

Number of skipped results (pagination offset used)

Example: 0

Default: 0

GET/leases/signatures/pending

curl --request GET \
  --url https://api.faireplace.com/api/leases/signatures/pending

shell

Example Responses

{
  "contracts": [
    {
      "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
      "lease_id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "SIGNING",
      "initiator_type": "PROPRIETAIRE",
      "created_at": "2024-01-15T10:00:00Z",
      "expires_at": "2024-01-22T10:00:00Z",
      "document_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002",
      "signed_pdf_url": null,
      "signers": [
        {
          "signer_type": "PROPRIETAIRE",
          "signer_email": "[email protected]",
          "signer_phone": "+33612345678",
          "status": "PENDING",
          "expires_at": "2024-01-22T10:00:00Z",
          "first_name": "Jean",
          "last_name": "Dupont",
          "title": "Mr."
        },
        {
          "signer_type": "LOCATAIRE",
          "signer_email": "[email protected]",
          "signer_phone": "+33612345679",
          "status": "COMPLETED",
          "expires_at": "2024-01-22T10:00:00Z",
          "first_name": "Marie",
          "last_name": "Martin",
          "title": "Mrs."
        }
      ]
    }
  ],
  "total_count": 1,
  "limit": 50,
  "offset": 0
}

json

application/json

Signature contract details

GET

https://api.faireplace.com/api

/leases/signatures/contracts/{document_signature_id}

Retrieves the complete details of a signature contract, including all signers and their statuses

Signature contract details › path Parameters

document_signature_id

string · uuid · required

Signature process ID

Signature contract details › Responses

Details retrieved successfully

Full details of a signature contract

document_signature_id

string · uuid · required

lease_id

string · uuid · required

media_id

string · uuid · required

Reference to the media table

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

initiator_type

string · enum · required

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

initiator_id

string · uuid · required

Initiator ID

Example: 550e8400-e29b-41d4-a716-446655440003

event_id

string · required

Unique ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

created_at

string · date-time · required

object[] · minItems: 1 · required

expires_at

string | null · date-time

document_url

string | null · uri

signed_pdf_url

string | null · uri

archive_url

string | null · uri

URL of the archived PDF with electronic timestamping

Example: https://storage.example.com/leases/archived-doc.pdf

GET/leases/signatures/contracts/{document_signature_id}

curl --request GET \
  --url https://api.faireplace.com/api/leases/signatures/contracts/:document_signature_id

shell

Example Responses

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "media_id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "READY",
  "initiator_type": "PROPRIETAIRE",
  "initiator_id": "550e8400-e29b-41d4-a716-446655440003",
  "event_id": "signature_550e8400-e29b-41d4-a716-446655440001_1704985200",
  "created_at": "2024-01-15T10:00:00Z",
  "expires_at": "2024-01-20T10:00:00Z",
  "signers": [
    {
      "signer_type": "PROPRIETAIRE",
      "signer_email": "[email protected]",
      "signer_phone": "+33612345678",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z",
      "signed_at": "2024-01-16T15:30:00Z",
      "first_name": "Jean",
      "last_name": "Dupont",
      "legal_name": "SARL Dupont Immobilier",
      "title": "M."
    }
  ],
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signed_pdf_url": "https://storage.example.com/leases/signed-doc.pdf",
  "archive_url": "https://storage.example.com/leases/archived-doc.pdf"
}

json

application/json

Request a signature (send OTP) - Global route

POST

https://api.faireplace.com/api

/leases/signatures/request

Requests a signer's signature by sending an OTP code via SMS. The person_id (owner_id or lessee_id) is automatically resolved from the JWT (auth_user_id). Minimal structure: document_signature_id and signature_data.signature_image.

Request a signature (send OTP) - Global route › Request Body

Request to initiate a user's signature. This object is sent to the `/leases/{lease_id}/signature/request` endpoint to: 1. Submit the signature image captured by the user 2. Trigger sending an OTP code via SMS The user is automatically identified via their JWT - no need to specify their identity in the request.

document_signature_id

string · uuid · required

Unique identifier of the signature process. Obtained during initiation via /signature/initiate.

Example: 550e8400-e29b-41d4-a716-446655440000

object · required

Handwritten signature data

Request a signature (send OTP) - Global route › Responses

OTP sent successfully

Dynamic response from DO Global

POST/leases/signatures/request

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_data": {
    "signature_image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }
}
'

shell

Example Request Body

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_data": {
    "signature_image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }
}

json

application/json

Example Responses

{
  "success": true,
  "message": "OTP code sent via SMS",
  "expires_at": "2024-01-15T10:15:00Z"
}

json

application/json

Process a signature event

POST

https://api.faireplace.com/api

/leases/signatures/events/process

Processes a signature request event received from the notifier function (used by webhooks)

Process a signature event › Request Body

Signature request event (format aligned with the notifier function)

object · required

Base event for Scaleway Topics

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

object · required

Signer information

document_url

string · uri · required

URL of the PDF document to sign

Example: https://storage.example.com/leases/unsigned-doc.pdf

signature_url

string · uri · required

URL to access the signature

Example: https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000

expires_at

string · date-time · required

Signature request expiration date

Example: 2024-01-22T10:00:00Z

Process a signature event › Responses

Event processed successfully

status

string

event_id

string

The processed event ID

Example: evt_550e8400-e29b-41d4-a716-446655440000

document_signature_id

string · uuid

lease_id

string · uuid

signer_email

string · email

signer_type

string · enum

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

POST/leases/signatures/events/process

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/events/process \
  --header 'Content-Type: application/json' \
  --data '
{
  "base": {
    "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
    "event_type": "SignatureRequested",
    "timestamp": "2024-01-15T10:00:00Z",
    "correlation_id": "corr_550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "metadata": {}
  },
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_info": {
    "signer_type": "PROPRIETAIRE",
    "phone": "+33612345678",
    "email": "[email protected]",
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jean",
    "last_name": "Dupont",
    "legal_name": "SARL Dupont Immobilier",
    "title": "M."
  },
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signature_url": "https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-22T10:00:00Z"
}
'

shell

Example Request Body

{
  "base": {
    "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
    "event_type": "SignatureRequested",
    "timestamp": "2024-01-15T10:00:00Z",
    "correlation_id": "corr_550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "metadata": {}
  },
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_info": {
    "signer_type": "PROPRIETAIRE",
    "phone": "+33612345678",
    "email": "[email protected]",
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jean",
    "last_name": "Dupont",
    "legal_name": "SARL Dupont Immobilier",
    "title": "M."
  },
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signature_url": "https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-22T10:00:00Z"
}

json

Example Responses

{
  "status": "processed",
  "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_email": "[email protected]",
  "signer_type": "PROPRIETAIRE"
}

json

application/json

Initiate signature for a specific lease

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/initiate

Initiates the electronic signature process directly from the context of a lease.

Signer identification

The system automatically identifies the initiating signer via:

The auth_user_id extracted from the JWT (claim sub)
Matching with an owner_id or lessee_id in the database
The signer type (owner or tenant) is determined automatically

Verification at individual signer level

The system now verifies at the individual signer level rather than at the global document level:

If you have already signed: you cannot restart (error 409)
If the document is fully signed: you cannot restart (error 409)
If a signature is in progress for you: you must wait (error 409)
If another signer has signed: you can continue the process (partial restart allowed)

Partial restart

If only one signer has signed, the other signer can initiate a new signature. This allows continuing the process even if one signer has already completed their signature.

PDF generation

Generates the PDF, creates signature requests for all signers (owner + tenants).

Initiate signature for a specific lease › path Parameters

lease_id

string · uuid · required

Lease ID

Initiate signature for a specific lease › Request Body optional

Initiate signature for a specific lease › Responses

Signature initiated successfully

Response after initiating a signature

document_signature_id

string · uuid · required

Unique ID of the signature process

Example: 550e8400-e29b-41d4-a716-446655440000

event_id

string · required

Unique event ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

pdf_url

string · uri · required

Absolute URL of the PDF document to sign

Example: https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002

media_id

string · uuid · required

Reference to the media table (PDF document)

Example: 550e8400-e29b-41d4-a716-446655440002

object[] · minItems: 1 · required

List of created signature requests

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

POST/leases/{lease_id}/signature/initiate

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/initiate \
  --header 'Content-Type: application/json' \
  --data '{}'

shell

Example Request Body

{}

json

Example Responses

{
  "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-446655440003",
      "signer_type": "PROPRIETAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "signer_type": "LOCATAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    }
  ],
  "status": "SIGNING"
}

json

application/json

Signature status of a lease

GET

https://api.faireplace.com/api

/leases/{lease_id}/signature/status

Retrieves the signature status for this specific lease. This route fetches the latest document_signature for the lease and queries DO Global to obtain the current state of the signature.

Signature status of a lease › path Parameters

lease_id

string · uuid · required

Lease ID

Signature status of a lease › Responses

Status retrieved successfully

Status of a signature process (returned by get_signature_status with DO Global)

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

object · required

Signature state from DO Global (dynamic structure)

Example: {"status":"SIGNING","signers":[{"signer_type":"PROPRIETAIRE","status":"COMPLETED"},{"signer_type":"LOCATAIRE","status":"PENDING"}]}

GET/leases/{lease_id}/signature/status

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/status

shell

Example Responses

{
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": {
    "status": "SIGNING",
    "signers": [
      {
        "signer_type": "PROPRIETAIRE",
        "status": "COMPLETED"
      },
      {
        "signer_type": "LOCATAIRE",
        "status": "PENDING"
      }
    ]
  }
}

json

application/json

Status of a specific signature document

GET

https://api.faireplace.com/api

/leases/{lease_id}/signature/document/{document_signature_id}/status

Retrieves the detailed status of a signature process by its ID in the context of a lease

Status of a specific signature document › path Parameters

lease_id

string · uuid · required

Lease ID

document_signature_id

string · uuid · required

Signature process ID

Status of a specific signature document › Responses

Status retrieved successfully

Detailed status of a signature document (returned by get_document_signature_status)

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

event_id

string · required

Unique ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

pdf_url

string · uri · required

PDF document URL

Example: https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002

media_id

string · uuid · required

Reference to the media table

Example: 550e8400-e29b-41d4-a716-446655440002

object[] · required

List of signature requests

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

GET/leases/{lease_id}/signature/document/{document_signature_id}/status

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/document/:document_signature_id/status

shell

Example Responses

{
  "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": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    }
  ],
  "status": "READY"
}

json

application/json

Request a signature - Send an OTP via SMS

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/request

Initiates the signature process for the authenticated user by sending an OTP code via SMS.

Signature flow

The user captures their signature image (handwritten drawing)
The image is encoded in base64 and sent with this endpoint
The system identifies the user via their JWT and verifies they are a signer of the lease
A 6-digit OTP code is sent via SMS to the registered phone number
The code expires after 5 minutes

User identification

The system automatically identifies the user as a signer via:

The auth_user_id extracted from the JWT (claim sub)
Matching with an owner_id or lessee_id in the database

Prerequisites

The user must be authenticated and be a signer of the lease
The signature process must have been initiated (/signature/initiate)
The signer must have a valid registered phone number

Signature image

The image must be:

Encoded in base64
PNG or JPEG format recommended
Reasonable size (< 500KB after encoding)

Request a signature - Send an OTP via SMS › path Parameters

lease_id

string · uuid · required

UUID identifier of the lease

Request a signature - Send an OTP via SMS › Request Body

document_signature_id

string · uuid · required

Unique identifier of the signature process. Obtained during initiation via /signature/initiate.

Example: 550e8400-e29b-41d4-a716-446655440000

object · required

Handwritten signature data

Request a signature - Send an OTP via SMS › Responses

OTP code sent successfully via SMS

success

boolean · required

Indicates whether the sending was successful

Example: true

message

string · required

Confirmation message

Example: OTP code sent by SMS

expires_at

string · date-time

OTP code expiration date (typically 5 minutes)

Example: 2024-01-15T10:15:00Z

phone_hint

string

Phone number hint (partially masked)

Example: +33 6 ** ** ** 78

POST/leases/{lease_id}/signature/request

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_data": {
    "signature_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAACoCAMAAABt9SM9AAAABGdBTUEAALGPC..."
  }
}
'

shell

Example Request Body

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_data": {
    "signature_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAACoCAMAAABt9SM9AAAABGdBTUEAALGPC..."
  }
}

json

application/json

Example Responses

{
  "success": true,
  "message": "OTP code sent via SMS to +33 6 ** ** ** 78",
  "expires_at": "2024-01-15T10:15:00Z"
}

json

application/json

Validate OTP and apply electronic signature

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/validate-otp

Validates the OTP code received via SMS and applies the electronic signature to the PDF document.

Validation flow

The user enters the 6-digit OTP code received via SMS
The system verifies that the code is valid and not expired
If valid, the signature (previously captured image) is applied to the PDF
The signer's status changes to COMPLETED
If all signers have signed, the final document is generated

User identification

The system automatically identifies the user as a signer via:

The auth_user_id extracted from the JWT (claim sub)
Matching with an owner_id or lessee_id in the database
Verification that this user is indeed a signer of the lease

OTP code expiration

The OTP code expires after 5 minutes. If the code has expired, the user must request a new code via /signature/request.

Final document

When all signers have validated their signature:

The signed PDF is generated with all signatures
The signed PDF URL is returned in signed_pdf_url
The document status changes to COMPLETED
A notification is sent to all signers

Validate OTP and apply electronic signature › path Parameters

lease_id

string · uuid · required

UUID identifier of the lease

Validate OTP and apply electronic signature › Request Body

Request to validate the OTP code and finalize the signature. This object is sent to the `/leases/{lease_id}/signature/validate-otp` endpoint after the user has received their code via SMS. The OTP code expires after **5 minutes**. If expired, the user must request a new code via `/signature/request`.

document_signature_id

string · uuid · required

Unique identifier of the signature process. Must match the one used during the signature request.

Example: 550e8400-e29b-41d4-a716-446655440000

otp

string · minLength: 6 · maxLength: 6 · pattern: ^\d{6}$ · required

6-digit OTP code received via SMS.

Format: Exactly 6 digits (0-9) Validity: 5 minutes after sending Attempts: Maximum 3 attempts before temporary lockout

Example: 123456

Validate OTP and apply electronic signature › Responses

Signature applied successfully

success

boolean · required

Indicates whether the signature was applied

Example: true

message

string · required

Confirmation message

Example: Signature completed successfully

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

signer_status

string

New signer status

Example: COMPLETED

document_status

string · enum

Overall document status after this signature

Enum values:

SIGNING

COMPLETED

Example: SIGNING

remaining_signers

integer

Number of remaining signers

Example: 1

signed_pdf_url

string | null · uri

Signed PDF URL (available only if all signers have signed)

Example: null

POST/leases/{lease_id}/signature/validate-otp

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/validate-otp \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "otp": "123456"
}
'

shell

Example Request Body

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "otp": "123456"
}

json

application/json

Example Responses

{
  "success": true,
  "message": "Signature completed successfully. Waiting for other signers.",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signer_status": "COMPLETED",
  "document_status": "SIGNING",
  "remaining_signers": 1,
  "signed_pdf_url": null
}

json

application/json

Process a signature event for a lease

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/events/process

Processes a signature request event received from the notifier function in the context of a specific lease

Process a signature event for a lease › path Parameters

lease_id

string · uuid · required

Lease ID

Process a signature event for a lease › Request Body

Signature request event (format aligned with the notifier function)

object · required

Base event for Scaleway Topics

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

object · required

Signer information

document_url

string · uri · required

URL of the PDF document to sign

Example: https://storage.example.com/leases/unsigned-doc.pdf

signature_url

string · uri · required

URL to access the signature

Example: https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000

expires_at

string · date-time · required

Signature request expiration date

Example: 2024-01-22T10:00:00Z

Process a signature event for a lease › Responses

Event processed successfully

status

string

event_id

string

The processed event ID

Example: evt_550e8400-e29b-41d4-a716-446655440000

document_signature_id

string · uuid

lease_id

string · uuid

signer_email

string · email

signer_type

string · enum

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

POST/leases/{lease_id}/signature/events/process

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/events/process \
  --header 'Content-Type: application/json' \
  --data '
{
  "base": {
    "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
    "event_type": "SignatureRequested",
    "timestamp": "2024-01-15T10:00:00Z",
    "correlation_id": "corr_550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "metadata": {}
  },
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_info": {
    "signer_type": "PROPRIETAIRE",
    "phone": "+33612345678",
    "email": "[email protected]",
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jean",
    "last_name": "Dupont",
    "legal_name": "SARL Dupont Immobilier",
    "title": "M."
  },
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signature_url": "https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-22T10:00:00Z"
}
'

shell

Example Request Body

{
  "base": {
    "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
    "event_type": "SignatureRequested",
    "timestamp": "2024-01-15T10:00:00Z",
    "correlation_id": "corr_550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "metadata": {}
  },
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_info": {
    "signer_type": "PROPRIETAIRE",
    "phone": "+33612345678",
    "email": "[email protected]",
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jean",
    "last_name": "Dupont",
    "legal_name": "SARL Dupont Immobilier",
    "title": "M."
  },
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signature_url": "https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-22T10:00:00Z"
}

json

Example Responses

{
  "status": "processed",
  "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_email": "[email protected]",
  "signer_type": "PROPRIETAIRE"
}

json

application/json

Cancel a signature request

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/signature/cancel

Cancels an ongoing signature request and resets the lease to DRAFT status. This operation allows re-initiating a signature after cancellation.

Action performed

This operation performs the following steps:

Marks the document as CANCELLED in DO Global (signature orchestrator)
Marks all signers as CANCELLED in DO Global
Marks the document as FAILED in the database (allows re-initiation)
Marks all ongoing signature requests as FAILED (Pending, OtpSent, Signing)
Resets the lease to DRAFT status

Re-initiation possible

After a cancellation, you can re-initiate a new signature via /signature/initiate. The system detects that the previous document is in FAILED status and allows re-initiation.

Difference with reset

Unlike /reset, this operation:

Preserves history: Documents and signature requests remain in the database with FAILED status
Marks as failed: The status is changed to FAILED in the DB (and CANCELLED in DO Global)
Allows auditing: Previous attempts remain visible for traceability
Allows re-initiation: A new signature process can be initiated immediately

Use cases

Use this operation when:

You have detected an error in the contract before sending
You want to correct the document and re-initiate
You need to preserve the history of attempts
The tenant is not responding and you want to re-initiate after correction

Prerequisites

The lease must be in PENDING_SIGNATURE status
A signature document must exist
The user must have the LeasesWrite permission

Cancel a signature request › path Parameters

lease_id

string · uuid · required

Lease ID

Cancel a signature request › Responses

Signature cancelled successfully

Response after cancelling a signature request. Cancellation marks the document as CANCELLED in the DO Global and sets the lease back to DRAFT status, while preserving the history of signature attempts.

success

boolean · required

Indicates whether the cancellation succeeded

Example: true

message

string · required

Confirmation message

Example: Signature cancelled for lease 550e8400-e29b-41d4-a716-446655440001

document_signature_id

string · uuid · required

Cancelled signature document ID

Example: 550e8400-e29b-41d4-a716-446655440000

DELETE/leases/{lease_id}/signature/cancel

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/cancel

shell

Example Responses

{
  "success": true,
  "message": "Signature cancelled for lease 550e8400-e29b-41d4-a716-446655440001",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000"
}

json

application/json

Fully reset a signature

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/signature/reset

Completely resets all signatures for a lease by deleting all traces. This operation allows starting from scratch without keeping any history.

Action performed

This operation performs the following steps:

Deletes the signature document in DO Global (signature orchestrator)
Deletes all signature requests in the database
Deletes the signature document in the database
Resets the lease to DRAFT status

Consequences

All signature data is deleted (no history retained)
The lease can be re-initiated for a new signature
Previously generated PDFs remain in the media system but are no longer linked
No trace of the previous attempt is retained

Difference with cancel

Unlike /cancel, this operation:

Completely deletes: All data is deleted (no retention)
No history: No trace of the previous attempt
Start from scratch: As if no signature was ever initiated

Use cases

Use this operation when:

The tenant is not responding after several days and you want to start from scratch
You need to completely delete an erroneous attempt
You want a new signature process without history
A major contract change requires a new document

Prerequisites

The lease must be in PENDING_SIGNATURE status
The user must have the LeasesWrite permission

Fully reset a signature › path Parameters

lease_id

string · uuid · required

Lease ID

Fully reset a signature › Responses

Signature reset successfully

Response after a complete signature reset. The complete reset deletes all signature data (documents and requests) and sets the lease back to DRAFT status, allowing a new signature initiation.

success

boolean · required

Indicates whether the reset succeeded

Example: true

message

string · required

Confirmation message

Example: Signature fully reset for lease 550e8400-e29b-41d4-a716-446655440001

DELETE/leases/{lease_id}/signature/reset

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/reset

shell

Example Responses

{
  "success": true,
  "message": "Signature completely reset for lease 550e8400-e29b-41d4-a716-446655440001"
}

json

application/json

Resend signature request for a signer

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/resend/{signer_type}

Resends the signature request for a specific signer (owner or tenant).

Action performed

This operation:

Resets the signer's status to PENDING
Resets notification counters
Sends a new INITIAL notification (SMS/Email) to the signer
Allows a new signature attempt for this signer only

Use cases

A signer did not receive the initial notification
A signer needs a new link to sign
Reset after a signature error for a single signer

Prerequisites

The lease must be in PENDING_SIGNATURE status
A signature document must exist
The specified signer must exist in the signature requests
The user must have the LeasesWrite permission

Note

This operation only affects the specified signer. Other signers retain their current status.

Resend signature request for a signer › path Parameters

lease_id

string · uuid · required

Lease ID

signer_type

string · enum · required

Signer type for which to resend the request

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

Resend signature request for a signer › Request Body optional

Resend signature request for a signer › Responses

Signature request resent successfully

Response after resending a signature request for a specific signer. Resending resets the signer's status to PENDING and resends the notifications (SMS/Email) to allow a new signature attempt.

success

boolean · required

Indicates whether the resend succeeded

Example: true

message

string · required

Confirmation message

Example: Signature request resent for signer proprietaire

signer_type

string · enum · required

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

resend_count

integer · min: 0 · required

Total number of resends performed for this signer (including this request)

Example: 1

remaining_resends

integer · min: 0 · required

Number of remaining allowed resends (maximum 5 total)

Example: 4

POST/leases/{lease_id}/signature/resend/{signer_type}

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/resend/:signer_type \
  --header 'Content-Type: application/json' \
  --data '{}'

shell

Example Request Body

{}

json

Example Responses

{
  "success": true,
  "message": "Signature request resent for signer proprietaire",
  "signer_type": "PROPRIETAIRE",
  "resend_count": 1,
  "remaining_resends": 4
}

json

application/json

Leases Lessees