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.
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: 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.
Live | tg_live_… | Real orders. Reviewed, generated, and billed on your monthly statement. |
Sandbox | tg_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.
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 }curl -X PUT "<upload_url>" \
-H "Content-Type: application/pdf" \
--data-binary @booking-form.pdfcurl -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", … } }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"], … } }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": { "code": "invalid_request", "message": "product must be cover_only or cover_plus_agreement" } }| Status | code | When |
|---|---|---|
| 401 | unauthenticated | Missing, invalid, revoked, or wrong-environment key. |
| 403 | api_disabled | API access is not enabled for your firm, or the firm is suspended. |
| 400 | invalid_request | The body or parameters failed validation. |
| 404 | not_found | Order or document not found in your firm + environment. |
| 409 | conflict | An idempotency key was reused with a different payload, or an order with this reference is still open (in review or needs attention). |
| 409 | not_ready | A document was requested before the order reached ready. |
| 422 | unprocessable | Unsupported file type for the given source_type. |
| 429 | rate_limited | Per-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.
Upload a file
/api/v1/uploadsRequest 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.
content_typerequired | string | The file’s MIME type, e.g. application/pdf. |
source_typerequired | "pdf" | "docx" | "image" | The kind of document being uploaded. |
{ "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.
Create an order
/api/v1/ordersSubmit 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.
referencerequired | string | Your 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_instructions | string | Free text — special conditions and notes. Used only to interpret/fill fields and carried verbatim; never used to draft clauses. |
partner_metadata | object | Optional 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. |
Idempotency-Key | string | Optional. A retried request with the same key and identical body returns the original order instead of creating a duplicate. See Idempotency. |
{
"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" }
}{
"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"
}
}Get an order
/api/v1/orders/{id}Retrieve one order’s current status. Returns 404 if the order isn’t in your firm + environment.
{
"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.
List orders
/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.
{
"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
}Retry an order
/api/v1/orders/{id}/retryRecover 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.
booking_form | { source_path, source_type } | Optional replacement document. |
additional_instructions | string | Optional updated notes. |
At least one of the two is required.
Fetch documents
/api/v1/orders/{id}/documentsList 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.
{
"documents": [
{ "kind": "tenancy_agreement", "download_url": "https://…", "expires_in": 300 }
]
}
# One kind per order: "tenancy_agreement" for cover_plus_agreement, "cover" for cover_only./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.
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.
| status | Meaning | Next |
|---|---|---|
processing | Received; extracting and (once approved) generating. | in_review |
in_review | Awaiting the law firm's review. | ready · needs_attention · rejected |
needs_attention | Corrections needed. Recoverable — retry the same order. | in_review (via retry) |
ready | Approved and generated. Documents downloadable. | — (terminal, fixed) |
rejected | Will 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.
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 order | Result |
|---|---|
in_review, processing or needs_attention | 409 conflict. Wait for the decision, or fix a needs_attention order with Retry an order. |
rejected | 201, 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.