Before you begin

  • Create a HubSpot private app or OAuth app with contact create/update permissions.
  • Decide whether email or another unique property will be used for upsert behavior.
  • Create any custom properties you want to store, such as `instachime_lead_id`, `lead_score`, `source_platform`, and `sentiment`.
  • Use a bridge, Zapier, or Make to receive the InstaChime webhook and call HubSpot.

Contact mapping

  • `lead.email` -> `email`
  • `lead.customer_name` -> split to `firstname` and `lastname` when possible
  • `lead.phone` -> `phone`
  • `lead.company` or `lead.company_domain` -> company-related properties
  • `lead.source_platform` -> `hs_analytics_source_data_1` or a custom source property
  • `lead.lead_score`, `lead.sentiment`, `lead.id` -> custom properties

Create contact payload

{
  "properties": {
    "email": "jamie@example.com",
    "firstname": "Jamie",
    "lastname": "Lee",
    "phone": "+15555550123",
    "company": "Acme",
    "lifecyclestage": "lead",
    "instachime_lead_id": "lead_uuid",
    "lead_score": "82"
  }
}

Verify

  • Send an InstaChime sample webhook through the HubSpot bridge.
  • Confirm a contact is created or updated with the expected properties.
  • Save the HubSpot contact ID or upsert response in the webhook delivery response.
  • Confirm a duplicate email updates the intended contact instead of creating an unwanted duplicate.

Exact HubSpot setup

  • In HubSpot, create a private app or OAuth app for the integration.
  • Grant contact read/write scopes and any company/deal scopes your workflow needs.
  • Create custom contact properties for `instachime_lead_id`, `source_platform`, `lead_score`, `sentiment`, `campaign`, and `first_response_status` if you want them visible in HubSpot.
  • Decide whether to create only contacts or also companies/deals.
  • Build a bridge, Zap, or Make scenario that receives InstaChime `lead.created`.
  • Use HubSpot create, update by email, or batch upsert according to your dedupe policy.
  • Return the HubSpot contact ID to InstaChime in the delivery response.

HubSpot upsert recommendation

  • Use email as the first matching key when the lead has an email address.
  • Use a custom unique property only if you want HubSpot records keyed by InstaChime lead ID or another external ID.
  • Avoid overwriting lifecycle stage backward unless your HubSpot process intentionally clears it first.
  • Preserve the original lead source in a custom field if HubSpot source fields are managed by tracking code or forms.
  • Add notes or timeline events through an additional bridge step if sales needs to see the original lead message.

HubSpot troubleshooting

  • If HubSpot returns a scope error, update the private app scopes and reinstall or regenerate the token.
  • If duplicate contacts appear, confirm whether your bridge creates contacts every time instead of updating by email.
  • If lifecycle stage does not change, check HubSpot lifecycle-stage rules.
  • If custom properties reject values, confirm field type and internal property names.
  • If workflows fire unexpectedly, review which properties the integration updates on existing contacts.

Official references

These vendor-owned pages explain the controls and requirements referenced in this guide.

  • HubSpot CRM contacts APIOfficial documentation used to verify this setup path and its current vendor requirements.
  • HubSpot private appsOfficial documentation used to verify this setup path and its current vendor requirements.