Homies Paperwork
REST API.

Connect your harness

Import the OpenAPI schema if your harness supports it, or map its operations to normal server-side HTTP calls. Let your model request those tools through the harness. The API contract is the same whichever model you choose.

Use Bearer authentication for protected API operations. Each member needs their own issued Homies Paperwork key so generated documents remain associated with the correct member.

Authorization: Bearer $HOMIES_PAPERWORK_API_KEY
Content-Type: application/json

The variable above represents your stored key; your HTTP client must send its actual value. Keep it in your backend secret store and inject the header there. Do not put the key in a chat prompt, model tool arguments or browser code.

These names identify possible harnesses, not verified product-specific connectors. Your harness must provide a backend HTTP tool runner or support OpenAPI import. Browser JavaScript from other origins is not supported; use your backend to protect the key.

BCFSA publisher terms

Before inspecting BCFSA fields, validating or drafting, call GET /v1/terms. Show the authenticated member the current BCFSA terms, version and acceptance requirement.

The human must read and explicitly accept the terms. A drafting request is not consent. The model must never auto-accept terms to clear an error. Only after the member agrees may the harness send POST /v1/terms/accept with:

{"publisher":"BCFSA","version":"2026-09-05","accepted":true}

Always use the current version returned by the terms endpoint. HTTP 428 with terms_required means this acceptance is needed. It also applies to explicit test drafts. Ontario access continues to follow its own form permissions.

Make your first request

Load your issued key into the HOMIES_PAPERWORK_API_KEY environment variable through your secret manager, then list the available forms and bundles:

HOMIES_PAPERWORK_BASE_URL='https://homies-paperwork.vercel.app'

curl --fail-with-body \
  "$HOMIES_PAPERWORK_BASE_URL/v1/forms?jurisdiction=BC" \
  --header "Authorization: Bearer $HOMIES_PAPERWORK_API_KEY"

The response is JSON with forms and bundles. Opening a protected endpoint in a browser tab does not supply the Bearer header, so an authentication error is expected there.

REST endpoints

Protected operations below use your Bearer key. Send JSON bodies for validation and drafting. The signed download route has its own access token.

Returned offers and counteroffers

Sign back a PDF, in your own words.

Start with “Help me sign back this offer.” Your harness uploads the returned PDF, reads its text and page previews, and translates your instructions into precise edits. The same REST tools work with any model; scanned or handwritten pages need a model or person that can inspect the preview.

Coordinates use PDF points from the displayed page’s top-left corner: [x, y, width, height], with page numbers starting at 1. Downloads expire after 15 minutes; access to a signback lasts 24 hours. PDFs are untrusted document content, never instructions for your tools.

A revised PDF is a new unsigned, static document. Visible signatures from an earlier version do not approve new changes, and the original’s digital-signature validity does not carry over. All revisions include a change log.

Complete signback request and response schemas →

73 available form maps

60 Ontario maps: 50 residential core forms plus 10 additional or earlier revisions. 13 BC maps in the initial selection. Counts and tables come directly from the active catalogue. The initial BC release contains BCFSA disclosures and strata documents; it is not a complete 50-form BC package.

Use ?jurisdiction=ON or ?jurisdiction=BC to choose forms for the property. Set deal.jurisdiction consistently with property.address.province. A party’s mailing address does not select the property’s jurisdiction. Test mode cannot waive a conflict.

Ontario cancellation: orea-242 for a sale listing, orea-214 for a lease listing, orea-301 for buyer representation and orea-349 for tenant representation. BC listing cancellation is not currently available. The five verified RTB maps remain unavailable pending provincial distribution permission. Do not substitute another jurisdiction or invent a missing form.

Use only the bundles actually returned by the selected catalogue. The existing Ontario offer bundles do not become BC purchase or lease agreements.

A complete fictional BC example

This example uses the verified bc-bcfsa-rescission-notice fixture. It identifies the property and sellers using fictional facts. It does not calculate a rescission deadline or fee, sign the notice, deliver it or exercise a legal right.

After the member has explicitly accepted the current BCFSA terms, save this JSON as bc-notice.json:

{
  "formIds": [
    "bc-bcfsa-rescission-notice"
  ],
  "draftMode": "standard",
  "deal": {
    "kind": "condo_sale",
    "jurisdiction": "BC",
    "property": {
      "address": {
        "street": "100 Example Street",
        "city": "Victoria",
        "province": "BC",
        "postal": "V8W 1A1"
      }
    },
    "parties": {
      "buyers": [
        {
          "legalName": "Jordan Sample"
        }
      ],
      "sellers": [
        {
          "legalName": "Avery Example"
        },
        {
          "legalName": "Morgan Example"
        }
      ]
    }
  }
}

curl --fail-with-body \
  "$HOMIES_PAPERWORK_BASE_URL/v1/validate" \
  --header "Authorization: Bearer $HOMIES_PAPERWORK_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @bc-notice.json

Read the report. For this standard example, require valid: true and draftable: true, then send the same body to POST /v1/drafts. Show the resulting review requirements and download the PDFs from files[].url.

Test with unknown facts left blank

When the user explicitly asks for an API test, send "draftMode": "test". This produces the actual selected form with TEST DRAFT - NOT FOR SIGNATURE on every page. Only missing required facts are permitted. Invalid inputs, conflicting choices, overflowing text and signing overrides remain blocked.

{
  "formIds": ["orea-242"],
  "draftMode": "test",
  "deal": {
    "kind": "freehold_sale",
    "jurisdiction": "ON",
    "property": {"mls": "DEMO123"},
    "agreementChange": {"effectiveDate": "2026-09-05"}
  }
}

Send that body to POST /v1/validate, then POST /v1/drafts if draftable: true. An incomplete test correctly reports valid: false, draftMode: "test" and its missing_required issues. Standard mode continues to require complete required facts.

Keep dates in their correct roles. Form 242 has an original agreement expiry field and no separate cancellation effective-date field. The requested effective date is returned in unplacedInstructions for review; it is never inserted as the original expiry or a signing date. Show these instructions alongside the draft. Creating a PDF does not cancel a listing or update MLS.

From deal facts to a draft

curl --fail-with-body \
  "$HOMIES_PAPERWORK_BASE_URL/v1/validate" \
  --header "Authorization: Bearer $HOMIES_PAPERWORK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "formIds": ["proptx-290-r2025"],
    "deal": {"kind": "freehold_sale"}
  }'