Overview

HubSpot is a customer platform that brings together CRM, marketing, sales, and service tools. Organizations use HubSpot to manage contacts, companies, deals, and other records, track customer interactions, and automate business processes.

The Alchemer integration with HubSpot enables organizations to send survey and workflow data to HubSpot in real time. Teams can upsert contacts, create and update records across HubSpot objects, retrieve record data to personalize surveys and drive workflow logic, and send custom events to a record's timeline. By keeping HubSpot records synchronized with response data and automating downstream actions, this integration reduces manual data entry and improves the accuracy and timeliness of customer information.

Common uses for the Alchemer HubSpot integration

• Upsert contacts in HubSpot from survey responses to keep contact records current.
• Create records in a HubSpot object (contacts, companies, deals, and more) from workflow data.
• Update existing HubSpot records with survey or workflow data.
• Retrieve HubSpot record data to personalize surveys, enrich responses, or drive workflow logic.
• Send custom events to a HubSpot record's timeline for reporting and to trigger downstream workflows.

What can the Alchemer HubSpot integration do?

• Send custom event
• Upsert contact
• Create record
• Update record
• Get record

You will need

• HubSpot authentication (sign in with your HubSpot account). See HubSpot authentication.
• An Alchemer plan that includes integrations and the Integration Manager permission enabled.  
  • Contact us if you are unsure if your plan includes integrations.

OAuth Scope Requirements

Your HubSpot app must grant the following OAuth scopes for these actions to work.

For Get record, Create record, Update record, and Upsert contact:

• crm.objects.companies.read / .write
• crm.objects.contacts.read / .write
• crm.objects.custom.read / .write
• crm.objects.deals.read / .write

For Send custom event:

• analytics.behavioral_events.send
• behavioral_events.event_definitions.read_write

---

Setup Alchemer HubSpot integration in workflow

HubSpot | Send custom event

Send a custom event to a record in HubSpot. These events appear in the record's timeline for use in workflows and reporting.

You will need:

• HubSpot authentication
• Your internal event name
• A field used to find the record
• Fields used to create the event

Configure the action

1. Open your workflow in Workflow builder.
2. On the right side, drag and drop the HubSpot connection where you want the action to trigger.
3. In the connection box, click the pencil icon in the top right corner.
4. Select HubSpot | Send custom event.
5. HubSpot | Authentication: Select an existing authentication or create a new one.
6. HubSpot | Internal event name: Enter the internal name of the event you want to use. You must create a custom event in HubSpot first. Example: pe123456_my_custom_event.
7. HubSpot | Find record: Select the field in this workflow that contains the value used to find the record for your event. Choose only one. Record ID is recommended. Use the Data prep options to control how inputs are handled (for example, strip HTML tags from inputs).
8. HubSpot | Send custom event: Select the fields you want to use to create the custom event occurrence.
9. Save the action.

Status codes

• 200: Successfully sent custom event
• 400: The external integration returned an error

---

HubSpot | Upsert contact

Upsert a contact within HubSpot. If a matching contact is found it is updated; otherwise a new contact is created.

You will need:

• HubSpot authentication
• A field used to look up the contact (contact email)
• Fields used to upsert the contact

Configure the action

1. Open your workflow in Workflow builder.
2. On the right side, drag and drop the HubSpot connection where you want the action to trigger.
3. In the connection box, click the pencil icon in the top right corner.
4. Select HubSpot | Upsert contact.
5. HubSpot | Authentication: Select an existing authentication or create a new one.
6. HubSpot | Find record: Select the field in Alchemer you want to use to look up the contact for the upsert. This must be the contact email.
7. HubSpot | Upsert contact: Select the fields that contain the values you want to use to upsert the contact.
8. HubSpot | Get data back: Select the HubSpot fields you want returned.
9. Save the action.

Status codes

• 200: Successfully upserted record
• 400: The external integration returned an error

---

HubSpot | Create record

Create a record within a HubSpot object.

You will need:

• HubSpot authentication
• Fields used to create the record

Configure the action

1. Open your workflow in Workflow builder.
2. On the right side, drag and drop the HubSpot connection where you want the action to trigger.
3. In the connection box, click the pencil icon in the top right corner.
4. Select HubSpot | Create record.
5. HubSpot | Authentication: Select an existing authentication or create a new one.
6. HubSpot | Select object: Select the object type you want to create the record in (for example, Contacts, Companies, Deals, Calls, Meetings, or Notes).
7. HubSpot | Create record: Select the fields that contain the values you want to use to create the record.
8. HubSpot | Get data back: Select the HubSpot fields you want returned.
9. Save the action.

Status codes

• 200: Record was successfully created
• 400: The external integration returned an error

---

HubSpot | Update record

Update a record within a HubSpot object.

You will need:

• HubSpot authentication
• Fields used to find the record to update
• Fields used to update the record
• Fields to return

Configure the action

1. Open your workflow in Workflow builder.
2. On the right side, drag and drop the HubSpot connection where you want the action to trigger.
3. In the connection box, click the pencil icon in the top right corner.
4. Select HubSpot | Update record.
5. HubSpot | Authentication: Select an existing authentication or create a new one.
6. HubSpot | Select object: Select the object type that contains the record you want to update.
7. HubSpot | Find record: Select the fields that contain the values you want to use to find the specific record. Use the Select operator option (AND or OR) to control how multiple fields are combined when matching.
8. HubSpot | Update record: Select the fields that contain the values you want to use to update the record.
9. HubSpot | Get data back: Select the HubSpot fields you want returned.
10. Save the action.

Status codes

• 200: Record was successfully updated
• 202: Multiple records were found. Please update your query to select unique fields.
• 400: The external integration returned an error

---

HubSpot | Get record

Get a record from a HubSpot object. Use the returned values to personalize surveys, enrich responses, or drive workflow logic.

You will need:

• HubSpot authentication
• Fields used to find the record

Configure the action

1. Open your workflow in Workflow builder.
2. On the right side, drag and drop the HubSpot connection where you want the action to trigger.
3. In the connection box, click the pencil icon in the top right corner.
4. Select HubSpot | Get record.
5. HubSpot | Authentication: Select an existing authentication or create a new one.
6. HubSpot | Select object: Select the object type that contains the record you want to get.
7. HubSpot | Find record: Select the fields that contain the values you want to use to find the record.
8. HubSpot | Get data back: Select the HubSpot fields you want returned.
9. Save the action.

Status codes

• 200: A single record was successfully found
• 201: Query ran successfully, but no records were found
• 202: More than one record was found. The first record is used for the values returned to Alchemer.
• 400: The external integration returned an error

---

Testing and Validation

How to test

• Trigger the workflow and monitor individual runs in the Monitor tab in your workflow.
  • Click on individual workflow runs to see metadata outputs.
• Confirm the expected retrieval, update, creation, upsert, or event occurs in HubSpot.
• Use metadata for verification and debugging.

How to verify results

• Check the impacted record in HubSpot.
• Ensure retrieved or updated values match expectations.

---

Monitoring Integration Activity

 Where to find logs

• Go to Results → Monitor 
• Select the integration step you want to inspect.

What logs display

• Input/Output

---

Troubleshooting

Authentication issues

• Incorrect or expired OAuth session
• Missing required OAuth scopes in HubSpot

Lookup failures

• Invalid identifier values
• No matching records

Mapping errors

• Unsupported or invalid fields
• Incorrect formatting

API errors

• Validation issues
• Endpoint restrictions

---

FAQs