Setting up your organization

Your organization is the top-level container for everything you do in The Contractor Codex — clients, projects, quotes, contracts, invoices, and settings. It's also the brand wrapper: every page, PDF, and email your clients see is stamped with the org's name, logo, and accent color.

Step 1: Sign up

Go to /sign-up and create an account with email + password (or Google OAuth). The first time you sign in, you'll land on /org-setup, the one-time onboarding wizard.

If you ever get logged out mid-setup, sign back in at /sign-in and you'll return to wherever you left off.

Step 2: Name your business

The Business name field is the user-facing name that appears in your portal's header, on every PDF (quote, contract, signed agreement, invoice), and in every notification email. Use the name you'd write on a business card — not your legal entity name unless they're the same.

Examples:

• ✅ "Acme Plumbing"
• ✅ "Jane Smith Consulting"
• ❌ "Acme Plumbing & Heating Services LLC" (too long; the LLC suffix takes up header space)

You can change this anytime in Settings (under the Branding section).

Step 3: Upload a logo

A square PNG between 200x200 and 1024x1024 works best. The logo appears in:

• The portal header (left side, next to the business name)
• Every PDF (quote, contract, signed copy)
• Email notifications
• Browser tab favicon

Keep the background transparent if you can. The portal renders against both light and dark surfaces, so a transparent PNG avoids a white box around your mark.

Step 4: Pick an accent color

The accent color drives every button, link, badge, and active-state highlight throughout the portal. Pick the color from your brand identity — it doesn't need to match your logo exactly but should complement it.

Common picks:

