TenancyPad
API docsContact
Developer reference · v1

Integration API

Submit a booking form from your own system, track it through our partner law firm’s review, and fetch the generated tenancy agreement — over a small, key-authenticated REST API.

Overview

The API exposes the same pipeline as the web app. Your system submits an order (a booking-form document, optional supporting files, and optional notes), we extract the details and our partner law firm reviews them, and once approved the documents are generated. You poll for status — or receive a webhook — and download the finished PDFs.

The API reads and formats; it never drafts legal language. Special conditions you send are carried through verbatim. Every request is scoped to your firm and environment — you can only ever see your own orders.

Base URL
https://dev.tenancypad.com/api/v1
Format
JSON over HTTPS
Auth
Bearer API key
Versioning
Path-based (/v1)

Authentication

Every request carries your secret key in the Authorization header. Keys look like tg_live_… or tg_sandbox_…. Keep them server-side — a key is a bearer credential and grants full access to your firm’s orders.

Authorization header
Authorization: Bearer tg_live_9f2a7c4e8b1d…

A firm admin creates, rotates, and revokes keys from your firm console — the full secret is shown once at creation and stored only as a hash, so save it then. Rotating or revoking a key stops it authenticating within seconds. Missing, invalid, revoked, or wrong-environment keys are rejected with 401 unauthenticated.

Environments

There are two environments in the same deployment, selected entirely by which key you use — there is no separate URL.

Environments
Livetg_live_…Real orders. Reviewed, generated, and billed on your monthly statement.
Sandboxtg_sandbox_…For building and testing. Runs the full lifecycle and returns a watermarked sample document — never billed, never on a statement, kept separate from live.

A live key can never see sandbox orders and vice versa. In sandbox you can force an error path for testing by sending additional_instructions of "simulate:needs_attention" or "simulate:rejected".

Quickstart

Five calls take you from a file to a finished document. Replace the host and key with your own.

1 — request an upload URL
curl -X POST https://dev.tenancypad.com/api/v1/uploads \
  -H "Authorization: Bearer tg_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "content_type": "application/pdf", "source_type": "pdf" }'

# → { "upload_url": "https://…", "source_path": "uploads/ab12…", "expires_in": 300 }
2 — upload the file bytes to the presigned URL
curl -X PUT "<upload_url>" \
  -H "Content-Type: application/pdf" \
  --data-binary @booking-form.pdf
3 — create the order
curl -X POST https://dev.tenancypad.com/api/v1/orders \
  -H "Authorization: Bearer tg_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: PNX-TEN-2026-000123" \
  -d '{
    "reference": "PNX-TEN-2026-000123",
    "product": "cover_plus_agreement",
    "booking_form": { "source_path": "uploads/ab12…", "source_type": "pdf" },
    "additional_instructions": "Special conditions: 2 months advance rental waived."
  }'

# → { "order": { "id": "9f2a4c7e-1b3d-4a5e-8c6f-0d1e2f3a4b5c", "status": "processing", … } }
4 — poll status (or receive a webhook)
curl https://dev.tenancypad.com/api/v1/orders/9f2a4c7e-1b3d-4a5e-8c6f-0d1e2f3a4b5c \
  -H "Authorization: Bearer tg_live_…"

# → { "order": { "id": "9f2a4c7e-1b3d-4a5e-8c6f-0d1e2f3a4b5c", "status": "ready", "documents": ["tenancy_agreement"], … } }
5 — fetch the generated documents
curl https://dev.tenancypad.com/api/v1/orders/9f2a4c7e-1b3d-4a5e-8c6f-0d1e2f3a4b5c/documents \
  -H "Authorization: Bearer tg_live_…"

# → { "documents": [ { "kind": "tenancy_agreement", "download_url": "https://…", "expires_in": 300 } ] }

Errors

Errors use a consistent shape: an HTTP status plus a stable machine-readable code and a human-readable message. Rate-limit and validation errors are always distinguishable from auth errors by their code.

Error shape
{ "error": { "code": "invalid_request", "message": "product must be cover_only or cover_plus_agreement" } }
StatuscodeWhen
401unauthenticatedMissing, invalid, revoked, or wrong-environment key.
403api_disabledAPI access is not enabled for your firm, or the firm is suspended.
400invalid_requestThe body or parameters failed validation.
404not_foundOrder or document not found in your firm + environment.
409conflictAn idempotency key was reused with a different payload, or an order with this reference is still open (in review or needs attention).
409not_readyA document was requested before the order reached ready.
422unprocessableUnsupported file type for the given source_type.
429rate_limitedPer-firm rate or quota exceeded. Includes a Retry-After header.

Rate limits

Each firm has its own request rate limit and a quota on the expensive operation (creating an order). Exceeding either returns 429 rate_limited with a Retry-After header telling you how many seconds to wait. One firm’s limits never affect another firm’s availability.

Retry on 429 and 5xx with exponential backoff, honouring Retry-After when present.

Endpoints
Uploads

Upload a file

POST/api/v1/uploads

Request a short-lived presigned URL, then PUT the file bytes to it directly. This keeps large and multi-file uploads off the request body. Each file may be up to 25 MB; the page limit is enforced when the order is created.

Body parameters
content_typerequiredstringThe file’s MIME type, e.g. application/pdf.
source_typerequired"pdf" | "docx" | "image"The kind of document being uploaded.
Response 200
{ "upload_url": "https://…signed-put…", "source_path": "uploads/ab12…", "expires_in": 300 }

The source_path is single-use and short-lived — pass it to Create an order.

The 25 MB size cap is enforced on the direct PUT to storage (an S3 error if exceeded — not a /api/v1 response). The page-count limit is checked when the booking form is read during processing: an over-limit document surfaces as needs_attention with a reason, not a synchronous error at create.

Orders

Create an order

POST/api/v1/orders

Submit a new order. The order is attributed to your firm, extraction begins, and it enters our partner law firm’s review queue. The response returns immediately with a processing status.

Body parameters
referencerequiredstringYour own transaction id (e.g. the booking-form number). Unique per firm + environment among open orders; echoed on every read and webhook. Used to prevent duplicate orders. Once an order is rejected or ready you may send the same reference again — see Sending a reference again.
booking_formrequired{ source_path, source_type }The primary document (from an uploads call) plus its source_type (pdf/image/docx). The only document extracted.
product"cover_only" | "cover_plus_agreement"Defaults to cover_plus_agreement.
supporting_documents[{ source_path, label? }]Optional additional files (IC copies, prior agreement, floor plan) — shown to the law firm reviewing the order, not extracted. Attach your agent’s contact sheet with the label Agent Contact Info so the law firm can reach the agent directly if something on the form needs checking.
additional_instructionsstringFree text — special conditions and notes. Used only to interpret/fill fields and carried verbatim; never used to draft clauses.
partner_metadataobjectOptional reconciliation fields (agent_name, agent_id) echoed on reads and used for your monthly statement. Include agent_phone so the law firm can contact the agent if they have a question about the order.
Headers
Idempotency-KeystringOptional. A retried request with the same key and identical body returns the original order instead of creating a duplicate. See Idempotency.
Request body
{
  "reference": "PNX-TEN-2026-000123",
  "product": "cover_plus_agreement",
  "booking_form": { "source_path": "uploads/ab12…", "source_type": "pdf" },
  "supporting_documents": [
    { "source_path": "uploads/cd34…", "label": "Tenant IC" }
  ],
  "additional_instructions": "Special conditions: diplomatic clause applies.",
  "partner_metadata": { "agent_name": "Agent A", "agent_id": "P001", "agent_phone": "+60 12-345 6789" }
}
Response 201
{
  "order": {
    "id": "9f2a4c7e-1b3d-4a5e-8c6f-0d1e2f3a4b5c",
    "reference": "PNX-TEN-2026-000123",
    "status": "processing",
    "product": "cover_plus_agreement",
    "environment": "live",
    "price_sen": 9900,
    "created_at": "2026-08-29T04:12:00Z"
  }
}
Orders

Get an order

GET/api/v1/orders/{id}

Retrieve one order’s current status. Returns 404 if the order isn’t in your firm + environment.

Response 200
{
  "order": {
    "id": "9f2a4c7e-1b3d-4a5e-8c6f-0d1e2f3a4b5c",
    "reference": "PNX-TEN-2026-000123",
    "status": "in_review",
    "product": "cover_plus_agreement",
    "environment": "live",
    "price_sen": 9900,
    "partner_metadata": { "agent_name": "Agent A", "agent_id": "P001" },
    "created_at": "2026-08-29T04:12:00Z",
    "updated_at": "2026-08-29T04:18:00Z",
    "documents": []
  }
}

price_sen is the firm’s snapshotted price for the order (integer sen). reason is included only when the status is needs_attention or rejected (the law firm’s note) — otherwise the field is absent. documents lists the document kinds available once the order is ready — a single kind per order (tenancy_agreement for cover_plus_agreement, cover for cover_only).

An order created by sending a reference again also carries previous_order_id (the order it follows) and link_kind: resent_after_reject or correction. Both fields are absent on every other order, so existing integrations need no change.

Orders

List orders

GET/api/v1/orders?status=&reference=&limit=&cursor=

List your firm’s orders, most recent first, scoped to the key’s environment. Filter by reference to look up a specific booking-form number.

