Electronic Signatures

Copy page

Electronic Signatures

Sign leases electronically with eIDAS-compliant advanced electronic signatures.

FairePlace provides a built-in electronic signature workflow that handles OTP verification, document signing, certificate embedding, and tamper-proof proof archival — no third-party signature service needed.

How it works

Code
 
1. Generate PDF     ──►  Lease document ready for signing
2. Purchase credits ──►  1 credit = 1 lease signature (all signers included)
3. Initiate signing ──►  Signers receive OTP via SMS
4. Signer validates ──►  OTP code + drawn signature
5. All signed       ──►  Signed PDF with embedded certificate
6. Proof archived   ──►  eIDAS-compliant JSON proof file

Each signer goes through the following flow:

Code
 
Pending → OtpSent → Signing → Completed
                        │
                        ├──► Failed (wrong OTP, technical error)
                        └──► Expired (OTP expired, signer didn't complete)

Signer types

Type	Description
Proprietaire	Property owner — signs first
Locataire	Tenant — signs after the owner
AgentImmobilier	Real estate agent — can sign on behalf of the owner

Starting a signature

Prerequisites

1. A lease with status Draft or Active
2. A generated PDF for the lease (see Create a Lease, step 8)
3. At least 1 signature credit (see Payments & Credits)

Initiate the signature

Code
 
curl -X POST https://api.faireplace.com/api/leases/{lease_id}/signature/initiate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_id": "pdf-6f789012-abcd-ef12-3456-7890abcdef34",
    "signers": [
      {
        "type": "Proprietaire",
        "name": "Jean Dupont",
        "email": "[email protected]",
        "phone": "+33612345678"
      },
      {
        "type": "Locataire",
        "name": "Marie Martin",
        "email": "[email protected]",
        "phone": "+33698765432"
      }
    ]
  }'

Code
 
{
  "signature_id": "sig-78901234-abcd-ef12-3456-7890abcdef56",
  "status": "Pending",
  "signers": [
    {
      "type": "Proprietaire",
      "name": "Jean Dupont",
      "status": "Pending",
      "order": 1
    },
    {
      "type": "Locataire",
      "name": "Marie Martin",
      "status": "Pending",
      "order": 2
    }
  ],
  "expires_at": "2026-03-05T10:08:00Z",
  "created_at": "2026-02-19T10:08:00Z"
}

The first signer (Proprietaire) immediately receives an OTP via SMS.

Signature statuses

Overall signature status

Status	Description
Pending	Signature initiated, waiting for signers
InProgress	At least one signer has started
Completed	All signers have signed successfully
Failed	A signer failed (wrong OTP, rejected)
Expired	Signature expired before completion (14 days default)
Cancelled	Signature was cancelled by the initiator

Individual signer status

Status	Description
Pending	Waiting for their turn (signers sign in order)
OtpSent	OTP sent via SMS, waiting for validation
Signing	OTP validated, signer is drawing their signature
Completed	Signature captured and embedded
Failed	OTP validation failed (3 attempts max)
Expired	OTP expired (5 minutes validity)

Checking status

Poll the signature status to track progress:

Code
 
curl https://api.faireplace.com/api/leases/{lease_id}/signature/status \
  -H "Authorization: Bearer $TOKEN"

Code
 
{
  "signature_id": "sig-78901234-abcd-ef12-3456-7890abcdef56",
  "status": "InProgress",
  "signers": [
    {
      "type": "Proprietaire",
      "name": "Jean Dupont",
      "status": "Completed",
      "signed_at": "2026-02-19T14:30:00Z"
    },
    {
      "type": "Locataire",
      "name": "Marie Martin",
      "status": "OtpSent",
      "otp_sent_at": "2026-02-19T14:30:05Z"
    }
  ]
}

Tip: Use webhooks to get real-time notifications instead of polling. See Payments & Credits for webhook configuration.

Downloading the signed document

Once status is Completed:

Code
 
# Download signed PDF
curl https://api.faireplace.com/api/leases/{lease_id}/signature/document \
  -H "Authorization: Bearer $TOKEN" \
  -o signed-lease.pdf

The signed PDF includes:

• Each signer's drawn signature on the signature pages
• An embedded digital certificate (PAdES-B format)
• A tamper-proof seal — any modification invalidates the document

Retrieving the proof certificate

The proof file provides a legally admissible record of the signing process:

Code
 
curl https://api.faireplace.com/api/leases/{lease_id}/signature/proof \
  -H "Authorization: Bearer $TOKEN"

Code
 
{
  "signature_id": "sig-78901234-abcd-ef12-3456-7890abcdef56",
  "document": {
    "name": "bail-2026-001.pdf",
    "hash_sha256": "a1b2c3d4e5f6...",
    "pages": 12
  },
  "signers": [
    {
      "type": "Proprietaire",
      "name": "Jean Dupont",
      "email": "[email protected]",
      "phone_last4": "5678",
      "otp_validated_at": "2026-02-19T14:29:50Z",
      "signed_at": "2026-02-19T14:30:00Z",
      "ip_address": "92.184.xxx.xxx",
      "user_agent": "Mozilla/5.0..."
    },
    {
      "type": "Locataire",
      "name": "Marie Martin",
      "email": "[email protected]",
      "phone_last4": "5432",
      "otp_validated_at": "2026-02-19T16:44:50Z",
      "signed_at": "2026-02-19T16:45:00Z",
      "ip_address": "86.247.xxx.xxx",
      "user_agent": "Mozilla/5.0..."
    }
  ],
  "certificate": {
    "authority": "Certinomis",
    "level": "Advanced Electronic Signature",
    "format": "PAdES-B",
    "timestamp_authority": "Certinomis TSA"
  },
  "completed_at": "2026-02-19T16:45:00Z"
}

Cancelling a signature

Cancel a pending or in-progress signature:

Code
 
curl -X POST https://api.faireplace.com/api/leases/{lease_id}/signature/cancel \
  -H "Authorization: Bearer $TOKEN"

Cancelling does not refund the signature credit.

eIDAS compliance

FairePlace electronic signatures meet the Advanced Electronic Signature (AdES) level under the EU eIDAS regulation:

Requirement	Implementation
Uniquely linked to signer	OTP sent to signer's personal mobile phone
Capable of identifying signer	Identity verified via phone number + email
Under sole control of signer	OTP valid for 5 minutes, 3 attempts max
Linked to data integrity	PAdES-B embedded signature with SHA-256 hash
Certificate Authority	Certinomis (French qualified trust service provider)
Timestamp	Qualified timestamp from Certinomis TSA
Proof archive	JSON proof file with all verification details

Error handling

Insufficient credits

Code
 
{
  "error": {
    "code": 402,
    "type": "PAYMENT_REQUIRED",
    "message": "Insufficient signature credits",
    "details": {
      "credits_required": 1,
      "credits_available": 0
    }
  }
}

Fix: Purchase credits via Payments & Credits.

OTP expired

If a signer's OTP expires, you can resend it:

Code
 
curl -X POST https://api.faireplace.com/api/leases/{lease_id}/signature/resend-otp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signer_email": "[email protected]"
  }'

Invalid phone number

Code
 
{
  "error": {
    "code": 422,
    "type": "VALIDATION_ERROR",
    "message": "Invalid phone number for signer",
    "details": {
      "signer": "Marie Martin",
      "phone": "+336987",
      "message": "Phone number must be a valid international format"
    }
  }
}

---

Related

• Create a Lease End-to-End — Full workflow including signature
• Payments & Credits — Purchase signature credits
• Leases API — PDF generation and signature endpoints