Build a contractor agreement signing flow
You're onboarding contractors in your own product, and each one signs an independent contractor agreement before they start. Your AI coding tool builds the onboarding step and the signing page, and Esign Comply supplies the signing rules and keeps the sealed record of every signature.
Free plan: 10 live signatures a month and a full test mode. No card required.
Try a contractor agreement signing page
This is a real signing ceremony against the real Esign Comply API in test mode: type any name, click Sign agreement, and a sealed test record comes back.
This is a working signing screen, the kind your AI tool builds. Run it and watch the record being made on the right.
Each step the signer takes is reported from the browser straight to Esign Comply. Run the demo to see the steps for this flow, then the sealed record.
The demo runs at level L1, so no email is sent. The setup Esign Comply recommends for a contractor agreement is L2: the contractor also confirms a six-digit code that Esign Comply emails them.
The prompt that builds the contractor signing step
The Esign Comply prompt generator produced this for contract signing with an Independent Contractor Agreement, on Next.js App Router with Supabase and Vercel, under the U.S. Federal rule pack. Paste it into Cursor, Claude Code, v0, Lovable, Bolt or Replit. Your tool adds the agreement page, the acceptances table, the server confirmation and the webhook.
The generator's use case for this document is contract signing. IDs in angle brackets are placeholders that the prompt tells your tool to ask for, and {Company} is your company name. A prompt generated in your dashboard has all three filled in.
# Esign Comply integration: contract signing Prompt esc_prompt_08be9278b2e0 · blocks 2026.11 · guidance bundled · region US Jurisdictions: US-FED · mode auto You are adding legally significant signature flows to this Next.js App Router application (TypeScript, Supabase Auth and Postgres, deployed on Vercel). Esign Comply is the independent record keeper. You build every screen. The Esign Comply SDK observes the screens you build and seals the record. Follow this prompt exactly. If something here conflicts with existing code, or you are unsure how to implement a step, stop and ask. Do not invent API methods, packages, or legal wording. This prompt has four kinds of instruction. Keep them apart: - "Required for the record": build all of it. Esign Comply checks these. - "Your obligations": duties the law places on {Company}. Esign Comply does not check them. Build what code can do and list the rest in your report. - "Recommendations": suggestions. Ask the developer before applying any that changes the product. - "What you can send us": optional reports {Company} may file with Esign Comply. ## Context - Packages (the only ones that exist): `esigncomply` (server), `@esigncomply/browser` (client), `@esigncomply/react` (optional hooks). - API host: https://esigncomply.com/v1 - Environment variables (server only, never NEXT_PUBLIC_): ESIGNCOMPLY_API_KEY, ESIGNCOMPLY_WEBHOOK_SECRET - Profiles: contract = `<profile ID for contract>` - Documents: Independent Contractor Agreement = `<document ID for Independent Contractor Agreement>` - An ID in angle brackets does not exist yet. Ask the developer for it. Do not invent IDs. - Rule pack versions: 2026-11-21 (all selected packs). - Server SDK calls return `{ data, error }` and do not throw. Check `error` every time. ## Required for the record 1. Create every session on the server with the secret key. Send only `client_token` to the browser. 2. Read `required_steps` from the session and satisfy each one. Do not hard-code steps. 3. Show the notice text directly above the action button, in the same container, visible without scrolling at 390 x 844 (CR-04). 4. Every notice names the action button by its label and every document by its title (CR-02, CR-03). Each flow's wording is in its build step. 5. Links to documents must be underlined and use a colour that differs from the surrounding text with a contrast ratio of at least 3:1, and at least 4.5:1 against the background. Notice text is at least 14px and never lighter than body text (CR-05, CR-06). 6. Every typed-name field starts empty (CR-01). 7. Only one primary button inside the assent container. Any other action sits outside it (CR-07). 8. Serve each document at a stable page on this domain that renders the registered version fetched from Esign Comply, unmodified (CR-08). 9. Treat the browser result as untrusted. Grant access only after the server has confirmed the record with the secret key (step 4 below). 10. Pass an `Idempotency-Key` on session creation. ### Never - Never pre-check a box, auto-submit, or call `.click()` on the user's behalf. - Never treat sign-in, scrolling, or continued use as acceptance. - Never use "By continuing" or "By clicking below" wording. - Never put the secret key, or any call that uses it, in a client component. - Never proxy `@esigncomply/browser` calls through this application's server. - Never cache or copy document text into the repository. Always render the registered version. - Never write to `esign_acceptances` from the browser. - Never show "signed" or "accepted" in the interface before step 4 confirms it. - Never write or change the text of the Independent Contractor Agreement. ## Your obligations These are {Company}'s duties under the rule packs selected. Esign Comply lists them and does not perform, monitor, or verify them. The list is not exhaustive. US-FED · pack 2026-11-21 - Customer: where another law requires {Company} to keep a record, keep an accurate, accessible copy for that period, including after export (US-31); before offering a record in court, give the adverse party reasonable written notice and access to the record and declaration (US-38). Outside this codebase. ## Recommendations Esign Comply recommends the following. Ask the developer which to apply. - State in the contract notice that the signer agrees to sign electronically, give a way to decline, and show a review step before the final act (US-04, US-05). Already reflected in step 6. - Before a material update to a document takes effect, notify signers in advance and ask for a fresh acceptance (US-18). - Keep saving and printing open wherever a signed record is shown (US-29). - Where minors may sign, consider an age attestation checkbox: `ceremony.ageAttested({ checkbox })` (US-42). ## What you can send us Optional. Each report is sealed with Esign Comply's receipt time and marked as supplied by {Company}; Esign Comply does not verify it. Every field is optional and any text, JSON, or file is accepted. Reports never affect recording, and a failed one never blocks the user's action. Suggested `data` per type: `esc.supplements.types()`. - When the terms-update notice email is sent: `esc.supplements.create({ subject: { signer: signerId }, type: "notice.sent", rule_ids: ["US-18"], text, data: { channel: "email", template } })` - Anything else worth keeping (support ticket, screenshot, policy in force): type `note`, or omit `type`. Only wire these if the developer says yes. ## Build steps ### 1. Install and configure `npm install esigncomply @esigncomply/browser` Create `lib/esigncomply.ts`: ```ts import "server-only"; import { EsignComply } from "esigncomply"; export const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY!); ``` Keys go in `.env.local` and the Vercel project settings, never in chat. Run commands in the integrated terminal. Rules file: `.cursor/rules/esigncomply.mdc`. ### 2. Database (Supabase migration) ```sql create table public.esign_acceptances ( id uuid primary key default gen_random_uuid(), user_id uuid references auth.users(id) on delete cascade, signer_id uuid not null, record_id text not null unique, document_id text not null, version_id text not null, purpose text not null, signed_at timestamptz not null, created_at timestamptz not null default now() ); alter table public.esign_acceptances enable row level security; create policy "read own" on public.esign_acceptances for select using (auth.uid() = user_id); -- No insert, update, or delete policies. Only the service role writes. ``` Add `signer_id uuid unique` to the profile table. ### 3. Document pages Create `app/legal/[slug]/page.tsx` for `independent-contractor-agreement`. Resolve `current` on session creation only. Fetch with `esc.documents.versions.getContent(documentId, versionId)`; render, print and download by the exact version ID returned on the session; the cache key includes that ID. Render inside `<article data-esc-document>` and reject stale versions before the final action. Give users a real opportunity to read the terms. ### 4. Server confirmation (the only place access is granted) Server action `finishContract(recordId)`: - `const { data: record, error } = await esc.records.get(recordId);` - Require: no error; `record.status` is "recorded", "timestamped", or "anchored"; `record.signer.external_id` equals the signer ID this server put on the session; `record.livemode` equals `process.env.VERCEL_ENV === "production"`; the record lists the exact versions pinned in that session. - Only then mark the document signed, and insert one `esign_acceptances` row per document using the service-role client. - If checks are inconclusive, do not mark the document signed. Show: "We could not confirm whether your acceptance was recorded. Please wait while we check." Reconcile the existing session before requesting another act. ### 5. Webhook `app/api/esigncomply/webhook/route.ts`, Node.js runtime. Read the raw body, then `esc.webhooks.verify(rawBody, request.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!)`. Reject on failure with 400. Handle idempotently by `webhook-id`: - `record.completed`: upsert `esign_acceptances` (covers a browser that closed early). - `record.disputed`: flag the row and notify the admin email. - Ignore event types you do not recognise and return 200. Return 200 within 5 seconds. ### 6. Contract signing (`/contracts/[id]`) - Server: create a session with `profile: "<profile ID for contract>"`, `documents: [{ document: "<document ID for Independent Contractor Agreement>", version: "current" }]`, `context.purpose: "contract_signature"`, the signer's `external_id`, `name` and `email`, `class: "business"`. - Obtain `country` and applicable jurisdiction from the form/customer configuration; do not guess from IP. - Page layout, top to bottom: 1. The full session-pinned Independent Contractor Agreement rendered inline with download and print. Call `ceremony.presentDocument({ versionId, mode: "inline", container })`. 2. Email verification (CR-17): a "Send code" button calls `ceremony.verify.start({ method: "email_otp" })`; a 6-digit field calls `ceremony.verify.confirm({ code })`. Show the masked address returned by the API. Allow resend after 30 seconds. 3. Review line: "You are signing the Independent Contractor Agreement between {Company} and {signer name} as {signer name}." Record it with `ceremony.reviewPresented({ container })` (CR-13). 4. Assent container with: the notice "By typing your name and clicking Sign agreement, you agree to sign this agreement electronically and to be bound by it." (CR-12); an empty text field labelled "Type your full legal name" (CR-09); a primary button "Sign agreement"; a secondary text link "Decline" outside the container that calls `ceremony.cancel()`. 5. `ceremony.observeAssent({ region, typedName: nameField, submit })`, then `ceremony.complete()` from the click. - After completion, confirm on the server as in step 4, then show "Signed. A copy has been emailed to you by Esign Comply." with a link to `result.verifyUrl` and a "Download copy" link. - Do not render a signature image or a cursive font as the signature. ### 7. Errors - `ceremony.complete()` rejected with a rule ID: show the message, keep the form, do not retry automatically. - Network failure or 5xx: show "We could not confirm whether your acceptance was recorded. Please wait while we check." Reconcile the same session and idempotency key before requesting another act. Never proceed without a record. - `client_token_expired`: create a new session and re-attach. - `verification_failed`: start a new session; offer no way past verification. ## Verify before you report success 1. `npm run build` passes and no file under `app/**` marked "use client" imports `esigncomply` or reads ESIGNCOMPLY_API_KEY. 2. Run `npx esigncomply check --url http://localhost:3000/contracts/test`. Fix every finding marked "block", re-running until none is left. List every finding marked "warn" in your report. 3. Confirm by test that submitting with the name field empty does nothing, and that calling `finishContract` with a made-up record ID does not mark the document signed. 4. Report: files created or changed, anything in this prompt you did not implement and why, the conformance summary, each item under "Your obligations" with "built", "partly built", or "needs a process outside this codebase", and each recommendation with the developer's decision.
The six steps a contractor signature needs
Create a session with the recommended contract profile and the API returns these required_steps. They run in this order, and a record is sealed only when every one of them is on file.
A typed name with an emailed code
For a contractor agreement, Esign Comply recommends the typed-name method at level L2. The contractor types their full legal name, and Esign Comply confirms a one-time code sent to the email address your onboarding collected.
- MethodTyped name
- LevelL2, one-time code by email
- method: typedassurance_level: L2document_type: contractpurpose: contract_signature
- 01
The SDK attaches to the onboarding step
client.attachedThe signer seesThe agreement step of your onboarding flow, inside your product.
Esign Comply recordsThat the SDK attached on that page: its address, the SDK version, the viewport, the language and the time zone.
- 02
The agreement is shown
document.presented:<version_id>The signer seesThe Independent Contractor Agreement in full, with download and print.
Esign Comply recordsWhich version was on screen, by ID, with a hash of the rendered text checked against the version you registered.
- 03
The notice is captured
notice.capturedThe signer seesOne notice above the button: "By typing your name and clicking Sign agreement, you agree to sign this agreement electronically and to be bound by it."
Esign Comply recordsA snapshot of the assent area: its text, the button label, the links, and where the notice sat relative to the button.
- 04
The emailed code is confirmed
identity.verifiedThe signer seesA six-digit code in their inbox, sent by Esign Comply, and a field on your page to type it into.
Esign Comply recordsThat the contractor returned the code sent to the email address on the session, with the time Esign Comply confirmed it.
- 05
The contractor types their name
intent.capturedThe signer seesAn empty name field. Their profile name is not copied into it.
Esign Comply recordsThe name as typed, the labels on the field and the button, and that the input came from real user events.
- 06
The signing act
signature.appliedThe signer seesThe Sign agreement button, then your own confirmation screen once your server has checked the record.
Esign Comply recordsThe final act, sealed with a signed receipt. The API refuses to seal while an earlier step is missing.
The prompt adds a review line before the signing act and records it with ceremony.reviewPresented(). It also adds a Decline link outside the signing area that calls ceremony.cancel(), so a contractor who declines leaves no record.
What you build for contractor onboarding, and what Esign Comply handles
The agreement is one step in a flow you own. You decide what comes before it and what it unlocks. Esign Comply covers the signing rules and the record.
The onboarding flow
The steps around the agreement: profile, payout details, and the rule that work starts only after signing.
Nothing here. The agreement step is one page in a flow that stays yours.
The agreement text
Write the agreement, register it once, and publish a new version when the terms change. Register a statement of work as its own document when it needs a signature.
Keeps every version immutable and pins the exact one to each record by hash.
Who signs
Decide who signs for your company and whether they countersign in the app. Track both signatures on the contractor's row.
One session per signer on the same version, with a separate sealed record for the contractor and for your signatory.
The signing page
The viewer, the code field, the name field, the notice and the Sign agreement button, styled like the rest of onboarding.
The rules prompt for your AI tool, and the browser SDK that reports each step from the contractor's browser.
Unlocking work
Set the contractor to active in your database only after your server has confirmed the record.
GET /v1 with your secret key, and the signed record.completed webhook when the browser closed early.
Storing the signed copy
Stamp the name and date onto the PDF when you want one file per contractor, keep it in your storage, and show it on the contractor's profile.
Emails the contractor their copy with a verification link, and serves the evidence report and the evidence package for the record.
When the agreement changes
Publish the new version as a material change and ask active contractors to sign again.
GET /v1 reports the agreement as outstanding for each contractor who signed an earlier version.
The record you get for each contractor agreement
Every contractor who signs leaves one sealed record. It names the agreement version they were shown, and it sits where nobody on your team can change it.
What the sealed record holds
- The agreement version the contractor saw, by SHA-256 hash.
- The notice and the button label, captured from the page as rendered.
- The typed name, with the field's label and its empty starting state.
- The confirmed one-time code for the contractor's email address.
- The server time of each step, from attach to signing act.
- An ES256-signed receipt, an outside RFC 3161 timestamp and a place in the hash-chained ledger.
What you do with it
- Signed receiptKeep it on the contractor's rowStore the record ID and the receipt in your contractors table. The receipt ties your row to the sealed record.
- PDF, per recordEvidence reportDownload
GET /v1into the contractor's file: who signed, which version, by what method, and when each step happened./records /{id} /report - verify_urlVerification pageShow the verification link on the contractor's profile and in the copy you send them.
- ZIP, verifies offlineEvidence packageThe record, the receipt, the timestamp token, the ledger proof and the exact document bytes. Anyone you hand it to runs the open-source
esigncomply-verifywith no account and no network.
Build guides, stack guides and AI tools
Contractor onboarding is one use of a signing flow you own. These pages cover the rest of the build.
- Build guideBuild your own DocuSignThe full send-for-signature product: upload, signers, links, signing page, completed copies.Open
- Build guideBuild signing into your productSigning inside your own app, driven by your backend, with reusable templates.Open
- Stack guidesStep-by-step guides for your stackSession creation, the signing page and server confirmation on the framework you use.Open
- AI toolsBuild it with your AI toolWhere to paste the prompt and how to run the conformance check in each coding tool.Open
Questions about contractor agreement signing
How do I collect a signed contractor agreement inside my app?
Make the agreement a step of your onboarding. Your server creates a session with POST /v1/sessions when the contractor reaches that step, your page shows the agreement and attaches the browser SDK, and the contractor confirms an emailed code, types their name and clicks Sign agreement. Your server confirms the record before it marks the contractor active.
Server confirmationWhich signature method fits a contractor agreement?
A typed name with an emailed code. Esign Comply's guidance for contracts is the typed method at level L2: the contractor types their full legal name into an empty field, and Esign Comply confirms a one-time code sent to their email during the ceremony. A drawn signature is also supported.
Where is the signed contractor agreement stored?
In two places. Your app stores the record ID and the signed receipt on the contractor's row, plus a stamped PDF when you produce one. Esign Comply keeps the sealed record and serves the evidence report PDF and the evidence package for it, and emails the contractor a copy with a verification link.
Evidence and verificationDoes my company countersign?
Your flow decides. To countersign in the app, create a second session on the same document version for your signatory. Each signer gets a separate sealed record, and your app marks the agreement complete when it has confirmed both.
What happens when the contractor agreement changes?
Publish a new version and mark it as a material change. GET /v1/signers/{external_id}/status then reports the agreement as outstanding for every contractor who signed an earlier version, and your app asks them to sign the new one. The earlier records stay as they are.
Re-acceptance guideBuild contractor onboarding yourself. Leave the record to us.
Free plan: 10 live signatures a month and a full test mode. No card required.
DocuSign, Dropbox Sign and the other product names on this page are trademarks of their owners. Esign Comply is not affiliated with them.