Connect HubSpot

Create or update a HubSpot contact from an accepted HoneyFalcon lead by matching the contact's email through the Contacts batch upsert API.

Why it matters

Email-based upsert reduces duplicate manual entry while preserving one repeatable mapping for contact properties. HoneyFalcon records the outbound HTTP result; HubSpot remains the source of truth for the final contact.

Where to work

Prepare the Service Key in the target HubSpot account. Then open Company -> Connectors, select New connector, choose HubSpot contact, and select Load preset.

Steps

1. In the target HubSpot account, create a Service Key with crm.objects.contacts.write permission and store it in a password manager.
2. Load the HubSpot contact preset in HoneyFalcon and confirm the batch-upsert Destination URL.
3. Paste the Service Key into Credential; leave the Bearer secret placeholder in Custom headers.
4. Review Payload fields and the request template, keeping idProperty set to email and using HubSpot's internal property names.
5. Confirm that Successful HTTP statuses contains 200.
6. Run Test draft with a unique synthetic email, then Create connector or Save changes and Activate the saved revision.
7. Accept a new synthetic lead, inspect Delivery history, and read the contact back in HubSpot by email.

See it in HoneyFalcon

Step 1 of 5: HubSpot preset selected in the connector editor.

Step 2 of 5: HubSpot destination and protected credential controls.

Step 3 of 5: HubSpot payload fields and request template.

Step 4 of 5: HubSpot request template and destination field mapping.

Step 5 of 5: HubSpot endpoint and Successful HTTP statuses to review before creation.

Configure an email-based HubSpot upsert

Use a customer-owned Service Key

Create the key for the target HubSpot account with crm.objects.contacts.write permission. Store the complete value securely because it is entered into HoneyFalcon as a write-only credential.

Do not paste the complete key into the request template, screenshots, or support evidence.

Keep the released batch-upsert contract

The preset posts to the Contacts batch upsert endpoint. Each input uses email as idProperty, so an existing contact with that email can be updated and a missing contact can be created.

The template's objectWriteTraceId uses the HoneyFalcon delivery ID to correlate the batch request. It is not a persistent HubSpot contact property.

Map internal HubSpot property names

The released template maps HoneyFalcon email, first name, last name, phone number, address, city, county, and postal code to HubSpot contact properties. Payload fields and template placeholders must remain synchronized.

If you add a HubSpot property, use its internal property name and select the corresponding HoneyFalcon field. Do not rely only on the display label shown in HubSpot.

Test, save, and activate in order

Test draft uses the visible values and a synthetic identity; it does not save the credential, create a revision, or add Delivery history.

Create connector or Save changes persists the reviewed revision. Activate then makes that saved revision available to new real deliveries.

Read the contact back

HTTP 200 is the preset's successful delivery contract. Delivered records that response, not the final values of every HubSpot property.

Search HubSpot by the synthetic email and compare the contact properties with the intended mapping before using the connector for production data.

The HubSpot connector is ready when

• The connector uses the Contacts batch-upsert endpoint, a scoped Service Key, idProperty email, and HTTP 200.
• Payload fields and HubSpot internal property names match the intended mapping.
• The saved connector can be activated without unsaved editor values.
• A synthetic delivery is traceable in HoneyFalcon and the contact read-back in HubSpot has the expected properties.

Continue learning

• Start from: For operations - start here
• Related guide: Edit and test safely
• Previous: Connect Make
• Next: Connect Pipedrive