Update HubSpot Object

Update contacts, deals, companies, and other HubSpot records with new information. Common uses:

Update deal stages when deals progress
Change contact properties based on form submissions
Update company information from webhook data
Modify ticket status and priority

Action type: hubspot.v2.update_object

What This Does (The Simple Version)

Think of this like editing a contact card in your phone. You find the person (by their name, email, or phone number), then update whatever details changed. Real-world example: A customer fills out a “Request Enterprise Demo” form. You use this action to find their contact record by email and update their lifecycle_stage to “Sales Qualified Lead” and set demo_requested to “Yes”.

How It Works

This action finds a HubSpot record and updates it with new property values. You choose:

What type of record to update (contact, deal, company, etc.)
How to find it (by ID, email, or domain)
Which properties to update
What values to set

The updated record is saved to a variable you can use in later actions.

Setting It Up

Step 1: Choose Object Type

When you add the Update HubSpot Object action, you’ll see clickable cards for each object type:

Contacts - People in your CRM
Companies - Organizations
Deals - Sales opportunities
Tickets - Support tickets
Calls - Call records
Emails - Email engagement records
Meetings - Meeting records
Notes - Notes attached to records
Tasks - Tasks in HubSpot

Click the card for the type you want to update.

Step 2: Choose How to Find the Record

After selecting the object type, you’ll see a “Identify by” dropdown with different lookup methods: For Contacts:

Lookup by Object ID - If you have the HubSpot ID
Lookup by Email - Find by email address

For Companies:

Lookup by Object ID - If you have the HubSpot ID
Lookup by Domain - Find by company domain (e.g., “acme.com”)

For all other objects (Deals, Tickets, etc.):

Lookup by Object ID - Only option (must have the HubSpot ID)

Choose your method from the dropdown.

Step 3: Enter the Identifier

In the identifier field below the dropdown, enter the value to find the record: Examples:

If you chose “Lookup by Email”: Enter [email protected] or click {} to insert an email variable
If you chose “Lookup by Domain”: Enter acme.com or click {} to insert a domain variable
If you chose “Lookup by Object ID”: Enter 12345 or click {} to insert an ID variable from a previous action

Using variables: Click the {} button to insert a variable from previous actions. Common patterns:

Email from webhook: Click {} → select contact_email (from your trigger)
ID from search: Click {} → select current_deal → hs_object_id (from a loop)

Step 4: Add Properties to Update

In the “Update Contact Properties” section (or “Update Deal Properties”, etc.), click the ”+ Add Property” button to select which properties you want to update. This opens a property picker modal showing:

Search bar at the top
List of all available properties for that object type
Click properties to select them (they’ll show a checkmark)
Click Done when finished

After closing the modal, you’ll see individual input fields for each property you selected. For each property:

The field is labeled with the property name (e.g., “Lifecycle Stage”, “Deal Stage”, “City”)
Type the new value directly, OR
Hover over the field to see the {} button, then click it to insert a variable

Example - Updating a contact:

Click ”+ Add Property”
Select lifecycle_stage, deal_stage_requested, city
Click Done
Now you see three fields:
- Lifecycle Stage: Type “Sales Qualified Lead”
- Deal Stage Requested: Type “Yes”
- City: Click {} → select form_city (from webhook)

Tips:

Only add properties you actually want to change (you don’t need to include properties that aren’t changing)
Use the property picker to avoid typos
Click {} to insert variables from triggers, previous actions, or loop items

Step 5: Name Your Output Variable

Give the updated record a descriptive name in the “Output Variable Name” field. Good names:

updated_contact
updated_deal
modified_ticket
current_record

This variable contains the full record with all its properties after the update.

What You Get Back

The action returns the complete updated object with all its properties (not just the ones you changed). Example: If you updated a contact’s lifecycle_stage and selected properties firstname, email, lifecycle_stage: Output saved to updated_contact:

