Skip to main content
Admin → Onboarding is the primary staff workspace for account links and exceptions. The Operator sees their required steps and the name of the person who must complete KYC.

​
What connects automatically

When automatic linking is enabled, opening or refreshing an eligible Location’s setup checks its agency SaaS subscription, the subscription’s Operations contact, its CRM payment subscription, and the matching Stripe subscription and saved card. A missing cardholder name does not block this process. The name displayed for KYC comes from the Operations contact. Compliance remains responsible for confirming card ownership and the signed agreement; automatic linking does not record either review as complete. For a new link, there must be exactly one unassigned, open opportunity for that contact in Onboarding → New - Paid, and exactly one CRM payment subscription on the contact. The app fills that opportunity’s Product Location ID with the customer’s SaaS Location ID, confirms the write, and saves the Operations contact mapping in setup. It reuses the opportunity; it does not create one or change its stage. A valid existing Product Location ID in the Onboarding pipeline takes precedence and survives movement to later stages. Account linking and identity verification resolve the mapping only in that pipeline. An opportunity in another pipeline, including 3. FM Client Onboarding, can carry the same Product Location ID without blocking the link. Those other opportunities are not selected or changed. Duplicate mappings within Onboarding, conflicting contacts or Locations, and incomplete searches still need review rather than a name or email match. The identity panel says the account was linked from its subscription. No compliance checkbox or reviewer timestamp is manufactured. Matching Stripe identity verification still completes KYC automatically after the CRM result is confirmed. Linking alone does not mark KYC complete, import an existing CRM Verified value, or confirm payment collected. A trial subscription with a saved card is eligible; its trial status is not proof of payment. Previously staff-reviewed identity evidence is preserved.
  1. Open the client in Admin → Onboarding.
  2. Open Account connection. Missing mappings show connection guidance directly; raw contact corrections remain under Troubleshooting.
  3. Under Connect the SaaS account, enter the customer’s SaaS Location ID if the opportunity has no Product Location ID yet, then choose Check account links.
  4. Read the result. The app checks that the selected opportunity is the one belonging to that account before updating anything.
New installations and completed provisioning jobs also try the guarded linker, with bounded retries for a delayed subscription or opportunity. The feature must already be enabled for that Location, either manually or through the separately configured new customer enrollment rule. See Account reconciliation for the full-agency report, including accounts without an app installation. Normal setup refreshes retry at least one minute apart. While the customer’s setup page is visible, its existing five-minute refresh also retries. Selecting an already mapped client in Admin only reads saved state. An explicit Refresh setup in Troubleshooting runs provider checks. An eligible client whose setup has never been opened can also be linked from admin or through the separately enabled background recovery below. Provider delays or a lost write response are checked again against current CRM data. A successful earlier mapping is not written twice.

​
Background recovery

When ONBOARDING_AUTO_LINK_RECOVERY_ENABLED=true and automatic linking is enabled, an hourly check selects up to ten eligible installed customer Locations in the Operations agency. Onboarding & Setup must already be enabled. Missing link attempts and pending attempts last checked at least an hour ago qualify; the oldest attempts go first. Dispatches are spaced ten seconds apart and use the existing guarded linker and its bounded one-, five- and fifteen-minute retries. Completed links, active locks, internal Locations, ambiguous ownership and review-required records are skipped. Recovery does not turn Labs on, clear review holds, mark compliance or payment complete, or activate the communications engine. The linker retains its existing separately gated Slack refresh behavior. Repairing Product Location ID in CRM does not itself save the app’s internal contact binding. After reviewing a conflict and repairing the CRM field, choose Check account links to revalidate the subscription and finish the binding. Background recovery deliberately leaves review holds for this staff action. Turning the recovery setting off stops queued recovery work and its later retries; an already-running attempt can finish. Turning automatic linking off also stops further linker writes. Existing links remain intact. Re-enable recovery to resume. The inventory is read in pages of 100 with separate database budgets and is bounded at 2,000 installations; exceeding it fails the sweep instead of silently treating a partial inventory as complete. A failed CRM opportunity lookup can leave an otherwise valid account pending. After the connection issue is corrected, use Check account links again; the app reuses the existing mapped opportunity. Do not create a duplicate opportunity to bypass a pending lookup. A failure before any CRM write releases its temporary reservation, so correcting the opportunity and retrying can succeed. Interrupted pre-write attempts are released when their five-minute lease expires. If a write might have reached CRM, its reservation is retained for readback rather than silently switching opportunities. Confirmed mappings and older reservations without dispatch information also remain protected. An account-link review blocks starting a new verification. A customer who already has a Stripe session can still resume that same session from the account that started it; this does not change the saved verification subject or clear the account-link review.

​
Resolve exceptions

  • Multiple Onboarding opportunities or subscriptions: review the records, set Product Location ID on the correct existing Onboarding opportunity in CRM, then retry from admin. The app will not select the newest payment or assume that a shared contact means one account.
  • Wrong saved contact or Location: verify the subscription’s account ownership first. Correct the CRM Product Location ID and use the existing admin contact-mapping controls. An active identity attempt must be reconciled/reopened before its contact can change.
  • Changed name or subscription identity: compliance must review the existing evidence. Automatic linking preserves the existing verification instead of changing its subject. Use Correct identity evidence for a reviewed exception (reopen an active attempt first), record the actual staff confirmation, then choose Check account links.
  • Missing opportunity or card: finish provisioning in the CRM or Stripe, then retry.
  • Connection unavailable: reconnect the relevant agency/Operations connection in admin.
Do not create a second opportunity to recover a failed link. A reserved opportunity that needs reassignment to a different account requires technical review; automatic retries never move it between Locations. Turning automatic linking off stops further automatic writes and preserves existing links and verification history.