FairePlace Property Management API

Workers

Endpointhttps://api.faireplace.com/api

Endpoints reserved for Cloudflare workers (signature-orchestrator, etc.).

These endpoints use API key authentication (X-API-Key) instead of JWT Bearer tokens. They allow workers to:

Update individual signature statuses
Finalize signature documents
Synchronize state between workers and the database

Complete an individual signature (Worker)

POST

https://api.faireplace.com/api

/leases/signatures/{document_signature_id}/complete/{signer_type}

Updates the status of an individual signature_request as "COMPLETED" in the database.

Usage

This endpoint is called by the signature-orchestrator (Cloudflare worker) when an individual signer has completed their signature. It synchronizes the signature state in the database in real time.

Signature flow

A signer completes their signature in the signature-orchestrator
The signature-orchestrator calls this endpoint to update the database
The corresponding signature_request is updated with COMPLETED status
If all signers have completed, the signature-orchestrator calls /finalize

Authentication

This endpoint uses an API key (X-API-Key) instead of a JWT Bearer token. Only authorized workers can call this endpoint.

Benefits

Real-time traceability: Each signature is recorded upon completion
Consistent state: The database reflects the actual state at each step
Robustness: If the process fails, already completed signatures are saved
Visibility: The state of each individual signature can be viewed

Prerequisites

The signature document must exist
A signature_request must exist for this document and this signer_type
The tenant_id must be provided in the X-Tenant-ID header

Complete an individual signature (Worker) › path Parameters

document_signature_id

string · uuid · required

Signature document ID

signer_type

string · enum · required

Signer type that has completed their signature

Enum values:

proprietaire

locataire

agent_immobilier

Complete an individual signature (Worker) › Request Body

Request to complete an individual signature. This endpoint is called by the signature-orchestrator when an individual signer has finished their signature. It updates the status of the corresponding signature_request in the database.

signature_hash

string | null

Signature hash for traceability (optional)

Example: abc123def456...

Complete an individual signature (Worker) › Responses

Signature request completed successfully

Response after completing an individual signature. This response confirms that the signature_request has been updated with COMPLETED status in the database.

success

boolean · required

Indicates whether the completion succeeded

Example: true

message

string · required

Confirmation message

Example: Signature request completed successfully

document_signature_id

string · uuid · required

Signature document ID

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

signer_type

string · enum · required

Type of the signer who completed their signature

Enum values:

proprietaire

locataire

agent_immobilier

Example: proprietaire

signature_request_id

string · uuid · required

Updated signature_request ID

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

POST/leases/signatures/{document_signature_id}/complete/{signer_type}

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/:document_signature_id/complete/:signer_type \
  --header 'Content-Type: application/json' \
  --data '
{
  "signature_hash": "abc123def456..."
}
'

shell

Example Request Body

{
  "signature_hash": "abc123def456..."
}

json

application/json

Example Responses

{
  "success": true,
  "message": "Signature request completed successfully",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signer_type": "proprietaire",
  "signature_request_id": "550e8400-e29b-41d4-a716-446655440001"
}

json

application/json

Finalize a signature document (Worker)

POST

https://api.faireplace.com/api

/leases/signatures/{document_signature_id}/finalize

Finalizes a signature document and activates the lease if all signatures are complete.

Usage

This endpoint is called by the signature-orchestrator (Cloudflare worker) when all signers have completed their signatures. It verifies that all signature_requests are complete and activates the lease if so.

Finalization flow

All signers have completed their signatures (via /complete/{signer_type})
The signature-orchestrator calls this endpoint to finalize the document
The system verifies that all signature_requests are in COMPLETED status
If all are complete:
- The document is marked as COMPLETED
- The lease changes to ACTIVE status
- A finalization event is published
If some signatures are not complete, the document is marked as COMPLETED but the lease remains in PENDING_SIGNATURE

Authentication

This endpoint uses an API key (X-API-Key) instead of a JWT Bearer token. Only authorized workers can call this endpoint.

Important note

The signature_requests must be updated individually via /complete/{signer_type} before calling this endpoint. This endpoint does not update the signature_requests, it only verifies them.

Prerequisites

The signature document must exist
All signature_requests must be in COMPLETED status (updated individually)
The tenant_id must be provided in the X-Tenant-ID header
The final signed PDF URL must be provided

Finalize a signature document (Worker) › path Parameters

document_signature_id

string · uuid · required

Signature document ID to finalize

Finalize a signature document (Worker) › Request Body

Request to finalize a signature document. This endpoint is called by the signature-orchestrator when all signers have finished their signatures. It verifies that all signatures are complete and activates the lease if so.

signed_pdf_url

string · uri · required

URL of the final signed PDF (containing all signatures)

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

archive_url

string | null · uri

URL of the archived PDF with timestamping (optional)

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

Finalize a signature document (Worker) › Responses

Signature document finalized successfully

Response after finalizing a signature document. This response confirms that the document has been finalized and that the lease has been activated if all signatures were complete.

success

boolean · required

Indicates whether the finalization succeeded

Example: true

message

string · required

Confirmation message

Example: Document signature finalized successfully

document_signature_id

string · uuid · required

Finalized signature document ID

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

POST/leases/signatures/{document_signature_id}/finalize

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/:document_signature_id/finalize \
  --header 'Content-Type: application/json' \
  --data '
{
  "signed_pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440003",
  "archive_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440004"
}
'