Response 200
{
  "orders": [
    { "id": "9f2a4c7e-1b3d-4a5e-8c6f-0d1e2f3a4b5c", "reference": "PNX-TEN-2026-000123", "status": "ready",
      "product": "cover_plus_agreement", "environment": "live", "price_sen": 9900,
      "created_at": "2026-08-29T04:12:00Z", "updated_at": "2026-08-29T05:03:00Z" }
  ],
  "next_cursor": null
}
Orders

Retry an order

POST/api/v1/orders/{id}/retry

Recover an order that came back needs_attention. Supply a corrected booking-form upload and/or updated instructions (at least one), on the same order id, to return it to review. A new upload replaces the source and re-runs extraction; instructions-only returns the existing document to re-review. Only works before generation — a rejected order is terminal and cannot be retried.

Body parameters
booking_form{ source_path, source_type }Optional replacement document.
additional_instructionsstringOptional updated notes.

At least one of the two is required.

Documents

Fetch documents

GET/api/v1/orders/{id}/documents

List the downloadable documents for a ready order. Each download_url is a short-lived signed link — fetch it fresh each time rather than storing it.

Response 200
{
  "documents": [
    { "kind": "tenancy_agreement", "download_url": "https://…", "expires_in": 300 }
  ]
}
# One kind per order: "tenancy_agreement" for cover_plus_agreement, "cover" for cover_only.
GET/api/v1/orders/{id}/documents/{kind}

Fetch one document. By default responds with a 302 redirect to a fresh signed URL; send Accept: application/json to get { download_url, expires_in } instead. Returns 409 not_ready if the order hasn’t reached ready. Because API firms are invoiced, documents are downloadable as soon as the order is ready — there is no payment step. In sandbox, a watermarked sample is returned.

Concepts

Order lifecycle

Every order moves through these states. The law firm’s review is a mandatory gate — nothing is generated until an order is approved.

statusMeaningNext
processingReceived; extracting and (once approved) generating.in_review
in_reviewAwaiting the law firm's review.ready · needs_attention · rejected
needs_attentionCorrections needed. Recoverable — retry the same order.in_review (via retry)
readyApproved and generated. Documents downloadable.— (terminal, fixed)
rejectedWill not be generated.— (terminal)

Webhooks

Instead of polling, register one HTTPS callback URL from your firm console. We POST to it whenever an order changes to a notable status — primarily ready, plus needs_attention and rejected. Polling always remains available as a fallback.

Delivery — headers + body
POST <your callback URL>
X-TG-Signature: sha256=<hmac>
X-TG-Event-Id: evt_7c1d…

{
  "event_id": "evt_7c1d…",
  "event": "order.ready",
  "order_id": "9f2a4c7e-1b3d-4a5e-8c6f-0d1e2f3a4b5c",
  "reference": "PNX-TEN-2026-000123",
  "status": "ready",
  "occurred_at": "2026-08-29T05:03:00Z"
}

The body carries identifiers and status only — never document bytes or tenancy-party PII. Verify the X-TG-Signature HMAC over the raw request body using your signing secret, and de-duplicate on event_id. Reply 2xx to acknowledge; non-2xx responses are retried with backoff. If your endpoint is down, reconcile via polling.

Idempotency

Order creation is safe to retry. Two mechanisms prevent duplicates:

Reference. reference is unique per firm + environment. Re-submitting the same reference with an identical payload returns the existing order (HTTP 200, with the full order object — the same shape as Get an order); a different payload returns 409 conflict.

Idempotency-Key header. For network-level retry safety, send an Idempotency-Key; a repeat with the same key and payload returns the original order rather than creating a new one. Reusing a key with a different payload is a 409 conflict.

“Same payload” compares the business fields — reference, product, additional_instructions, partner_metadata, and the supporting-document labels — not the single-use upload paths. So if you re-upload the file (getting a new source_path) before an identical retry, it still matches the original order rather than conflicting.

These rules apply while an order with that reference is open. Once it is rejected or ready, a new submission of the reference creates a new order — see Sending a reference again. Send a fresh Idempotency-Key for that new submission: reusing the original key with the same payload still returns the original order.

Sending a reference again

What happens when you submit a reference you have used before (same firm + environment):

Earlier orderResult
in_review, processing or needs_attention409 conflict. Wait for the decision, or fix a needs_attention order with Retry an order.
rejected201, a new order with link_kind: "resent_after_reject" and previous_order_id set to the rejected order. Charged as a normal order once ready.
ready (approved)201, a correction: link_kind: "correction", price_sen: 0 (not charged). The earlier order keeps status ready and its documents stay downloadable; use the correction’s documents once it is ready.

The new order is reviewed by the law firm like any other and follows the normal lifecycle and webhooks. Our reviewer sees what changed since the earlier order.

API Documentation