Managing Companies
Audience: Agency-success / Support / Sales · Where in app: /agency/companies (list, create, create-ghl, detail, edit, add-addon) · Plan availability: Agency tier (verify specifics)
"Companies" are the agency's client sub-accounts. Each is a normal Knock Knock company (companies collection) tagged with agency_id, owned by a web_owner user the agency creates. From this cluster of screens the agency creates clients, assigns them a package, manages add-ons, logs in as the client (impersonation), changes their owner password, overrides the widget white-label, and archives/transfers them.
What it does
- List all client companies with search, sort, and pagination.
- Create a client three ways: standard (manual), via the agency's GoHighLevel sub-accounts, or as the agency's own self-account.
- View a client's company info, owner, and subscription/add-ons on a detail page.
- Edit company fields and assign/change the subscription package.
- Add / cancel add-ons on a client's subscription.
- Impersonate ("Login as Owner") to manage the client's account directly.
- Change the owner's password, override the widget's "Powered by" white-label per company, and archive / delete a company.
- Invite the client (activation email, auto or on demand), fund their wallet on create, restrict their portal (Agency Controls), set up hidden sections for them (setup session), and pause / resume them.
How it works
The list reuses the same /company endpoint as the main app — the backend scopes results to the caller's agency. Creating a client decrements available_sub_accounts on the agency and provisions a company + web_owner user + a default chatbot flow + a client subscription pointing at the chosen package.
Two creation paths exist:
- Standard (
POST /agencies/companies,createCompany) — manual client, no GHL. - GHL (
POST /agencies/companies/ghl,createCompanyForGHL) — same provisioning, but also mints a GHL install URL so the agency can map the new Knock Knock account to a GoHighLevel sub-account. One Knock Knock account per GHL client.
Package assignment writes a SubscriptionModel row for the client (package_id, remaining_ai_credits = pkg.ai_credits, expiry derived from the agency's own subscription). The client's company admin cannot change their own plan — they hit a "contact agency" gate; only the agency changes it.
Source: frontend/src/views/agency/companies/ (List.vue, Edit.vue, CreateGHL.vue, Detail.vue, Addon.vue) and AgencyController.
Configuration & options
Companies list (companies/List.vue)
| Control | Backed by | Notes |
|---|---|---|
| Search / sort / pagination | getCompanies() → GET /company?skip&limit&search&sort&order | Agency-scoped server-side |
| Add Company | router link → /agency/companies/create | Gated by agency.add_client_subscription in the UI |
Create — Standard (companies/Edit.vue in create mode, "Add a Client Without GoHighLevel (White Label)")
createCompany → POST /agencies/companies (requires agency.add_client_subscription; consumes one sub-account slot). Form (vee-validate + zod):
| Field | Notes |
|---|---|
| Company Name, Email, Description | Email must be globally unused (non-playground) — "Email already in use" |
| Default Users (0–3) | Seed a per-client private PackageModel (AI Credits field removed from Add Client, 5d5beb6e — the package opens at 0 credits; funding is the opening wallet transfer) (<company> Package, user_emails: [email], expiry_days: 30) |
Transfer to their wallet (transfer_credits, sent in credits, shown in $) | Required in the UI and prefilled at the agency minimum when the user has agency.subscription_payments (disabled otherwise). Backend: transfer_credits > 0 needs subscription_payments (403), must be ≥ openingTransferMinCredits(agency) = agency.opening_wallet_transfer_credits (super-admin set, default/fallback 1000 = $10, values <100 fall back) → 400 "The minimum wallet transfer is $X", and ≤ agency.wallet_credits → 402. 0 = no transfer is still accepted by the API. Moved after create via _moveWalletCreditsToCompany (ledger source agency_wallet_transfer_*); a failed move returns a wallet_transfer_failed warning, not an error |
Email this client their invite now (send_invite) | Defaults to agency.auto_invite_clients (default true); per-client override |
Client access (client_permissions) | Agency Controls allow-list; everything ticked is sent as null (unrestricted) |
The owner user is created is_verified: true with an invite_key; invited_at is stamped only if an invite email actually went out. (The opening-transfer minimum went through a same-day add/revert/re-add on 2026-09-30 — 9beb33123 → e658731ff → 0aeda2dca; the final state is the one above.)
Edit (PUT /agencies/companies/:id, updateCompany)
Gated by _canEditClients = agency.edit_clients or agency.add_client_subscription (transitional until POST /migrations/backfill-agency-edit-clients has run everywhere — then drop the second clause). Writes only the explicit whitelist AGENCY_EDITABLE_COMPANY_FIELDS (company_name, phone_number, website_url, industry, timezone, language, country_code), each normalised by normalizeAgencyCompanyField (blank phone/website/industry allowed; blank timezone/language/country refused rather than silently reset to the schema defaults Pacific/Auckland/NZ). Side effects, each degrading to a warnings[] entry (UI: "Saved, with follow-up needed") rather than failing the save:
- Website change → re-points the
CompanyWebsiterow and enqueues a crawl on the client's credits (scrape_skipped_no_credits,scrape_skipped_not_configured,scrape_enqueue_failed,website_row_*). - Timezone/language/phone change →
syncAffectedInboundAgents(fire-and-forget sinceba5a2b028;agent_sync_failed/agent_sync_truncated). - Transfer Payment (
add_ai_credits) → wallet top-up via the same_moveWalletCreditsToCompany(ledger sourceagency_wallet_ai_credit_purchase); never touches the packageai_creditsallocation (resolvePackageCredits), so the client isn't credited twice at renewal.
Agency-funded wallet auto-recharge
Since c0748c695 (frontend 622b88d0). auto_recharge: { enabled, threshold_credits, amount_credits } on create (standard + GHL — CreateGHL also gained the opening Transfer to their wallet field) and PUT /agencies/companies/:id; edit returns auto_recharge (agencyAutoRechargeView, incl. client_card_on). Parsed by lib/agencyAutoRecharge.js (parseAgencyAutoRecharge: explicit true/false only, both amounts 0–1,000,000 credits = $10,000, amount > 0); turning it on needs agency.subscription_payments (403). Stored on the client's billable subscription as balance_auto_recharge with source: 'agency_wallet' + amount_credits (vs the client's own source: 'card' + addon_id) — one or the other, last writer wins; switching it off never touches a card setup. UI: components/agency/ClientAutoRechargeFields.vue ("Auto-recharge their wallet", "When their wallet drops below", "Add this much"), utils/clientAutoRecharge.js.
BalanceAutoRechargeJob(every minute): wallet< thresholdor<= 0→_rechargeFromAgencyWallet→moveAgencyWalletToCompany(same path as Transfer Credits, ledgeragency_wallet_transfer_out). 10-min cooldown (AGENCY_WALLET_COOLDOWN_MINUTES), claim re-checksenabled+source, re-readsarchived_atbefore moving. Pays from the company's current agency only (a stalesub.agency_idfrom another agency is skipped). Agency wallet short → nothing moves, oneagency/client-auto-recharge-short.htmlto the agency owner per failure run (agency_short_notified_at, cleared on the next success).CompanyWalletLowJob._autoRechargeCovers: agency-funded counts as covering while the agency wallet ≥amount_credits.- Client side (
SubscriptionControllerauto-recharge save): an agency-funded setup is read-only — onlypromptedmay change, else 403 "Auto-recharge on this wallet is managed by your agency."; a body withenabled: true+addon_idtakes over (card source, clearslast_recharge_at, switches the agency one off on every row). The client AddOns page shows "your agency adds … automatically" with no Manage button, so the takeover is API-only today. - Package change carries
agency_id+balance_auto_rechargeonto the new subscription row (previously dropped silently). - Archive/delete call
_stopAgencyAutoRechargefirst, so no top-up lands between the refund and the wallet wipe.
Create — GHL (companies/CreateGHL.vue)
Wrapped in AgencyPermissionGate permission="agency.add_client_subscription". If GHL is not connected it shows an "Integrate Go High Level" prompt linking to /agency/ghl-instructions.
| Field | Required | Backend validation |
| -------------------------------------------- | -------- | ---------------------------------------------- | ------- | ------------------------------------------------------ |
| Client Business Name (company_name) | yes | required | string |
| Client Website URL (website_url) | no | string |
| Industry | yes (UI) | string (from COMPANY_INDUSTRIES) |
| Subscription Package (package_id) | yes | required | mongoId | exists:PackageModel.\_id (must belong to this agency) |
| Contact/Owner name, email, password, confirm | yes | email must be globally unused (non-playground) |
On success returns ghl_install_url; the agency follows it to map the Knock Knock account to the GHL sub-account. Email is identity-only — no emails are sent to the client from this form.
Company detail (companies/Detail.vue)
| Section / action | Permission / gate | Backend |
|---|---|---|
| Company info (incl. Widget Installed/Not installed + date, AI credits, members count), owner, subscription | view | getCompanyById → GET /company/:id; subscription via GET /company/:id/subscriptions?limit=1 |
| Login as Owner (impersonate) | agency.impersonate_clients | impersonateUser(owner) → loginAsUser → POST /user/:id/login-as |
| Pause Client / Resume Client | agency.disable_clients | setCompanyPaused → POST /agencies/companies/:id/pause { paused } |
| Edit button | _canEditClients | → /agency/companies/:id/edit |
| Client access card (Full access / Restricted) | edit: _canEditClients; else read-only list | PUT /agencies/companies/:id/client-permissions |
| Change Password (owner) | appStore.isAgencyOwner only | changeUserPassword → PUT /user/:id { new_password } |
| Widget Whitelabel Override (toggle, text, redirect URL, Agency logo show/hide) | view | updateWidgetWhitelabel → PUT /company/:id/widget-whitelabel { is_enable, text, url, hide_logo } |
| Cancel recurring add-on | agency.add_client_subscription | removeAddon(id, addonId) → POST /agencies/companies/:id/cancel-addon/:addon_id |
The widget renders the agency logo in every "Powered by" footer through widget/src/components/PoweredByLogo.vue (6ad5cdb) when widget_whitelabel.is_enable && !hide_logo and the agency has a logo.
Client list (companies/List.vue, "Client Sub-accounts")
Columns: Name (Own Company badge for the self-account), Email Address, Invite Link (Accepted + date, else Copy Link and Send Invite), LeadConnector (only when the agency is connected — Connect when unmapped, else Connected / Old app: stopped + summary · Manage → GhlClientModal, see GHL Integration), subscription status chip — paused (amber) wins over the subscription status (9ebbf87c). Row menu: Impersonate, View Company, Transfer Credits (subscription_payments), Add Add-on, Pause/Resume Client (disable_clients), Cancel/Reactivate Subscription, Archive (owner only; dialog "Archive this client?" → cancel subscription → archiveCompany(id, 'archive'), which frees the seat and refunds trial wallets — no more permanent delete from the agency UI). Tabs Active / Archived (?tab=archived, linked from the deletion emails): archived rows show Archived date, Deletion date (from ArchivedAccountDeletionJob, see Plans), Download data (requestDataExport, repositories/accountDeletion) and Restore (disable_clients; takes a seat). Low-wallet clients get a "Wallet empty" / "Wallet $X" badge and AgencyLowWalletsPanel sits above the table.
Activation invites (POST /agencies/companies/:id/send-invite)
_sendClientInvite emails agency/client-invite.html ("Activate your account") with company_id set, so MailService white-labels it (agency sender name, reply-to, logo, and portal_url = the agency custom domain when live — the link is built from the resolved portal_url in the template, never Config.app('portal_url')). The link is /invite/:invite_key → InviteView signs them in → /setup. Since 30d5921af the template also carries a 4-step "How to get set up" block (activate — no password on the first visit; follow the setup guide; paste the widget snippet; sign in later at portal_url + '/signin' with Forgot password to choose a password), prints the raw link as a fallback, and closes with "Questions? Contact <agency>". Sent automatically on create when send_invite (default agency.auto_invite_clients), or on demand from the list; the on-demand endpoint needs agency.add_client_subscription and refuses a client with no owner, no invite key, or invite_accepted_at set. Never throws after the account exists. Not to be confused with the prospecting-email Client Invitations tool.
Agency Controls (agency_client_permissions)
companies.agency_client_permissions: absent/null = unrestricted (every pre-existing client), array = allow-list, [] = hide every gated section. Fixed vocabulary in backend/app/lib/agencyClientPermissions.js, mirrored in frontend/src/common/constants/clientPermissions.js (unknown key → 400):
settings.widget,settings.knowledge_base,settings.ai_agents,settings.ai_agents.behavior(only meaningful with its parent),settings.integrations,settings.webhooks,settings.calls,settings.organization,settings.funnelpages.activities,pages.chats,pages.calls,pages.members,pages.reports,pages.leads,pages.agent_k,pages.nox_activity
Written only by AgencyController.createCompany / updateCompany / updateClientPermissions (PUT /agencies/companies/:id/client-permissions, body { client_permissions: array|null }, _canEditClients); CompanyController strips it from every generic $set. The picker sends everything-ticked as null so sections added later aren't silently hidden. Personal settings are never gated.
Enforcement depth (v1): the client portal hides nav/sidebar/settings items (useClientAccess, useSettingsMenu) and router/clientAccessGuard.js bounces typed URLs; NoxConfigController refuses Nox config reads/writes in hidden sections (noxConfigPermissions.js). Direct REST calls are not blocked — same depth as team-member permissions. Hidden applies to every session in the client portal, impersonating agency users included.
Setup session (POST /agencies/companies/:id/setup-session)
The Set up button on a hidden settings card opens /agency/companies/:id/setup?section=<key> (companies/Setup.vue), which embeds the client's settings page in an iframe (AgencySetupFrameLayout, utils/agencySetupFrame.js). The endpoint mints an owner-scoped token (needed because settings APIs and ms-ai resolve the company from the token) — owner-equivalent, so gated on agency.impersonate_clients. Differences from /user/:id/login: 8-hour expiry, refuses the agency's own account (400) and a blocked owner (409), and carries an agency_setup claim with the acting agency user so the request log attributes changes. The frontend holds the token in memory inside the frame only and drops it if the tab's own session changes; expiry shows Reconnect. Integrations have no setup path (OAuth can't run in the frame); the desktop app shows a web-only notice.
Pause / resume (POST /agencies/companies/:id/pause)
pauseCompany (b4a697fc7), body { paused: boolean } — anything else is a 400 (an empty body used to read as resume). Gate agency.disable_clients. Sets paused_at/paused_by (null = running); idempotent (no second write, so paused_by isn't overwritten). Refuses to pause the agency's own account, checked by agency_self_account and owner ownership (resume is never refused). Does not touch subscription, package, credits or available_sub_accounts — that's the difference from cancel. Emits company-settings-updated to the company room.
Where it bites (3870acae8 backend, e7eebfc ms-comm, a041ebf widget):
| Layer | Behaviour |
|---|---|
public/widget.js loader | bails before boot (paused_at); the widget store also listens for company-settings-updated and hides live widgets (jittered refetch) |
visitorCompanyPaused middleware | 403 on /user-session/create (covers the headless SDK, which never mounts the widget); playground sessions exempt |
companyPaused middleware | 403 { paused: true } on the client's operational routes (calls, chats, stats, reports, sessions, Nox brief/actions/activity/funnel) for the owner, members and an impersonating agency user; agency users as themselves and super-admins pass; billing, settings, /user/me, /members and /chats/ai-messages stay open. Uncached lookup so Resume is instant; fails open |
internalCompanyPaused | same for ms-ai's internal Knox routes |
ms-comm InboundCallController | before screening/routing/hours: dials the first routing-priority number → agent transfer number → company number; none → "This number is temporarily unavailable. Goodbye." No AI tail. Fails open |
ms-comm WhatsApp MessageController | message ingested, AI muted |
AiSmsWebhookController | SMS agent refuses (403), logged status: 'paused' (SmsAgentMessageModel enum) |
| Frontend | appStore.isCompanyPaused: sidebar items disabled ("Paused by your agency — contact them to reactivate"), router redirects /live-sessions, /recorded-sessions, /chats, /calls, /members, /leads, /reports, /prospecting, /agent-k, /activity, /nox-activity to /dashboard?paused=1; dashboard shows "Your account is paused" and hides the command center + setup cards; Nox isn't mounted |
Agency-side: amber banner "This client is paused" on detail, paused chip in the list, pause icon in SubAccountSwitcher (paused clients stay switchable).
Package & add-on management
| Action | Repository fn | Endpoint |
|---|---|---|
| Assign a package to a company | assignPackage(companyId, packageId) | POST /agency/companies/:companyId/assign-package |
| Buy a company add-on | addAddon(companyId, addonId) | POST /agencies/buy-addon { company_id, addon_id } |
| Cancel a company add-on | removeAddon(companyId, addonId) | POST /agencies/companies/:companyId/cancel-addon/:addonId |
| Cancel company subscription | cancelCompanySubscription(companyId) | POST /agencies/companies/:id/cancel-subscription |
| Reactivate company subscription | reactivateCompanySubscription(companyId) | POST /agencies/companies/:id/reactivate-subscription |
| Pause / resume company | setCompanyPaused(companyId, paused) | POST /agencies/companies/:id/pause |
| Send activation invite | sendCompanyInvite(companyId) | POST /agencies/companies/:id/send-invite |
| Archive company | archiveCompany(id) | GET /company/:id/archive |
| Permanently delete (archived) | deleteCompany(id) | DELETE /company/:id |
Default Knowledge Base
4245f7061, frontend 15dae45e. Agency Settings → Knowledge Base (/agency/settings/knowledge-base, views/agency/settings/KnowledgeBase.vue, agency.manage_settings). API: GET /agencies/default-knowledge-base, POST …/documents, DELETE …/documents/:id, PUT …/texts; stored in agency.default_knowledge_base.{documents[{file}], texts[{title, content}]}. Limits: PDFs only, 10 MB each, 10 documents; 20 texts, 50k chars each.
Applied in the background on creation only — Add Client (POST /agencies/companies), GHL create (/agencies/companies/ghl), signup page (/public/agency-signup/:token/register) and Platform API create. Each PDF is copied per client (agent_knowledge_base_documents[].auto_train) and trained once extraction finishes; text is trained immediately. Not applied to existing clients, the agency's own site, or companies moved in with admin "Add existing company". /setup offers sub-accounts "I'll add my website later" when the default KB already gives them content.
Bot Flow Builder (same commits) is a super-admin switch, not an agency setting: Admin → Agencies → Detail card "Bot Flow Builder" → PUT /agencies/admin/:agency_id/bot-flow-enabled {enabled} sets agency.bot_flow_enabled and bulk-writes company.bot_flow_enabled on every client sub-account (not the own site or playgrounds); off overrides per-company enables, flows are kept. New and attached sub-accounts inherit it (lib/agencySubAccountFlags.inheritAgencyFlags).
Self-account (agency's own website)
Self-serve agencies now get their own site at signup (see Overview); older ones can still install it via the dashboard (setupOwnCompany → POST /agencies/setup-company), which flags the company agency_self_account: true. Conversion of a direct account: Overview → Direct → agency conversion. The own site is never auto-deleted. Self-account members can be migrated into agency staff — see Staff Management.
Behaviors & edge cases
- Low client wallets (
25e2eb2b6; panela303b58e/260c5cbe; snooze5208618d/0b046c73):AgencyClientWalletLowBanner.vue(inAgencyLayout) andAgencyLowWalletsPanel.vue(client list) pollGET /agencies/client-wallets/low(WalletLowController.agencyClients, every 5 min + on focus) foragency.subscription_paymentsholders. Copy: "$Xleft · enough for about N days at current usage";days_leftnull over 30 days (7c5872c17). The bar is now dismissible (Remind me later 3/7/14 days, Don't show again → account-menu notice), per browser — details in Wallet. Rule =lib/walletLowStatus(same asCompanyWalletLowJob's email). - Capacity guard. GHL/standard creation rejects with "Agency has no available sub accounts" when
available_sub_accounts < 1. Each create decrements the counter by 1. - Package must belong to the agency.
createCompanyForGHLlooks up the package by{ _id, agency_id }; a package from another agency is rejected even if the id is valid. - Client expiry tracks the agency. A new client subscription's
expiry_dateis derived from the agency's own subscription expiry (GHL flow adds 30 minutes). When the agency renews, client allowances/credits refresh. - Clients can't self-serve billing. The client-side plan screen shows a "contact agency" gate; all plan/add-on changes go through these agency endpoints.
- Impersonation is permission-gated. Staff without
agency.impersonate_clientsdon't see the Login-as-Owner button; the action also requires the company to have anowner. Staff can further be limited tousers.impersonate_client_ids(0fb458768), enforced inPOST /user/:id/loginandPOST /agencies/companies/:id/setup-session(403 "This client is not assigned to you. Contact your agency owner.") — see Staff Management. - Trial clients keep their own expiry on agency renewal (
08315c59c) — see Subscriptions. - Widget white-label URL is validated client-side (must be http/https with a dotted hostname) before save.
- Wallet refund on archive/delete is trial-only (
c0748c695)._refundSubAccountWalletreturns unspent agency-funded balance (ledgeragency_wallet_subaccount_refund, "Returned to agency") only when_wasAgencyTrialClient: no row hasagency_trial_converted_at/agency_paid_seat_at, and some row hasagency_trial_seat,agency_trial_released_at, oragency_seat_claimed: false(fallback: anagency_trial_wallet_seedledger row). A paid client's balance is zeroed and gone.agency_trial_released_at(seat handed back on cancel/delete) andagency_paid_seat_at(stamped on every row of the company when real money arrives via Connect) exist only for this check — trial-day and seat-charging logic still readagency_trial_converted_at. The agency UI deletes as cancel → archive → delete and toasts the summedrefunded_credits. - Archive vs. delete. Archive is reversible (
GET .../archive, Restore from the Archived tab); the agency UI no longer callsDELETE /company/:id— permanent deletion isArchivedAccountDeletionJob's, when the super-admin settingarchived_company_deletionis on (only the agency is emailed for its clients). Clients of an archived agency are never auto-deleted.
Plan & limits
- Number of clients an agency can create is bounded by
total_sub_accountsfrom its package (verify the slot counts per plan). - AI credits granted to each client come from the assigned package's
ai_credits(see Packages). - Moving a direct company under an agency is super-admin "Add existing company" (Overview); moving a company between agencies is still not a first-class button.
Technical implementation
- Views:
frontend/src/views/agency/companies/*.vue - Routes:
frontend/src/router/agency.js(agency-companies,-create,-create-ghl,-view,-setup,-edit,-add-addon) - Repository:
frontend/src/repositories/agency/index.js - Controller:
backend/app/controllers/AgencyController.js(createCompany,updateCompany,pauseCompany,updateClientPermissions,createSetupSession,sendCompanyInvite,createCompanyForGHL,setupCompany,setupAgencyAccount,cancelCompanySubscription,cancelCompanyAddon); middlewarescompanyPaused,internalCompanyPaused,visitorCompanyPaused; libsagencyClientPermissions.js,noxConfigPermissions.js— see backend service - Models:
CompanyModel,SubscriptionModel,AgencyModel,PackageModel(agency-scoped client packages) - GHL:
GoHighLevelService.getInstallUrl— see CRM integration and GoHighLevel integration