如何将潜在客户捕获应用对接HubSpot创建联系人API并适配格式

Got it, let's walk through how to convert your lead JSON into the exact structure HubSpot's API expects. First, let's start with the finished converted example, then break down the key mappings and considerations.

Converted JSON Example #

{
  "email": "twst@email.com",
  "properties": [
    { "property": "company", "value": "Test" },
    { "property": "website", "value": "https://www.test.com" },
    { "property": "firstname", "value": "Carl" },
    { "property": "lastname", "value": "Swann" },
    { "property": "jobtitle", "value": "Dr" },
    { "property": "phone", "value": "0789654321" },
    { "property": "products", "value": "Khaos Control Hybrid" },
    { "property": "notes", "value": "Here are the notes " },
    { "property": "contact_owner", "value": "cswann@khaoscontrol.com" },
    { "property": "show_name", "value": "Spring Fair" }
  ]
}

Key Mapping Details #

Let's break down how each of your original fields maps to HubSpot's structure:

1. Standard HubSpot Properties #

HubSpot uses lowercase internal names for its built-in properties, so we'll map your fields accordingly:

• CompanyName → company (HubSpot's standard company name property)
• Website → website (Pro tip: Always add https:// or http:// to URLs—HubSpot will treat them as clickable links and validate them better)
• FirstName → firstname
• LastName → lastname
• JobTitle → jobtitle
• Phone → phone
• Email → Top-level email field (this is critical for HubSpot to detect duplicate contacts; you can also include it in the properties array, but the top-level field is preferred for deduplication)

2. Custom Properties #

Fields like Products, Notes, ContactOwner, and ShowName are likely custom properties in your HubSpot portal (since they aren't standard HubSpot fields). For these:

• You need to use their internal names from HubSpot (not the display names you see in the UI). To find these:
  1. Go to HubSpot Settings → Properties
  2. Search for the property
  3. Check the "Internal name" field (e.g., if you named your show field "Show Name", the internal name might be show_name)
• In the example above, I used plausible internal names (products, notes, contact_owner, show_name)—replace these with your actual internal names if they differ.

Bonus Tips #

• Contact Owner: Instead of using an email, you can use the HubSpot user ID for the contact owner. This is more reliable because emails can change, but user IDs stay the same. You can find user IDs in HubSpot Settings → Users & Teams.
• Deduplication: The top-level email field is how HubSpot determines if a contact already exists. If you want to update an existing contact instead of creating a new one, make sure this email matches the existing contact's email.
• Validation: HubSpot will return errors if you use invalid property names or values (e.g., a phone number with invalid characters). Test with a single lead first to catch any issues.

内容的提问来源于stack exchange，提问作者Swanne