​

Processing Application gate cutover

​

What enabling blocks

• Agreement category. This covers every processing type, including term loans — submitting term loans to 7 Figures is a handoff, so it carries the client’s own attested answers like any other handoff. Term loans were exempt until Jul 28 2026.

​

The legacy-agreement exemption

• The in-flight review is no longer required for activation. Contacts mid-deal at enable time are exempted by their own agreement date. The candidates script and grandfather overrides remain available as an escape hatch (e.g. a contact whose paperwork must be re-sent after enable but who should not collect an application), not as a rollout step.
• The exemption is permanent for old paperwork, unlike overrides, which expire after 90 days. A stalled old deal can still submit without an application months later; forcing it through the gate would demand paperwork the system never sent.
• Re-signing new paperwork re-arms the gate. The newest completed agreement decides, so a client who completes a post-activation agreement is gated normally.
• A disable→re-enable cycle re-exempts agreements sent while enforcement was off (verifiedAt moves forward), which mirrors what re-grandfathering did by hand.

​

The client-app-agreement exemption

• Manually verified uploads only. The category on a CRM-sent row proves nothing — the legacy send form defaulted it and post-cutover sends record none — so CRM-synced agreements keep the normal gate, the override, and the legacy send-time exemption.
• Agreement Only categories do not qualify on their own. They never carried an application; only the explicit checkbox exempts them. Reclassifying the category or toggling the checkbox flips the exemption in both directions on the next read.
• The newest completed agreement decides, as with the legacy exemption. A client who later completes a post-activation CRM agreement is gated normally.
• Marking the upload complete still requires Approved review status, a rate, a type, a signed date, and the operator’s confirmation checkbox (convex/lib/manualAgreementMetadata.ts).

​

What the operator sees

• Send client agreement & application replaces “Send client agreement”. The application link is a custom value inside the agreement template, so one send delivers both.
• Once the agreement is out, that row nests a Waiting on client cluster with two rows — Awaiting signed agreement and Awaiting processing application — each carrying its own resend button. The rows are derived from CRM state and have no checkbox: the authoritative gate is the Convex check on the captured application, and a tickable row could claim a file was ready when a submit would still be rejected. Resend Application lives here rather than on the review step, so the cluster stays visible while either artifact is outstanding — even if the operator ticked the review early — and disappears only once both have landed and the review is cleared.
• Review agreement & processing application replaces “Review signed agreement” and covers both artifacts in one review call. Unlike the gate-off agreement review, it does not auto-complete when the paperwork lands — the operator clears it by hand once both artifacts are in.
• The Application tab keeps Resend Application available after a submission is captured under the prompt Missing or incorrect information? Use it when the client needs to correct an answer. It retriggers the existing CRM-tag workflow; Funding Machine does not send a direct SMS or email.
• Beneath Resend Application (empty and captured states), operators can copy the Location’s FM Processing Application form link and send it manually (text / chat) when the CRM resend path isn’t the right channel. The link is the same branded share URL used by the contract-redirect walkthrough.
• Its checkbox is disabled until both artifacts arrive, with a tooltip naming what is still missing. You cannot review paperwork that has not shown up, and ticking it early used to march the checklist onto a submit the server gate rejects. Un-ticking stays available, so a file whose review completed before the gate was switched on is never frozen. This is a UI guardrail only — the authoritative check is the Convex gate at submit time.
• While the review is outstanding, the pinned banner names the missing artifact and offers Message Client instead of prompting a review of paperwork that has not arrived.
• First-send walkthrough (contract redirect). The first time an operator opens the agreement send flow at a gate-enabled location that has not yet confirmed its post-signing redirect, a walkthrough dialog opens ahead of the send form. It explains the sign-first flow, shows the location’s own form URL with a copy button, and walks through configuring Enable redirection to custom URL on both Client Agreement templates. Enforcement is soft: Set up later always proceeds to the send, and the walkthrough returns on every send until the operator attests setup on both templates. The attestation is per location, recorded with who confirmed and when (locationSettings.featureFlags.contractRedirectSetup), and reachable afterwards via the “Redirect setup guide” link in the send modal footer.
• On term-loan files the offers step stays reachable during the wait, because pulling rates from Engine is not a hand-off. Only Generate Offers is offered early; Submit Term Loans to 7 Figures Funding is withheld until the review is genuinely current, since that is the hand-off the gate exists to hold back.
• CRM opportunity conversion waits for both artifacts. At a gate-enabled location, completing the agreement alone does not move the Applicants opportunity to Won - Signed or create the Clients opportunity. Conversion runs once the completed agreement and captured Processing Application are both present, regardless of which arrives first: Applicants becomes Won - Signed with status Won, then an idempotent Clients opportunity is created at Agreement Signed. A valid grandfather override also satisfies the application side. Pre-cutover agreements keep the legacy-agreement exemption, and gate-off locations keep signature-only conversion.

