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 data to HubSpot in real time when a response is submitted. Teams can upsert contacts, create and update records across HubSpot objects, retrieve record data to personalize surveys, and send custom events to a record's timeline. By keeping HubSpot records synchronized with response data, 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 survey data.
• Update existing HubSpot records with survey data.
• Retrieve HubSpot record data to personalize surveys and enrich responses.
• Send custom events to a HubSpot record's timeline for reporting and to trigger downstream automation.

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 surveys

HubSpot | Send custom event

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

You will need:

• HubSpot authentication
• Your internal event name
• A survey field used to find the record
• Survey fields used to create the event

Configure the action

1. Open your survey in Survey Builder.
2. Select Add New: Action.
3. In the Add Action modal, scroll to the Your Integrations section.
4. Select HubSpot.
5. Select HubSpot | Send custom event.
6. HubSpot | Authentication: Select an existing authentication or create a new one.
7. 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.
8. HubSpot | Find record: Select the survey field 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).
9. HubSpot | Send custom event: Select the survey fields you want to use to create the custom event occurrence.
10. 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 survey field used to look up the contact (contact email)
• Survey fields used to upsert the contact

Configure the action

1. Open your survey in Survey Builder.
2. Select Add New: Action.
3. In the Add Action modal, scroll to the Your Integrations section.
4. Select HubSpot.
5. Select HubSpot | Upsert contact.
6. HubSpot | Authentication: Select an existing authentication or create a new one.
7. HubSpot | Find record: Select the survey field you want to use to look up the contact for the upsert. This must be the contact email.
8. HubSpot | Upsert contact: Select the survey fields that contain the values you want to use to upsert the contact.
9. HubSpot | Get data back: Select the HubSpot fields you want returned and map each to the Alchemer survey field you want to update.
10. 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
• Survey fields used to create the record

Configure the action

1. Open your survey in Survey Builder.
2. Select Add New: Action.
3. In the Add Action modal, scroll to the Your Integrations section.
4. Select HubSpot.
5. Select HubSpot | Create record.
6. HubSpot | Authentication: Select an existing authentication or create a new one.
7. HubSpot | Select object: Select the object type you want to create the record in (for example, Contacts, Companies, Deals, Calls, Meetings, or Notes).
8. HubSpot | Create record: Select the survey fields that contain the values you want to use to create the record.
9. HubSpot | Get data back: Select the HubSpot fields you want returned and map each to the Alchemer survey field you want to update.
10. 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
• Survey fields used to find the record to update
• Survey fields used to update the record

Configure the action

1. Open your survey in Survey Builder.
2. Select Add New: Action.
3. In the Add Action modal, scroll to the Your Integrations section.
4. Select HubSpot.
5. Select HubSpot | Update record.
6. HubSpot | Authentication: Select an existing authentication or create a new one.
7. HubSpot | Select object: Select the object type that contains the record you want to update.
8. HubSpot | Find record: Select the survey 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.
9. HubSpot | Update record: Select the survey fields that contain the values you want to use to update the record.
10. HubSpot | Get data back: Select the HubSpot fields you want returned and map each to the Alchemer survey field you want to update.
11. 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 survey questions or enrich responses.

You will need:

• HubSpot authentication
• Survey fields used to find the record

Configure the action

1. Open your survey in Survey Builder.
2. Select Add New: Action.
3. In the Add Action modal, scroll to the Your Integrations section.
4. Select HubSpot.
5. Select HubSpot | Get record.
6. HubSpot | Authentication: Select an existing authentication or create a new one.
7. HubSpot | Select object: Select the object type that contains the record you want to get.
8. HubSpot | Find record: Select the survey fields that contain the values you want to use to find the record.
9. HubSpot | Get data back: Select the HubSpot fields you want returned and map each to the Alchemer survey field you want to update.
10. 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

• Submit a survey response with data that triggers the integration action.
• Confirm the expected activity occurs in HubSpot (record created, updated, or retrieved, or event sent).
• Use the returned values and metadata to validate successful behavior.

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 → Individual Responses.
• Select the response you want to inspect.
• Open the Action Log tab.

What logs display

• Success or failure status
• Timestamp
• Input and output values
• Returned status codes from HubSpot

---

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