Sending contracts for signature

Quotes and contracts are the same underlying record type in The Contractor Codex (a "Contract" with a kind field of quote, agreement, or change_order). Quotes are pricing offers; agreements are the long-form legal contracts.

This page covers sending an agreement-type contract.

Where contracts live

List: /admin/contracts — every contract you've sent, with filters by status, type, and signing provider.
Composer: /admin/contracts/new, the guided form where you build and send a new agreement or change order.
Templates: /admin/contracts/templates — reusable contract bodies you can spin up per client.
Detail: /admin/contracts/<id> — the contract's full state: signers, audit log, attached PDF artifacts.
Per client: open a client and click their Contracts tab to see every quote and contract for that client, with statuses and open links.

Creating a contract

Agreements and change orders are both built in the composer at /admin/contracts/new. A few ways in:

Click New Contract at the top of /admin/contracts.
Open a template from /admin/contracts/templates and click Send for signature. The composer opens with that template already selected.
On a signed contract's detail page, click Create change order. The composer opens with the client, project, and original contract pre-filled and the type set to Change order.

Quotes are built in their own composer at /admin/quotes/new, which adds the line-item editor. If you open /admin/contracts/new from an old quote bookmark, it forwards you there automatically.

Your account starts with a library of ready-made templates, so the composer always has something to work from. If every template on your account has been deactivated, the composer sends you to /admin/contracts/templates/new to create one first.

The Details step

The composer has two steps, Details and Review, with a live preview alongside the form the whole time. On Details you set:

Contract type: New agreement or Change order.
Client: pick an existing client, or check Send to a new prospect and type their name and email (company optional). The client record is created when you send, so once the prospect signs you just add a project to start tracking work.
Add a co-signer (optional): a second person on the client side, like a spouse or business partner. Both signers get their own signing link at the same time, and the contract only completes after both have signed. See Multi-signer workflows.
Project (optional): linking a project fills in the project merge fields (name, description, budget) in the body.
Signing method: In-house signing or DocuSign. With DocuSign you can use one of your DocuSign templates, send a Markdown template through DocuSign, or upload a finished PDF (a lawyer-prepared contract, for example). See DocuSign integration.
Template: click Pick a template to open the picker, organized by category. Once picked, the template shows as a chip with Change and Edit actions. There's also a link to create a brand-new template at /admin/contracts/templates/new without leaving the flow.
Title: suggested automatically from the template name and client the first time both are set. Edit it freely; this is the name the client sees in their email and on the PDF.
Expires in (days): how long the signing link stays valid. Agreements default to 14 days; you can set anywhere from 1 to 120.
Your signature: agreements go out pre-signed by you (see Pre-signing below). Pick Saved, Typed, or Drawn. This card is hidden for change orders, since the signed parent carries your signature.

For change orders, three extra fields appear:

Original signed contract: the parent this change order amends. Only signed contracts for the selected client are listed. The parent stays intact; the change order is a separate document with its own signatures.
Change summary: a short description of what's changing. Required before you can review.
Edit the contract body: the parent's signed text loads into an editor so you amend it in place. The preview pane switches to a comparison view that highlights every line you added or removed, and Reset to parent discards your edits.

The live preview

The right-hand pane renders the contract exactly as the signer will read it, with merge fields filling in live as you pick the client, project, and title. Click Preview PDF to open the rendered document in a new tab. What you see is what gets frozen at send time; the body cannot change after sending.

Review and send

Continue to review unlocks once the required fields are set. The Review step shows a summary (recipient, project, type, provider, template, title, expiry) plus warnings for anything worth a second look: unresolved merge fields, a template that uses project fields with no project selected, a signing window shorter than 3 days. Tick I reviewed the recipient, template, title, expiry, and preview, then click Send for signature.

Building a reusable template

Templates are the contract bodies you send again and again: a service agreement, an NDA, a master services agreement. Write your own at /admin/contracts/templates/new, reachable from the New Template button on /admin/contracts/templates. A template has:

Name (required): shown in the picker, and used to suggest the contract title in the composer. Names must be unique; if you reuse one, the page asks for a different name.
Description (optional): an internal note about when to use the template. Clients never see it.
Category: which group the template appears under in the picker on /admin/contracts/new. Service work, Confidentiality, Barter and work trades, Project changes, Custom, or Universal for no specific group.
Industry (optional): files the template under that industry on the Starter library tab of the templates page.
Require company countersignature: with pre-signing at send time (the default), this checkbox rarely changes anything. Multi-signer workflows covers the cases where it still applies.

Writing the template body

The body is Markdown with merge fields. A live preview sits next to the editor (on narrow screens, switch between the Edit and Preview tabs) showing the template the way a signer will read it, including the signature and initials placeholders.

The Insert panel drops snippets at your cursor:

Signer fields: three buttons insert a signature line ({{signature:Client Signature}}), a signing date ({{date:Date Signed}}), and a required initials line ({{initial:Clause name}}). The signer fills these in on the signing page.
Merge fields: a dropdown grouped by Client, Project, Contract, Your business, and Billing terms. Each option inserts a field like {{customer.name}} or {{project.budget}} that fills in automatically when you send from /admin/contracts/new.
Clause library: inserts one of your saved clauses as a heading plus its text, ready to tailor. A starter set of clauses is loaded for you; manage them on the Clauses tab of the templates page.

