Skip to main content

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)​

ControlBacked byNotes
Search / sort / paginationgetCompanies() → GET /company?skip&limit&search&sort&orderAgency-scoped server-side
Add Companyrouter link → /agency/companies/createGated 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):

FieldNotes
Company Name, Email, DescriptionEmail 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 CompanyWebsite row 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 since ba5a2b028; agent_sync_failed / agent_sync_truncated).
  • Transfer Payment (add_ai_credits) → wallet top-up via the same _moveWalletCreditsToCompany (ledger source agency_wallet_ai_credit_purchase); never touches the package ai_credits allocation (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 < threshold or <= 0 → _rechargeFromAgencyWallet → moveAgencyWalletToCompany (same path as Transfer Credits, ledger agency_wallet_transfer_out). 10-min cooldown (AGENCY_WALLET_COOLDOWN_MINUTES), claim re-checks enabled+source, re-reads archived_at before moving. Pays from the company's current agency only (a stale sub.agency_id from another agency is skipped). Agency wallet short → nothing moves, one agency/client-auto-recharge-short.html to 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 (SubscriptionController auto-recharge save): an agency-funded setup is read-only — only prompted may change, else 403 "Auto-recharge on this wallet is managed by your agency."; a body with enabled: true + addon_id takes over (card source, clears last_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_recharge onto the new subscription row (previously dropped silently).
  • Archive/delete call _stopAgencyAutoRecharge first, 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 / actionPermission / gateBackend
Company info (incl. Widget Installed/Not installed + date, AI credits, members count), owner, subscriptionviewgetCompanyById → GET /company/:id; subscription via GET /company/:id/subscriptions?limit=1
Login as Owner (impersonate)agency.impersonate_clientsimpersonateUser(owner) → loginAsUser → POST /user/:id/login-as
Pause Client / Resume Clientagency.disable_clientssetCompanyPaused → POST /agencies/companies/:id/pause { paused }
Edit button_canEditClients→ /agency/companies/:id/edit
Client access card (Full access / Restricted)edit: _canEditClients; else read-only listPUT /agencies/companies/:id/client-permissions
Change Password (owner)appStore.isAgencyOwner onlychangeUserPassword → PUT /user/:id { new_password }
Widget Whitelabel Override (toggle, text, redirect URL, Agency logo show/hide)viewupdateWidgetWhitelabel → PUT /company/:id/widget-whitelabel { is_enable, text, url, hide_logo }
Cancel recurring add-onagency.add_client_subscriptionremoveAddon(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.funnel
  • pages.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):

LayerBehaviour
public/widget.js loaderbails before boot (paused_at); the widget store also listens for company-settings-updated and hides live widgets (jittered refetch)
visitorCompanyPaused middleware403 on /user-session/create (covers the headless SDK, which never mounts the widget); playground sessions exempt
companyPaused middleware403 { 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
internalCompanyPausedsame for ms-ai's internal Knox routes
ms-comm InboundCallControllerbefore 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 MessageControllermessage ingested, AI muted
AiSmsWebhookControllerSMS agent refuses (403), logged status: 'paused' (SmsAgentMessageModel enum)
FrontendappStore.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​

ActionRepository fnEndpoint
Assign a package to a companyassignPackage(companyId, packageId)POST /agency/companies/:companyId/assign-package
Buy a company add-onaddAddon(companyId, addonId)POST /agencies/buy-addon { company_id, addon_id }
Cancel a company add-onremoveAddon(companyId, addonId)POST /agencies/companies/:companyId/cancel-addon/:addonId
Cancel company subscriptioncancelCompanySubscription(companyId)POST /agencies/companies/:id/cancel-subscription
Reactivate company subscriptionreactivateCompanySubscription(companyId)POST /agencies/companies/:id/reactivate-subscription
Pause / resume companysetCompanyPaused(companyId, paused)POST /agencies/companies/:id/pause
Send activation invitesendCompanyInvite(companyId)POST /agencies/companies/:id/send-invite
Archive companyarchiveCompany(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; panel a303b58e / 260c5cbe; snooze 5208618d / 0b046c73): AgencyClientWalletLowBanner.vue (in AgencyLayout) and AgencyLowWalletsPanel.vue (client list) poll GET /agencies/client-wallets/low (WalletLowController.agencyClients, every 5 min + on focus) for agency.subscription_payments holders. Copy: "$X left · enough for about N days at current usage"; days_left null 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 as CompanyWalletLowJob'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. createCompanyForGHL looks 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_date is 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_clients don't see the Login-as-Owner button; the action also requires the company to have an owner. Staff can further be limited to users.impersonate_client_ids (0fb458768), enforced in POST /user/:id/login and POST /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). _refundSubAccountWallet returns unspent agency-funded balance (ledger agency_wallet_subaccount_refund, "Returned to agency") only when _wasAgencyTrialClient: no row has agency_trial_converted_at / agency_paid_seat_at, and some row has agency_trial_seat, agency_trial_released_at, or agency_seat_claimed: false (fallback: an agency_trial_wallet_seed ledger row). A paid client's balance is zeroed and gone. agency_trial_released_at (seat handed back on cancel/delete) and agency_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 read agency_trial_converted_at. The agency UI deletes as cancel → archive → delete and toasts the summed refunded_credits.
  • Archive vs. delete. Archive is reversible (GET .../archive, Restore from the Archived tab); the agency UI no longer calls DELETE /company/:id — permanent deletion is ArchivedAccountDeletionJob's, when the super-admin setting archived_company_deletion is 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_accounts from 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); middlewares companyPaused, internalCompanyPaused, visitorCompanyPaused; libs agencyClientPermissions.js, noxConfigPermissions.js — see backend service
  • Models: CompanyModel, SubscriptionModel, AgencyModel, PackageModel (agency-scoped client packages)
  • GHL: GoHighLevelService.getInstallUrl — see CRM integration and GoHighLevel integration