{
  "id": "12345",
  "properties": {
    "firstname": "Jane",
    "email": "[email protected]",
    "lifecycle_stage": "salesqualifiedlead"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-10-01T14:22:00Z"
}

Note: The full record is returned, but you control which properties are visible by what you selected in the property picker.

Using the Results

Access Updated Properties

After the update action, use the output variable to access the updated record: In any field that accepts variables:

Click the Insert Variable button ({} icon)
Navigate to your output variable (e.g., updated_contact)
Select the property you want (e.g., id, properties → email)

In a Loop

If you’re updating multiple records in a loop: Example workflow:

Search HubSpot (V2) - Find contacts matching criteria, save to contacts_to_update
For Loop - Loop through contacts_to_update, current item: current_contact
Update HubSpot Object (V2) - Inside the loop:
- Object Type: Contacts
- Identify by: Lookup by Object ID
- Identifier: Click {} → current_contact → hs_object_id
- Update properties (e.g., set last_contacted to today)
- Output Variable: updated_contact
End Loop

Check If Update Succeeded

The update either succeeds (returns the full record) or throws an error. If the record isn’t found or credentials are wrong, the workflow stops with an error message.

Common Workflows

Update from Form Submission

Goal: When someone fills out a form, update their contact record Trigger: Webhook from HubSpot form Webhook receives: email, requested_demo variables

Update HubSpot Object (V2)
- Object Type: Contacts
- Identify by: Lookup by Email
- Identifier: Click {} → select email (from webhook)
- Update Properties: Click ”+ Add Property” and select:
  - demo_requested: Set to “Yes”
  - lifecycle_stage: Set to “Sales Qualified Lead”
- Output Variable: updated_contact
Send notification or continue workflow…

Update Deal Stage in Loop

Goal: Move multiple deals to the next stage

Search HubSpot (V2)
- Object Type: Deals
- Search Filters: Click ”+ Add Property”
  - Property: Deal Stage
  - Operator: Equals
  - Value: “presentationscheduled”
- Retrieve Properties: Select dealname, hs_object_id
- Output Variable: deals_to_progress
For Loop
- Loop through: deals_to_progress
- Current item: current_deal
Update HubSpot Object (V2) - inside loop
- Object Type: Deals
- Identify by: Lookup by Object ID
- Identifier: Click {} → current_deal → hs_object_id
- Update Properties: Click ”+ Add Property”
  - dealstage: Set to “decisionmakerboughtin”
- Output Variable: updated_deal
End Loop

Update Company by Domain

Goal: Update a company’s information when you know their domain Trigger: Manual or webhook with company domain

Update HubSpot Object (V2)
- Object Type: Companies
- Identify by: Lookup by Domain
- Identifier: Type “acme.com” or click {} to insert domain variable
- Update Properties: Click ”+ Add Property”
  - industry: Set to “Technology”
  - company_size: Set to “500+”
- Output Variable: updated_company

Real Examples

Contact Lifecycle Update

Scenario: When a contact downloads a whitepaper, update their lifecycle stage. Webhook receives: email variable from form Update Configuration:

Object Type: Contacts
Identify by: Lookup by Email
Identifier: Click {} → select email (from webhook)
Update Properties: Click ”+ Add Property” and select:
- lifecycle_stage: “marketingqualifiedlead”
- last_engagement_date: Click {} → select today (system variable)
- content_downloads: Click {} → select download_count (from previous action)
Output Variable: updated_contact

Next steps: Send confirmation email using updated contact data.

Deal Amount Update

Scenario: When a deal reaches “Contract Sent” stage, update the expected close date. Trigger: Manual or scheduled Update Configuration:

Object Type: Deals
Identify by: Lookup by Object ID
Identifier: Click {} → select deal_id (from search or webhook)
Update Properties: Click ”+ Add Property” and select:
- closedate: Click {} → select thirty_days_from_now (calculated variable)
- dealstage: “contractsent”
Output Variable: updated_deal

Troubleshooting

Record Not Found

Error: “Object not found” or “No record with that email/domain” Possible causes:

The email/domain/ID doesn’t exist in HubSpot
Typo in the identifier value
Using wrong identification method

How to fix:

Check HubSpot manually - does the record exist?
Verify the identifier value (email is case-insensitive, but check for typos)
For email lookup, make sure you selected “Contacts” (not Companies or Deals)
For domain lookup, make sure you selected “Companies” (not Contacts)
Check the execution log to see the exact value that was used

”Missing OAuth Scope” Error

You don’t have permission to update that object type How to fix:

Go to Settings → Integrations
Click “Reconnect” on HubSpot
Make sure you check the box to authorize WRITE access to that object type
Save and try the update again

Required permissions by object:

Contacts: “Write Contacts” (not just “Read Contacts”)
Companies: “Write Companies”
Deals: “Write Deals”
Tickets: “Write Tickets”

Properties Not Updating

The action succeeds but properties don’t change Possible causes:

Property name is misspelled
Property value format is wrong (e.g., date format)
Property is read-only in HubSpot
Property doesn’t exist for that object type

How to fix:

Use the ”+ Add Property” button to select from actual HubSpot properties (avoids typos)
Check HubSpot → Settings → Properties to see valid values for that property
Look at a HubSpot record to see the expected format (dates, picklists, etc.)
Try updating the property manually in HubSpot to verify it’s editable
Check the execution log - the response shows which properties were actually updated

No Properties Selected

Error: “At least one property is required to update an object” How to fix:

Click the ”+ Add Property” button
Select at least one property to update
Enter a value for that property
Make sure you clicked “Done” in the property picker modal

Tips & Best Practices

✅ Do:

Use the ”+ Add Property” button to browse and select from your actual HubSpot properties
Use “Lookup by Email” for contacts when you have their email (more reliable than searching)
Use “Lookup by Domain” for companies when you know the domain
Always use hs_object_id when you have it (fastest, most reliable)
Test with a single record before running in a loop on hundreds of records
Use descriptive output variable names

❌ Don’t:

Try to update properties that don’t exist for that object type
Forget to check permissions (need WRITE access, not just READ)
Assume email/domain lookup works for all object types (Contacts/Companies only)
Update properties that are managed by HubSpot workflows (may get overwritten)

Performance tips:

Updating by Object ID is fastest (no extra lookup required)
Only update properties that actually changed (don’t update everything)
If updating many records, use a loop with reasonable batch sizes (100-500)

What to do next:

Search HubSpot (V2) - Find records to update
Lookup HubSpot Object (V2) - Get record details before updating
For Loop - Update multiple records one by one
If Condition - Conditionally update based on property values

Related guides:

Variable System - Using variables in update values
HubSpot Setup - Getting write permissions

Last Updated: 2025-10-01

Using Agent.ai

For Builders

Actions

What This Does (The Simple Version)

How It Works

Setting It Up

Step 1: Choose Object Type

Step 2: Choose How to Find the Record

Step 3: Enter the Identifier

Step 4: Add Properties to Update

Step 5: Name Your Output Variable

What You Get Back

Using the Results

Access Updated Properties

In a Loop

Check If Update Succeeded

Common Workflows

Update from Form Submission

Update Deal Stage in Loop

Update Company by Domain

Real Examples

Contact Lifecycle Update

Deal Amount Update

Troubleshooting

Record Not Found

”Missing OAuth Scope” Error

Properties Not Updating

No Properties Selected

Tips & Best Practices

Using Agent.ai

For Builders

Actions

​What This Does (The Simple Version)

​How It Works

​Setting It Up

​Step 1: Choose Object Type

​Step 2: Choose How to Find the Record

​Step 3: Enter the Identifier

​Step 4: Add Properties to Update

​Step 5: Name Your Output Variable

​What You Get Back

​Using the Results

​Access Updated Properties

​In a Loop

​Check If Update Succeeded

​Common Workflows

​Update from Form Submission

​Update Deal Stage in Loop

​Update Company by Domain

​Real Examples

​Contact Lifecycle Update

​Deal Amount Update

​Troubleshooting

​Record Not Found

​”Missing OAuth Scope” Error

​Properties Not Updating

​No Properties Selected

​Tips & Best Practices

​Related Actions

What This Does (The Simple Version)

How It Works

Setting It Up

Step 1: Choose Object Type

Step 2: Choose How to Find the Record

Step 3: Enter the Identifier

Step 4: Add Properties to Update

Step 5: Name Your Output Variable

What You Get Back

Using the Results

Access Updated Properties

In a Loop

Check If Update Succeeded

Common Workflows

Update from Form Submission

Update Deal Stage in Loop

Update Company by Domain

Real Examples

Contact Lifecycle Update

Deal Amount Update

Troubleshooting

Record Not Found

”Missing OAuth Scope” Error

Properties Not Updating

No Properties Selected

Tips & Best Practices

Related Actions