A misspelled field stays as literal text in the sent contract, so test a new template by composing a contract and clicking Preview PDF before sending it to a real client.

Click Create template and it's immediately available in the composer's picker. Edits to a template later only affect future contracts; anything already sent keeps its frozen body.

Signers

Every contract has at least one signer (the client). You can add:

A co-signer, another person on the client side who also needs to sign.
A witness, typically a neutral third party.
A company signer (you), automatically populated at compose time using your saved signature.

For multi-signer flows, see Multi-signer workflows.

Pre-signing (your signature goes out with the contract)

Your signature is applied to every outgoing quote and agreement at the moment you click Send. The recipient opens a document that's already authorized by your side, and their signature becomes the only one needed to finalize it.

This means you don't have to do a separate "countersign" step after the client signs. As soon as they accept, the contract moves to signed and the final PDF is ready.

What you need to do once: save a signature at Settings → Signatures. After that, every outgoing quote and agreement uses it automatically. Both composers (quote and agreement) also have a signature pad in their UI so you can override the mode (typed vs drawn) per send if you want a different look on a specific document. The quote composer's pad is a sticky card on the right side under the Quote total; the agreement composer's pad is in the Review step before send.

The Send button is gated on a captured signature. You can't accidentally send an unsigned contract from the UI. If you switch to Typed mode with an empty name field, the button stays disabled until you fill it in.

Three exceptions where pre-sign doesn't fire:

Change orders. They amend a parent contract that's already signed; the parent's signatures carry the legal weight. The Sign as company pad isn't shown when you select Change Order from the composer.
MCP-sent contracts when the API key's owner has no saved signature. The send still goes through, but the response includes a warning string and the contract lands in awaiting_countersign after the customer signs. Save a signature once and future MCP sends ship pre-signed. See MCP server for the agent-side details.
Pre-rollout contracts. Anything sent before the pre-sign rollout that's still sitting in awaiting_countersign can still be manually countersigned from the contract detail page.

Per-admin signatures. Each admin has their own saved signature (scoped to their Clerk user ID). Whichever admin clicks Send is the one whose signature gets stamped on that contract.

The signing flow

When you click Send:

Your signature is stamped on the contract. A ContractSigner row with role="company" and status="completed" is created, the signature PNG uploads to storage, and ContractFieldValue rows are written for the company signature + date fields. All in one transaction; if it fails, the contract doesn't send.
Each signer gets an email with a unique signing link (/contracts/sign/<token> for agreements, /quotes/<token> for quotes).
The client clicks the link and lands on the signing page, branded and mobile-friendly. The PDF shows your signature already in place; the client column shows their printed name with a "Pending — accept via the link in this email" placeholder and an "Awaiting your acceptance" header at the top of the signature block.
They review the contract body, type their name or paste a saved signature, and sign.
Status moves to signed. The header on the PDF flips to "Signed and accepted" with both signatures filled in. Both parties get a copy emailed and the PDF is saved to the client's Documents tab.

What if I really do need a countersign step?

Some teams want the old "client signs, partner reviews, partner countersigns" workflow on purpose. Two ways to land there:

Don't save a signature on the admin account that's sending. Without a saved signature the UI Send button stays disabled, but contracts created and sent via MCP or the agent API will ship unsigned. They land in awaiting_countersign after the client signs and a different admin can countersign from the contract detail page.
Use the legacy countersign flow. Pre-rollout contracts that are sitting in awaiting_countersign still work the old way. The countersign UI on the contract detail page is unchanged for those.

See Multi-signer workflows for the use cases that warrant this and the per-template requiresCountersign flag's role (informational only — pre-sign at send time bypasses it).

Signing methods

On the signing page, the client picks one:

Type — type their name; the portal renders it in a cursive script for the signature.
Draw — sign with mouse or finger on a canvas. The drawn signature is saved as a PNG.
Use saved signature — if they've signed before and saved their signature, it's pre-loaded.

The signed PDF embeds the actual drawn or saved signature image, not just the typed name.

The audit trail

Every signature is captured with:

Timestamp (server-side, UTC)
IP address
User-agent string
A SHA-256 hash of the contract body at the moment of signing (signedBodyHash)
A SHA-256 hash of the signing token

When you mark a contract as signed, the portal generates two PDFs:

Signed PDF — the contract with all signatures embedded.
Audit PDF — a separate document listing every signer, timestamp, IP, UA, and hashes. Use this for legal disputes.

Both PDFs are downloadable from the contract detail page and are saved to the client's Documents tab.

Resending

If a signer hasn't acted in a few days, click Resend on the contract detail page. The signer gets a fresh email with the same signing link. The original link continues to work — no token rotation.

Voiding

If you need to pull back a contract, click Void on the detail page. Status moves to voided. The hosted signing page shows "This contract was voided." Voided contracts are kept in your list under the Closed filter.

Multi-org client switching

If a single client signs in to portals for more than one org, contracts follow them — they'll see all signed agreements across orgs in their dashboard, scoped per org.