​

Preconditions

1. The location installation has Forms read access and has been re-authorized if the scope was added after installation. Confirmed for every install as of Aug 6 2026. forms.readonly is in the requested scope list and every location has been re-authorized, so this is not an open question — verify it per location only through inspection.formId on the configuration check below.
2. The location has exactly one form named FM Processing Application. The form itself is built.
3. Capture requires no form-submission workflow. On an authorized contact read, the app resolves the location’s form and polls the Forms API for that exact contact. A successfully submitted, non-empty snapshot is the completion evidence. See How capture works below.
4. A contact-tag workflow listens for fm-resend-processing-application and sends the client the Processing Application message using the Processing Application Form Link custom value. Built.
5. The Processing Application Form Link custom value is created or refreshed by the app before every agreement send. Built. Delivering the application link inside the agreement email is no longer the plan — GHL provides no way to change the default email template used when an agreement is sent — but the custom value remains load-bearing for the resend workflow (precondition 4).
6. The post-signing redirect is the delivery mechanism. Documents & Contracts supports Enable redirection to custom URL per template: when the client finishes signing, GHL sends them to the location’s Processing Application form. The setting lives in each operator’s own sub-account, on both Client Agreement templates (Capped and Non-Capped), takes a raw URL only (no custom values), and has no API to configure or verify it — so each operator sets it up once by hand, trained by the first-send walkthrough (see What the operator sees) and recorded as a per-location self-attestation. Template re-pushes from the snapshot do not clobber the setting (tested Aug 13 2026). Until a location’s redirect is set up, clients sign and stop there; the operator recovers with Resend Application, and the submit gate still enforces the captured application either way.
7. (Optional since the legacy-agreement exemption.) Contacts already at or beyond the processing handoff are exempted automatically by their agreement date, so the per-contact review below is no longer an activation requirement. Run it when you want visibility into the population, or to grandfather a contact the exemption does not cover. Generate the candidate list with
   bun run scripts/processing-application-cutover-candidates.ts \
     --location LOCATION_ID --form FORM_ID
   
   which replays the gates in the order the submit path runs them. Do not export by pipeline stage: the agreement gate runs first, so a contact in the right stage without a completed, rated agreement needs no override, while one in an unexpected stage with a signed agreement does. The script reports contacts still in flight separately from those whose processing has already finished, because the latter only meet the gate on a new submit. Processing here spans every type: a contact whose cards are done but whose term-loan handoff is still ahead counts as in flight. A third bucket, needs manual review, holds contacts whose submission history exceeded the per-contact scan limit with nothing open observed: the review cannot tell whether processing is still open, so those contacts are left out of the recommended override list (and out of the --out file’s recommendedContactIds) and listed under needsManualReviewContactIds instead. Check each one in the CRM and grandfather it only if it is genuinely still in flight. Activation reconciles the reviewed list against active overrides. To review the whole fleet in one pass instead of one location per run, use
   bun run scripts/processing-application-cutover-batch.ts \
     --base-url https://APP_ORIGIN
   
   which iterates every installed location, resolves each form ID through the same admin configuration check, runs this same review, and writes a consolidated report of which locations are misconfigured, need overrides, need a live capture, or are ready to enable. With --apply-overrides it also creates the recommended overrides through the audited admin endpoint. See the script header for the required admin session token.

​

Scaling the capture trigger beyond the pilot

​

There is no marketplace webhook for this

​

Document statuses are polled, not pushed

​

How capture works

• Every location is covered, including ones installed tomorrow. There is no workflow to clone, no bearer to distribute, and no snapshot to update.
• The delivery-relative window does not apply. A read has no event to correlate against, so submittedAfter is omitted and applications older than 10 minutes are captured normally. The ambiguity failure mode and the localStorage._ud retry trap only ever applied to the webhook path.
• Already-captured submissions are still excluded, so re-reads dedupe rather than writing duplicate snapshots.
• A poll failure never breaks the read. It is logged and the existing context is returned, including field-label repair when needed.
• Capture runs regardless of gate state, so the 7-day capture evidence that activation requires accumulates on its own before cutover.

​

Answers are named by the form that was submitted

​

Form links use the location’s branded domain

​

Per-location token mechanics (pilot and debugging only)

bun -e 'const c=require("crypto");console.log(c.createHmac("sha256",process.env.GHL_PROCESSING_APPLICATION_WEBHOOK_SECRET).update(`processing-application:${process.argv[1]}`).digest("base64url"))' LOCATION_ID

​

Check configuration

