Customer Portal Widget
The ContractorScope AI customer portal lets your clients view their estimate, ask questions, approve the scope of work, and sign contracts — all without needing to create an account or install anything. The portal widget lets you embed this experience directly on your own website so clients never leave your brand.
This guide covers generating your embed code, configuring the widget's appearance, what clients see when they open the portal, and how the approval flow works.
What the Customer Portal Does
When a client receives an estimate link from you, they open a branded page that shows:
- A professional summary of the scope of work
- Itemized line items (with the option to hide pricing detail)
- AI Visualization images (if generated — see AI Visualization)
- A message thread so they can ask questions
- An Accept Estimate button that collects their electronic signature
- Optional: a deposit payment button (Stripe integration required)
Clients access the portal through a unique, secure link. No login required.
Embedding the Widget on Your Website
What the Widget Does
The customer portal widget is a small piece of embed code you add to your website. When a client visits a specific estimate link (generated by ContractorScope AI), the portal displays on your own domain instead of on contractorscopeai.com.
This keeps your brand front and center throughout the client experience.
Getting the Embed Code
- Go to Settings → Customer Portal.
- Click Widget Setup.
- Copy the embed code snippet.
The embed code looks like this:
<script
src="https://cdn.contractorscopeai.com/portal-widget.js"
data-company-id="YOUR_COMPANY_ID"
defer
></script>
Adding the Code to Your Website
Paste the embed code into the <head> or just before the closing </body> tag of every page on your site. If you use a website builder:
| Platform | Where to paste |
|---|---|
| WordPress | Appearance → Theme Editor → header.php, or use a "Header & Footer Scripts" plugin |
| Wix | Settings → Advanced → Custom Code → Head section |
| Squarespace | Settings → Advanced → Code Injection → Header |
| Webflow | Project Settings → Custom Code → Head Code |
| Shopify | Online Store → Themes → Edit Code → theme.liquid |
If you are not comfortable editing your website code, share the embed snippet with your web developer or web hosting support team. It is a one-time, two-minute task.
Once the code is on your site, ContractorScope AI handles the rest. When you send a client their estimate link, the portal loads on your domain automatically.
Lead Capture Embed Form
In addition to the portal, you can embed a lead-capture form on your website so prospective customers can request a callback. New leads land directly in your account, and your AI phone assistant (Scout) can follow up — see Voice Assistant.
Getting the Form Embed Code
- Go to Settings → Customer Portal.
- Open the Lead Capture section and copy the form embed snippet.
The snippet includes a secure embed token that ties every submission to your company. This token is required — it is how ContractorScope AI knows which account a new lead belongs to. Use the code exactly as provided; do not edit or remove the token.
Each lead-capture snippet is tied to your account through its embed token. Always copy your snippet from Settings → Customer Portal. A form without a valid token will not create leads.
Optional Snippet Settings
The JavaScript version of the form snippet looks like this:
<div id="contractorscope-contact-form"></div>
<!-- Optional: data-site="your-website-com" tags each lead with this website; data-project-types="Water damage,Fire & smoke,Mold,Storm damage,Other" sets the project-type list. -->
<script
src="https://YOUR_BACKEND_URL/api/v1/leads/contact-form-embed.js"
data-embed-token="YOUR_TOKEN"
data-container="contractorscope-contact-form"
data-autoheight="on"
async
></script>
You can add these optional settings to the <script> line:
| Setting | What it does |
|---|---|
data-autoheight="on" | Sizes the form's frame to fit the form, so there is no inner scrollbar and no empty space below it. Already on in the snippet we generate. Remove it to keep a fixed 600px-tall frame. |
data-site="your-website-com" | Tags every lead from this page with your website's name, so you can tell which of your sites a lead came from, and your assistant can mention it on the call. Use lowercase letters, numbers, dots, dashes or underscores (up to 64). |
data-project-types="Water damage,Fire & smoke,Mold,Storm damage,Other" | Replaces the project-type dropdown on this page with your own list, separated by commas (up to 12 types, 40 characters each). Handy when one website covers different work than another. |
data-brand="#1d4ed8" | Sets the button and accent color. A very light color that white text can't be read on is ignored, and the form keeps its default color. |
If you embed the plain HTML iframe version instead, it can't resize itself: it stays 600px tall and the form scrolls inside it when needed.
What Leads See and Agree To
The form is a single short screen: first and last name, phone number, project type, a description, the project address (with suggestions as they type), and an optional email. Visitors don't have to give an email address to send a request.
When a homeowner fills out the form, they see a consent disclosure before submitting. It tells them, in plain language, that by submitting they agree to be contacted — including by an automated / AI phone call (a TCPA-style consent notice). Submitting the form is their consent to that follow-up.
The form also has built-in protections so you only get real leads:
- Automated bot submissions are quietly filtered out.
- A repeat submission from the same phone number within 24 hours is ignored, so you don't get duplicates.
- Submitted details are cleaned up before they reach your account.
There is nothing extra to configure for these protections — they are always on.
Project Types on Your Lead Form
The lead-capture form asks visitors to pick a project type from a dropdown. By default, every account uses our standard list (Bathroom Remodel, Kitchen Remodel, Basement Finishing, and so on). If your business does different kinds of work, you can add your own project types alongside the standard list:
- Go to Settings → Lead capture & embeds.
- Open Project types on your lead form.
- Type a label and click Add. The first one you add is appended to the full 10-item standard list (it does not replace it), so you start at 11 — up to 12 project types total, 40 characters each, which leaves room for 2 additions before you hit the cap.
- Once you've added your first project type, a Remove button appears next to every row (standard or custom) so you can remove any of them.
- Click Use defaults at any time to go back to our standard list.
Leaving this alone (never adding anything) keeps the standard list — you don't need to touch this section unless you want to customize it.
Configuring the Widget
Appearance Settings
Customize how the portal looks to match your brand:
- Go to Settings → Customer Portal → Appearance.
- Configure:
| Option | Description |
|---|---|
| Logo | Upload your company logo. Appears at the top of the portal. |
| Primary Color | Sets button and accent colors. Enter a hex code or use the color picker. |
| Font | Choose from 6 professional fonts. Default is system font for fastest loading. |
| Background | Light or dark background theme. |
| Hide Itemized Prices | Shows scope of work but not individual line item prices — only the total. |
| Show Project Images | Toggle whether AI Visualization images appear in the portal. |
- Click Save. Changes apply immediately to all future estimate views (and to currently open portal sessions on next refresh).
Notification Settings
Configure when you receive notifications about client activity:
- Go to Settings → Customer Portal → Notifications.
- Toggle notifications for:
- Client viewed the estimate
- Client sent a message
- Client accepted the estimate
- Client declined the estimate
- Client requested a change
- Choose delivery method: Email, SMS, or both.
Customer-Facing Estimate Views
What the Client Sees
When a client opens their estimate link, they see:
- Header — Your logo and company name.
- Estimate summary — Client name, property address, estimate number, and date.
- Scope of work — Grouped line items with descriptions. Item prices are shown or hidden based on your settings.
- Project images — If you generated AI Visualization images, they appear here with a before/after comparison.
- Total — The estimate total, tax (if applicable), and any deposit amount.
- Message thread — A chat-style message area where the client can ask questions.
- Action buttons — Accept, Decline, or Request Changes.
Mobile Experience
The customer portal is fully responsive. Clients opening the link on a phone or tablet see a clean, single-column layout optimized for small screens. The accept button is large and prominent.
Estimate Link Expiration
By default, estimate links expire 90 days after the estimate was created. You can change this per estimate or set a default:
- Per estimate: Open the estimate → click Share → set a custom expiration date.
- Default: Go to Settings → Customer Portal → set Default Link Expiration.
If a client tries to open an expired link, they see a message asking them to contact you for a refreshed link.
Approval Flows
How a Client Accepts an Estimate
- The client reviews the scope of work and total.
- They click Accept Estimate.
- A signature panel appears. The client types their full name and clicks I Agree and Sign.
- The signed estimate is recorded in ContractorScope AI with a timestamp and IP address.
- You receive an instant notification (email and/or SMS based on your settings).
- The estimate status changes to Accepted in your dashboard.
Electronic Signature
The client's typed name and timestamp constitute the electronic acceptance. The signed record includes:
- Client name as typed
- Date and time (UTC)
- Client IP address
- Estimate number and version
You can download a PDF of the signed estimate from the estimate detail page. The PDF includes a signature block at the bottom.
Collecting a Deposit
Deposit collection pays out directly to your own connected Stripe account (not ContractorScope's) — so before you can require a deposit, you need to activate payments once:
- Go to Settings → Deposits.
- Click Activate payments. This creates a Stripe Connect account for your company and sends you through Stripe's hosted onboarding (business details, bank account for payouts).
- Once Stripe confirms onboarding is complete, the deposit settings unlock.
With payments activated, require a deposit as part of the acceptance flow:
- Open the estimate.
- Click Payment Settings.
- Enable Require Deposit and enter the deposit amount or percentage.
- Save the estimate.
When the client clicks Accept Estimate, they are prompted to pay the deposit via Stripe before the acceptance is finalized. The deposit is a destination charge routed straight to your connected Stripe account (no platform fee) and appears in your own Stripe dashboard, not ContractorScope's.
If you try to collect a deposit before finishing Stripe onboarding, the request is rejected
(connect_not_onboarded) rather than silently charging through ContractorScope's account. Finish
the Activate payments step in Settings → Deposits to clear this.
Requesting Changes
If the client clicks Request Changes, they can type a message describing what they want changed. This message appears in the estimate's message thread and triggers a notification to you.
After you update the estimate, resend the link. The client receives a new notification and can review the updated scope before accepting.
Next Steps
Once your portal is live, explore these related features: