Review Typeform Responses Before Adding HubSpot Contacts With Codex

To review Typeform responses before adding HubSpot contacts with Codex, keep the workflow in three separate approvals: read at most ten completed responses from one form and date range, search HubSpot for each approved email, then create only the contacts a person explicitly accepts. Do not let a response read silently become CRM enrollment, lifecycle-stage changes, lead scoring, or outreach.

This guide is for operations and growth teams that want a useful Typeform-to-HubSpot handoff without turning every submission into an automatic sales record. Success means Codex produces a small review queue, proves that duplicates were checked, creates only approved contacts, and reads back the resulting HubSpot record IDs. It does not qualify leads or send messages.

Use a Three-Step Approval Boundary

The current Aident catalog exposes these as separate Actions. That separation is useful: authentication proves an account is available, while each Action and input defines a different consequence.

Prerequisites

You need:

• the Aident Loadout CLI available to Codex;

• authority to connect the intended Typeform and HubSpot accounts;

• one approved Typeform form ID;

• the exact field IDs for email, first name, and last name;

• an explicit UTC time window; and

• a person who can approve or reject each proposed contact.

Do not paste Typeform or HubSpot tokens into the prompt. Use Aident Vault for the connections, and keep raw responses out of repositories, tickets, and reusable prompts.

1. Confirm Both Connections

Start with account and Vault status:

aident account auth status
aident vault status --integrationId "composio:typeform_tools" --json
aident vault status --integrationId "composio:hubspot_tools" --json

Confirm the intended accounts before any provider execution. During this review on September 12, 2026, both integrations were available in the staging catalog but disconnected in the reviewed Vault. The commands below were schema-checked and preflighted with placeholders; no private response or CRM record was read or changed.

2. Inspect the Current Actions

Discover by job, then inspect the exact contracts:

aident capabilities search \
  --query "read recent completed responses from one Typeform form" \
  --json

aident capabilities get \
  --name "composio:typeform_tools:typeform_get_form_responses" \
  --json

aident capabilities search \
  --query "find a HubSpot contact by exact email before creating a duplicate" \
  --json

aident capabilities get \
  --name "composio:hubspot_tools:hubspot_search_contacts_by_criteria" \
  --json

The reviewed Typeform contract requires form_id and can bound the request with since, until, page_size, response_type, and specific field IDs. Its description warns that recent responses may take up to 30 minutes to appear. Typeform's public Responses API documentation recommends webhooks for real-time delivery, so a polling review should not be presented as instant.

The reviewed HubSpot search contract accepts an exact email filter, a one-row limit, and a short property list. HubSpot's CRM Search API documents the same filter-group model, and its Contacts API documents email as a supported contact lookup key.

3. Preflight One Bounded Typeform Read

Replace only the approved placeholders, then preflight:

aident capabilities preflight \
  --name "composio:typeform_tools:typeform_get_form_responses" \
  --input '{
    "form_id":"<APPROVED_FORM_ID>",
    "since":"2026-09-05T00:00:00Z",
    "until":"2026-09-12T00:00:00Z",
    "page_size":10,
    "response_type":["completed"],
    "fields":[
      "<EMAIL_FIELD_ID>",
      "<FIRST_NAME_FIELD_ID>",
      "<LAST_NAME_FIELD_ID>"
    ]
  }'

This exact placeholder shape passed Aident schema validation with a free quote on September 12, 2026. Preflight does not prove the form exists, the account can access it, or the returned answers are safe to retain.

Execute only after the form, dates, fields, and row ceiling are approved. Keep the response token in the local review record as a duplicate-processing key, but do not send it to HubSpot unless a reviewed custom property is designed for that purpose.

4. Build a Minimal Review Queue

Normalize each completed response into a local table:

Reject or escalate rows that have no email, malformed email, unexpected fields, unapproved consent, or a response version that no longer matches the reviewed mapping. Do not infer company, seniority, lifecycle stage, lead score, or commercial intent from free text.

5. Search HubSpot Before Creating Anything

For one reviewed email, preflight an exact duplicate check:

aident capabilities preflight \
  --name "composio:hubspot_tools:hubspot_search_contacts_by_criteria" \
  --input '{
    "filterGroups":[{
      "filters":[{
        "propertyName":"email",
        "operator":"EQ",
        "value":"<APPROVED_EMAIL>"
      }]
    }],
    "properties":["email","firstname","lastname","hs_object_id"],
    "limit":1
  }'

The placeholder shape also passed free preflight. If a contact exists, stop the create path and present the record ID for review. Do not update the existing record merely because the submitted name differs. A spelling change, reused address, existing customer, or shared inbox may require a human decision.

6. Create One Approved Contact

Inspect the create Action immediately before use:

aident capabilities get \
  --name "composio:hubspot_tools:hubspot_create_contact" \
  --json

Then preflight only the approved properties:

aident capabilities preflight \
  --name "composio:hubspot_tools:hubspot_create_contact" \
  --input '{
    "email":"<APPROVED_EMAIL>",
    "firstname":"<APPROVED_FIRST_NAME>",
    "lastname":"<APPROVED_LAST_NAME>"
  }'

The reviewed create contract exposes many optional HubSpot fields. That breadth is not permission to populate them. The minimal placeholder passed free preflight on September 12. Execute it only after a person approves that exact contact and consequence.

After creation, read back the contact ID, email, first name, and last name. Record the Typeform response token locally, the approving person or checkpoint, the HubSpot record ID, and the execution receipt. Stop before adding a company, deal, list membership, owner, lifecycle stage, task, note, or marketing enrollment.

Common Failure Modes

A recent response is missing

The Typeform Action notes that recent responses can take up to 30 minutes to appear. Wait for the documented availability window or use a separately reviewed webhook workflow. Do not widen the form or date scope as a debugging shortcut.

HubSpot finds an existing contact

Treat that as a successful duplicate check, not a failed workflow. Return the existing record for review and do not create or update anything.

The form changed after mapping

Stop when field IDs or form version no longer match the approved mapping. Re-inspect the form schema and obtain a fresh review before reading or creating records.

The agent wants to score or contact the respondent

Return a recommendation only. Lead qualification, lifecycle changes, and outreach are separate consequences with separate evidence and approval requirements.

Reusable Codex Prompt

Use Aident Loadout. Confirm the intended Typeform and HubSpot Vault
connections, then inspect the current response-read, contact-search, and
contact-create Action schemas. Do not execute a provider Action yet.

After I approve one form, UTC date range, completed responses, three field
IDs, and a ten-row maximum, preflight the Typeform read. Execute only that
identical input. Build a local review queue containing response token, email,
first name, and last name. Do not return hidden fields, files, partial
responses, or unrelated answers.

For each row I approve, search HubSpot by exact email with limit 1 and return
only email, name, and record ID. If a match exists, stop that row. If no match
exists, show the exact three-field create payload and wait for approval.
Create only an approved contact, read back its record ID and three fields,
then stop. Do not update records, score leads, change lifecycle stages, create
deals or tasks, enroll contacts, or send messages

Connect Typeform and HubSpot, then review one ten-response batch

First complete the Typeform-to-Copilot connection check if the Typeform connection is not yet verified. Use the risk-versus-spend approval workflow before the first CRM write. For the general discovery, Vault, preflight, execution, and Audit loop, continue with How to Use Aident Loadout.

Sources

• Typeform Responses API, reviewed September 12, 2026.

• HubSpot CRM Search API, reviewed September 12, 2026.

• HubSpot Contacts API, reviewed September 12, 2026.

• Aident Loadout setup, reviewed September 12, 2026.

• Live Aident Loadout staging Typeform and HubSpot Action schemas plus three exact free preflights, inspected September 12, 2026.

Refresh this guide when Typeform changes response availability, filters, or field behavior; HubSpot changes contact search, uniqueness, or create properties; or Aident changes either integration's schema, risk metadata, pricing, connection flow, or Audit behavior.