Recipes

Contracts signed elsewhere

Keep signing in your own system and let Quarters mirror the envelope, the signature and the PDF.

Quarters renders, sends and signs tenancy agreements itself. An operator who already signs in another system, DocuSeal say, can keep doing so and let Quarters mirror it: the booking shows the agreement’s state, the signed PDF is archived with the record, and a signature confirms the booking exactly as one collected here would.

1. Switch the provider

Under Settings › Contracts choose “In another system, through the API” and name it. From that moment nothing in the dashboard sends a contract, and the write endpoints below accept your reports. Until it is switched they answer 409.

2. Notice the booking

Subscribe to reservation.created and reservation.updated. A booking that turns reserved and has requiresContract is the one to issue for. Read it in full: it carries the guest, the address, the owner and the money as agreed, which is everything the agreement must state.

3. Report the envelope

When your system has created it, PUT the agreement with status sent, your externalId and the signers, including the tenant’s signing link, so staff can copy it from the booking.

curl -X PUT "https://go.quarters.live/api/v1/reservations/7c02…/agreement" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "docuseal:1849213",
    "status": "sent",
    "signers": [
      {
        "role": "lessor",
        "name": "City Retreat B.V.",
        "email": "bookings@cityretreat.com",
        "status": "completed"
      },
      {
        "role": "lessee",
        "name": "Sofia Rossi",
        "email": "sofia@example.com",
        "status": "pending",
        "signingUrl": "https://docuseal.com/s/…"
      }
    ]
  }'

4. Report the signature

On completion PUT status completed with the provider’s document URL. Quarters confirms a reserved booking on that report and tells you so with reservation.updated. You do not change the booking status yourself.

curl -X PUT "https://go.quarters.live/api/v1/reservations/7c02…/agreement" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "docuseal:1849213",
    "status": "completed",
    "documentUrl": "https://docuseal.com/d/…/signed.pdf",
    "signers": [
      {
        "role": "lessee",
        "name": "Sofia Rossi",
        "email": "sofia@example.com",
        "status": "completed",
        "completedAt": "2026-09-09T08:12:40.000Z"
      }
    ]
  }'

Then archive the executed PDF: the bytes, not a link, so the contract outlives the provider’s retention and the dashboard can serve it.

curl -X PUT "https://go.quarters.live/api/v1/reservations/7c02…/agreement/document" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @signed.pdf

5. Answer a request from staff

Declines and failures are reported the same way, as status declined or failed with a reason, and shown on the booking. Staff can then press Request contract, which reaches you as an agreement.requested webhook; force is true when a live envelope should be re-issued.

The rules

• The same externalId updates the current envelope in place; a different one creates a new version and supersedes a live one, as a re-issue from the dashboard would.
• Signers are matched by role and never removed. Send only the party that changed if you like.
• declined, voided and failed are recorded and shown to staff; none of them changes the booking, and Quarters sends no email on any of them. Your system already talked to the parties.
• A report against a superseded version lands on that historical row and changes nothing about the current agreement or the booking. Finishing an old envelope after staff re-issued never confirms anything.