await fetch(
  "/api/admin/processing-application-cutover?locationId=LOCATION_ID",
  {
    headers: {
      Authorization: `Bearer ${sessionStorage.getItem("fm_auth_token")}`,
    },
  },
).then((response) => response.json());

​

Grandfather in-flight contacts

await fetch("/api/admin/processing-application-cutover", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${sessionStorage.getItem("fm_auth_token")}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action: "grandfather",
    locationId: "LOCATION_ID",
    contactId: "CONTACT_ID",
    reason: "Already at the processing handoff before cutover",
  }),
}).then((response) => response.json());

​

Per-contact admin UI

• First-time grandfather: shown when there is no override, or the override is expired or bound to a replaced form. Requires a 5–500 character reason and a confirmation, then posts action: "grandfather" without renew.
• Renewal: shown only when an active override exists. The existing expiry, reason, and form ID are displayed; the button and confirmation copy say “renew”, and the post includes renew: true. Cancelling keeps the current override as is.
• Unknown outcome (network failure, 5xx, unreadable response): the panel blocks resubmission until it has re-read the override for that exact contact. A readback showing the expected result (active; for a renewal, a later expiry than before) confirms success. A readback that does not show it is reported as not confirmed — it is not treated as proof the write failed, because the request may still commit. The panel pins the original operation (intent, the expectedExpiresAt observed before the write, and the audit reason as confirmed). “Retry” re-sends exactly that request — never an expiry read afterwards or an edited reason — so a late first attempt turns the retry into a 409 rather than a second renewal, and the audit trail matches what the operator confirmed. The reason field is read-only while pinned; Dismiss releases it. A later readback that shows the expected result resolves the state to success; only an explicit dismiss releases the pinned operation.
• Switching contacts while a request is in flight drops that request’s completion — even when the operator returns to the same contact before it finishes. Each visit is a new epoch; completions from an older epoch never update the panel or trigger a readback. The current view reads the server’s truth on its own.

​

Prove polling capture

​

Waiving capture evidence

​

Troubleshoot a failed capture

• 400 Invalid payload — the body must omit submissionId entirely when the workflow cannot supply one. An empty string is rejected.
• 401 Valid session required — the request never reached the route. The path must be exempt from the session middleware (lib/proxy/isExemptPath.ts).
• 401 Unauthorized — the bearer does not match the token derived for the locationId in the body. On a newly rolled-out location this is almost always a workflow copied from the pilot with the pilot’s bearer left in place.
• 409 form_mismatch — the body’s formId is not the location’s own FM Processing Application form, re-checked against a forced refresh. Same cause: a copied workflow still pointing at the pilot’s form.
• 409 ambiguous_submission — the contact has more than one uncaptured submission, or an uncaptured one older than the fallback window.
• 409 configuration_error — Forms read access is missing, or the location does not have exactly one FM Processing Application form.
• 422 invalid_submission — the submission could not be turned into a field snapshot. The logged message names the offending key.

​

Enable

await fetch("/api/admin/processing-application-cutover", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${sessionStorage.getItem("fm_auth_token")}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action: "enable",
    locationId: "LOCATION_ID",
    grandfatheringConfirmed: true,
    grandfatheredContactIds: [],
    // Optional, see "Waiving capture evidence":
    // captureEvidenceWaived: true,
    // waiverReason: "Form is snapshot-managed; capture proven at pilot",
  }),
}).then((response) => response.json());

​

Smoke checks

• A newly captured application can submit to Processing.
• A contact whose completed agreement predates activation can submit to Processing without an application (legacy-agreement exemption), and its submission records applicationGateReason: "legacy-agreement".
• A contact whose newest completed agreement is a manually verified upload classified under a Client App + Agreement category, or marked as containing the application, can submit to Processing without an application, and its submission records applicationGateReason: "client-app-agreement". The same upload under an Agreement Only category without the checkbox stays blocked.
• A grandfathered in-flight contact can submit to Processing.
• An expired override or an override from a replaced form does not bypass the gate.
• A contact whose newest completed agreement was sent after activation and who has neither a captured application nor an override is blocked with the Processing Application requirement.
• Resend Application, on the Awaiting processing application row, removes and re-adds the workflow tag and produces a new client message with a working form link.
• Resend Application remains available in the Application tab after capture; a corrected submission appends to history and the newest submittedAt snapshot is displayed.
• The review step stays open after both artifacts land and only clears when the operator checks it.
• Operators can read the captured snapshot and processors can edit only the audited working copy from the Application tab.

​

Roll back

await fetch("/api/admin/processing-application-cutover", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${sessionStorage.getItem("fm_auth_token")}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action: "disable",
    locationId: "LOCATION_ID",
  }),
}).then((response) => response.json());