shell

Example Request Body

{
  "signed_pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440003",
  "archive_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440004"
}

json

application/json

Example Responses

{
  "success": true,
  "message": "Document signature finalized successfully",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000"
}

json

application/json

Signatures Lessees

FairePlace Property Management API

Workers

Endpointhttps://api.faireplace.com/api

Endpoints reserved for Cloudflare workers (signature-orchestrator, etc.).

These endpoints use API key authentication (X-API-Key) instead of JWT Bearer tokens. They allow workers to:

Update individual signature statuses
Finalize signature documents
Synchronize state between workers and the database

Complete an individual signature (Worker)

POST

https://api.faireplace.com/api

/leases/signatures/{document_signature_id}/complete/{signer_type}

Updates the status of an individual signature_request as "COMPLETED" in the database.

Usage

Signature flow

A signer completes their signature in the signature-orchestrator
The signature-orchestrator calls this endpoint to update the database
The corresponding signature_request is updated with COMPLETED status
If all signers have completed, the signature-orchestrator calls /finalize

Authentication

This endpoint uses an API key (X-API-Key) instead of a JWT Bearer token. Only authorized workers can call this endpoint.

Benefits

Real-time traceability: Each signature is recorded upon completion
Consistent state: The database reflects the actual state at each step
Robustness: If the process fails, already completed signatures are saved
Visibility: The state of each individual signature can be viewed

Prerequisites

The signature document must exist
A signature_request must exist for this document and this signer_type
The tenant_id must be provided in the X-Tenant-ID header

Complete an individual signature (Worker) › path Parameters

document_signature_id

string · uuid · required

Signature document ID

signer_type

string · enum · required

Signer type that has completed their signature

Enum values:

proprietaire

locataire

agent_immobilier

Complete an individual signature (Worker) › Request Body

signature_hash

string | null

Signature hash for traceability (optional)

Example: abc123def456...

Complete an individual signature (Worker) › Responses

Signature request completed successfully

Response after completing an individual signature. This response confirms that the signature_request has been updated with COMPLETED status in the database.

success

boolean · required

Indicates whether the completion succeeded

Example: true

message

string · required

Confirmation message

Example: Signature request completed successfully

document_signature_id

string · uuid · required

Signature document ID

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

signer_type

string · enum · required

Type of the signer who completed their signature

Enum values:

proprietaire

locataire

agent_immobilier

Example: proprietaire

signature_request_id

string · uuid · required

Updated signature_request ID

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

POST/leases/signatures/{document_signature_id}/complete/{signer_type}

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/:document_signature_id/complete/:signer_type \
  --header 'Content-Type: application/json' \
  --data '
{
  "signature_hash": "abc123def456..."
}
'

shell

Example Request Body

{
  "signature_hash": "abc123def456..."
}

json

application/json

Example Responses

{
  "success": true,
  "message": "Signature request completed successfully",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signer_type": "proprietaire",
  "signature_request_id": "550e8400-e29b-41d4-a716-446655440001"
}

json

application/json

Finalize a signature document (Worker)

POST

https://api.faireplace.com/api

/leases/signatures/{document_signature_id}/finalize

Finalizes a signature document and activates the lease if all signatures are complete.

Usage

Finalization flow

All signers have completed their signatures (via /complete/{signer_type})
The signature-orchestrator calls this endpoint to finalize the document
The system verifies that all signature_requests are in COMPLETED status
If all are complete:
- The document is marked as COMPLETED
- The lease changes to ACTIVE status
- A finalization event is published
If some signatures are not complete, the document is marked as COMPLETED but the lease remains in PENDING_SIGNATURE

Authentication

This endpoint uses an API key (X-API-Key) instead of a JWT Bearer token. Only authorized workers can call this endpoint.

Important note

The signature_requests must be updated individually via /complete/{signer_type} before calling this endpoint. This endpoint does not update the signature_requests, it only verifies them.

Prerequisites

The signature document must exist
All signature_requests must be in COMPLETED status (updated individually)
The tenant_id must be provided in the X-Tenant-ID header
The final signed PDF URL must be provided

Finalize a signature document (Worker) › path Parameters

document_signature_id

string · uuid · required

Signature document ID to finalize

Finalize a signature document (Worker) › Request Body

signed_pdf_url

string · uri · required

URL of the final signed PDF (containing all signatures)

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

archive_url

string | null · uri

URL of the archived PDF with timestamping (optional)

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

Finalize a signature document (Worker) › Responses

Signature document finalized successfully

Response after finalizing a signature document. This response confirms that the document has been finalized and that the lease has been activated if all signatures were complete.

success

boolean · required

Indicates whether the finalization succeeded

Example: true

message

string · required

Confirmation message

Example: Document signature finalized successfully

document_signature_id

string · uuid · required

Finalized signature document ID

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

POST/leases/signatures/{document_signature_id}/finalize

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/:document_signature_id/finalize \
  --header 'Content-Type: application/json' \
  --data '
{
  "signed_pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440003",
  "archive_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440004"
}
'

shell

Example Request Body

{
  "signed_pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440003",
  "archive_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440004"
}

json

application/json

Example Responses

{
  "success": true,
  "message": "Document signature finalized successfully",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000"
}

json

application/json

Signatures Lessees