• A saturated brand color (e.g., #e7c98b, the platform default)
• A muted version of your logo color if your logo is highly saturated

You'll see the accent applied immediately after saving. Change it as often as you want.

If you'd rather not choose, leave Match my theme's accent color on in Settings → Branding: each portal theme ships with its own accent and applies it everywhere until you set a custom color.

Step 5: Set your support email

The support email is two things at once:

• The contact address shown on client-facing pages, PDF footers, and "Contact us" links.
• The recipient address for every client-activity notification (quote accepted, contract signed, change requested, declined). If you set it, those emails go here instead of your login email.

Use a real, monitored inbox. Leave the field empty if you'd rather have client-activity notifications come to the email you signed in with.

The "From" address on outbound emails to your clients comes from your email-sending domain (Step 6), not from this field. Replies to those emails route to whatever inbox you've configured at your DNS host for the From address.

Step 6: (Optional) Connect a custom email domain

If you have your own domain (e.g., acmeplumbing.com), you can send portal emails from that domain instead of from the platform default. See Settings → Email Domain for the DNS records to add.

This is optional but strongly recommended for trust signaling — clients are far less likely to mark emails as spam when they come from your domain.

What happens after setup

The wizard saves your organization and creates two things automatically:

1. A Stripe Connect account (if you haven't already connected one) — see Connecting Stripe.
2. An admin user that's you — the first member of the org with full admin rights.

You'll be redirected to /admin, the admin dashboard, where you can start adding clients and sending quotes.

Step 7: Save your signature

Visit Settings → Signatures and save a signature (you can type your name, draw with mouse/finger, or both). After that, every quote and agreement you send is automatically pre-signed by you at compose time. The recipient opens an authorized document and their signature finalizes it; no separate countersign step.

You can change your saved signature any time. The next outgoing contract picks up the new one.

Bringing in your existing data

Coming from Jobber, Housecall Pro, QuickBooks, or a spreadsheet? Import Data at /admin/import takes a CSV export and turns it into records here. Three kinds are supported: clients, projects, and your price catalog. Files can be up to 5 MB and 5,000 rows; split anything bigger and import it in parts.

The flow is upload, map, check, confirm:

1. Upload the CSV and say what's in it.
2. Match your columns. The wizard fills in best guesses from the headers. Jobber and Housecall Pro exports, which split the name into First and Last columns, map cleanly, and company-only client rows are fine. Fix anything that looks wrong.
3. Check the file. You get an exact preview: how many rows will be imported, how many already exist and will be skipped (matched by client email or catalog code, so nothing gets doubled), and how many rows have problems and won't be imported. Problem rows are listed with their row numbers and can be downloaded as a CSV, so you can fix just those and import them separately.
4. Confirm. Nothing is created until you click Import. Once started, the import keeps running even if you leave the page.

Two things worth knowing:

• Import clients before projects. Each project row is matched to a client by email, so the client has to exist first.
• You can roll an import back. The batch page keeps a Roll back button that removes the records the import created, except any that already have real work attached (projects, invoices, documents, and so on stay). The page tells you how many were removed and how many were kept.

Each org can have multiple admins. Every admin sees the same clients, projects, and settings, with actions audit-logged per admin. Manage your admin team from Settings → Team at /admin/settings/team. See Team management below.

Changing org settings later

Everything from this wizard is editable later:

• Branding (name, logo, accent color, support email) → Settings
• Stripe connection → Settings → Stripe
• Email domain → Settings → Email Domain
• AI chat → Settings → Chat
• Calendar → Settings → Calendar

The wizard exists just to make first-run setup fast. Everything is reversible.

Billing entity details

When you fill out the org-setup wizard, you also tell the portal who you are as a business entity. This data is used by Stripe Tax (if enabled), by your subscription invoices for The Contractor Codex itself, and to populate KYC documents Stripe might request later.

The relevant fields, all in Settings → Billing Profile:

• Legal name — the name on your articles of incorporation. May differ from your business name (e.g., "ABC Holdings LLC" dba "Acme Plumbing").
• DBA — your doing-business-as name if different from legal.
• Entity type — sole_prop, llc, s_corp, c_corp, partnership, nonprofit, government, or other.
• EIN last 4 — last 4 digits of your federal tax ID (for sole prop, last 4 of SSN). The portal never stores the full number.
• Address — your business mailing address. Used for tax calculation by Stripe Tax (if enabled), and printed on your subscription invoices.
• Tax exemption — most orgs are none. If your business is sales-tax exempt (or international reverse-charge VAT applies), email support@contractorcodex.com with your exemption certificate and we'll set it up. There is no self-serve exemption field in the wizard.
• Accounts payable contact — name, email, phone of your billing/AP contact. The platform routes any billing questions about your subscription here.

You can fill these in later — they're not required to send quotes or invoices to your clients. They become required only if you enable Stripe Tax or run into a billing question.

Timezone

In Settings → Display, set your org's timezone. This drives:

• Display of timestamps throughout the admin portal.
• When recurring invoices fire (the cron uses the org's timezone to pick the right local day-of-month).
• Calendar event sync timing.

Overdue-invoice reminders are timed from each invoice's due date, not your timezone, so they are unaffected by this setting.

Default is America/Los_Angeles. Change to whatever city/region you operate in.

Team management — two different things

There are two "Team" concepts in The Contractor Codex. They live on different sides of the portal:

1. Client team (your customer's team)

Each Client (one of your customers) can have multiple CustomerMembers — different people from that company who all log in to their portal. For example, Acme Corp's CFO and AP manager might both need access to download invoices.

Clients manage their own team from /dashboard/settings/team in their portal:

• Owner invites teammates by email (14-day signup link).
• Owner can remove teammates.
• Owner status is held by whoever was first invited; promoting/demoting is currently a support-assisted action.

You don't manage this for them — they self-service from their dashboard. Your involvement is limited to support assistance if the owner asks for a promotion change.

2. Org admin team (your team)

Each Organization (your business) can have multiple OrganizationMembers — admins who log in to manage your portal. Same idea as client team, different table.

Manage your admin team from Settings → Team at /admin/settings/team:

• Invite a team member — only an org owner sees this form. Enter an email + optional first/last name, pick a role, and click Send invite. The invitee gets an email with a secure 14-day signup link.
• Pending invites show up in the list with an "Invite pending" pill. Owners can resend the link or remove the slot.
• Remove a member — owners see a Remove button on every row. Click to revoke access; their historical actions stay logged.
• MFA badge — members with multi-factor authentication enabled show a green MFA pill so you can audit at a glance.

The founder of the org is automatically the owner. There are three roles: owner (everything, including team, roles, and account), admin (view and edit everything, no owner controls), and viewer (read-only, good for a bookkeeper who should see invoices but change nothing). Owners change anyone's role from the role menu on their row, and the team page shows a full "what each role can do" table. See Team and access for the details.

Constraints

• At least one owner. You can't remove or demote the last owner. To remove yourself if you're the only owner, promote another member to owner first (the role menu on their row).
• Email already used as a client. If the email you're inviting is already a CustomerMember (a portal user on the client side) in any org, the invite is blocked. The auth resolver can't route the same Clerk user as both a customer and an admin.
• Self-invite. Inviting your own email is blocked — you're already a member.

Auto-created Stripe Connect account

The wizard creates a Stripe Connect Express account automatically the first time you save your org info. This is so you don't have to think about Stripe before you're ready to send your first quote. See Connecting Stripe for the rest of the onboarding.

The Express account is owned by Stripe (they handle compliance + payouts), with the platform as the connected-account host. You sign in to Stripe's hosted dashboard with the email you used during onboarding.

If you'd rather connect your existing Stripe account instead, skip the Express path and go to Settings → Stripe after wizard completion to OAuth into your existing account.

What "ready to send a quote" looks like

Before you can send your first quote, the portal needs:

• ✅ Business name set
• ✅ Logo uploaded (optional but recommended)
• ✅ Stripe Connect account onboarded (charges enabled)
• ✅ At least one client added (or just type an email in the quote composer)

If any of these are missing, the /admin page shows a banner telling you what's left. Click through to the relevant settings page to finish.

Common pitfalls

"My logo looks tiny on PDFs" — Upload at 512x512 or larger. The portal scales down for different surfaces but can't scale up cleanly.

"My accent color makes buttons unreadable" — Pick a color with at least 4.5:1 contrast against white text. Tools like https://webaim.org/resources/contrastchecker/ can verify.

"I can't change my org slug" — The slug (used in URLs like /admin/clients/<customer-slug>) is generated from your business name. To change it, contact support — slugs aren't user-editable to avoid breaking saved URLs.

"I want to delete my org" — Contact support. Deleting an org wipes all client data, contracts, invoices, and Stripe Connect account. We do it manually to prevent accidents.