Build with

Capture a sales enquiry after applying an explicit business rule and confirming the customer’s details. The worked example creates a HubSpot contact with lifecycle stage lead, retains its ID and tells the customer what was recorded. It does not send an email, book a meeting or create a deal.

Before you begin

  • A test project with HubSpot CRM action OAuth, and an administrator-approved lifecycle value. Code uses the same browser-authorized connection.
  • The fields your sales team needs, an approved contact/consent policy and a place to persist the returned record ID with the enquiry.
  • An explicit qualification rule. This example qualifies enquiries for 20 or more seats where the person requests sales follow-up; that threshold is illustrative business policy, not a Voiceflow or HubSpot rule.

Studio

Open your test project in Agent studio. Prepare a Workflow that collects the qualification answers, name, email and company, then asks the customer to confirm the summary before writing. Use a Workflow condition or a backend check when the qualification gate must be enforced.

Code

Use a Voiceflow bearer credential with access to this project and test Environment; keep it on your backend. Set VF_TOKEN, PROJECT_ID and ENVIRONMENT before using the commands. Standalone execution uses the Environment’s Draft. For native CRM actions, complete the browser OAuth in the prerequisite manual even when working through Code.

Qualify and save the enquiry

1

Apply the qualification rule

Studio

In More → Variables, create seat_count, requested_followup and details_confirmed, initially 0, and retain any existing verified CRM record ID in your application’s mapping. Collect a numeric seat count and set requested_followup to 1 only for an explicit request. Keep details_confirmed at 0 until the customer confirms the collected summary.

In a Workflow, add a Condition step immediately before the Create contact step. Choose Match all and require seat_count to be at least 20, requested_followup to equal 1 and details_confirmed to equal 1. Connect only the matching branch to creation; connect the unmatched branch to confirmation or self-service. Route an existing verified record to its existing-record path before this gate. The tool Trigger describes usage; the Condition/backend gate enforces sequencing.

Code

Validate the seat count, follow-up request and saved confirmation on your backend. Use the deterministic enquiryDecision gate shown in the save step below before invoking the CRM action. Keep an existing verified CRM mapping on its existing-record path.

Ask how many seats the customer needs and whether they want sales follow-up. Under the example policy, 25 seats with requested follow-up qualifies; 5 seats or no follow-up request does not. Offer the relevant self-service path when the rule does not pass. Never infer consent from an email address alone.

2

Confirm the information to save

Collect Maya Chen, maya@example.com and Example Company as illustrative details. Show the summary and ask for confirmation. If a verified existing CRM mapping is available, use its existing-record workflow; do not create another contact for every visit. Do not reveal a record merely because the visitor typed an email that matches it.

3

Create one contact and retain its ID

Studio

On the Condition’s matching branch only, add an Integration step and choose HubSpot → Create contact. Keep that write out of Global tools and other branches so it cannot bypass the gate. Set firstname, lastname, email, company and the approved lifecyclestage. Run only after the confirmation gate passes. Inspect the real result and use Capture response to retain the contact ID.

The shared tool editor shows the contact fields; the Workflow gate controls when the write can run. Photo:

Code

Download requests.mjs beside your backend script. Apply its deterministic example policy to validated data and the confirmation/mapping retained by your application:

The values above are fixtures; substitute the actual validated enquiry and saved customer confirmation. The module returns self-service below the threshold or without follow-up, confirm without confirmation, and existing-record when a mapping already exists. Its fixture tests cover each branch. Execute this action only after that gate passes:

Require success: true, error: null and truncated: false; retain output.data.contact.id. If your backend accepts arbitrary customer text, apply the nativeCRMInputs guard and the one-run input interpolation rules: brace-shaped Secret tokens are interpreted in top-level strings, not automatically treated as literal text.

Open the same Contact in HubSpot and compare name, email, company and lifecycle stage. Create lead also creates a Contact but does not set its lifecycle stage in the current handler; its label is not the qualification rule.

4

Confirm the result and arrange the next action

Tell the customer that the enquiry was recorded only after a successful write. Retain the ID and confirmation with the request. If your team needs an assigned work item, follow Create and route follow-up; creating the Contact alone does not assign that work.

For Salesforce, use Create lead with FirstName, LastName, Email and Company, and retain the returned Lead Id. That is a separate Salesforce object, not a HubSpot lifecycle stage.

Verify the qualification journey

Test a qualifying confirmed enquiry, one below the threshold, a declined confirmation and an existing customer. Only the intended creation path may write. After an uncertain response, reconcile the CRM record before retrying; a duplicate create or a successful write followed by a failed read can otherwise produce another record. Confirm one saved record and the approved customer-facing acknowledgement.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.