Association labels in Import API

[HunorSZ]

Hello, community!

I faced an issue a few days ago and haven't managed to find a solution in the documentation or in the community. So I've decided to post it here along with the solution.

The problem

Using Import API V3 to import multiple objects in a single file and associate these objects with association labels.

Solution

Part 1: Build import csv file for multiple objects plus associations (without association labels this time)

Step 1: I've created the column mapping as described here. I've added all the properties for all the objects with I wanted to import in the json.

Note: columnName is used to match the columns in the csv or excel file and it doesn't matter if it's the same as the HubSpot label of the property.

{
  "name": "myImport",
  "files": [
    {
      "fileName": "myData.csv",
      "fileFormat": "CSV",
      "dateFormat": "DAY_MONTH_YEAR",
      "fileImportPage": {
        "hasHeader": true,
        "columnMappings": [
          {
            "columnObjectTypeId": "0-1",
            "columnName": "contact|firstname",
            "propertyName": "firstname",
            "idColumnType": null
          },
          {
            "columnObjectTypeId": "0-1",
            "columnName": "contact|lastname",
            "propertyName": "lastname",
            "idColumnType": null
          },
          {
            "columnObjectTypeId": "0-1",
            "columnName": "contact|email",
            "propertyName": "email",
            "idColumnType": "HUBSPOT_ALTERNATE_ID"
          },
          {
            "columnObjectTypeId": "0-2",
            "columnName": "company|name",
            "propertyName": "name",
            "idColumnType": null
          },
          {
            "columnObjectTypeId": "0-2",
            "columnName": "company|domain",
            "propertyName": "domain",
            "idColumnType": "HUBSPOT_ALTERNATE_ID"
          }
        ]
      }
    }
  ]
}

Step 2: I've created a header for the csv file with all the properties for all the objects (same as the column mapping, in the same order).

Step 3: I've added in separate rows the data for each object.

Note: don't try to save place by adding 2 or more different objects in one row (I know you could), because you will lose the customizability of the associations between them. More on this later.

Step 4: I've added the associations rows below the data rows, by filling only the 2 or more objects' HUBSPOT_ALTERNATE_ID or HUBSPOT_OBJECT_ID columns.

Until this part, after spending several hours reading documentation and experimenting, you could figure out this technique on your own.

Part 2: Add association labels

Ok, so this is the trickier part because it's not documented at the time I'm writing this little tutorial.

Step 1: I've created a new USER_DEFINED association label in the first object, which I wanted to associate with the second one.

More on working with associations here and here.

Step 2: I've added a new column mapping item to the json, at the last place in the columnMapping array.

{
   "columnObjectTypeId": "0-1",
   "toColumnObjectTypeId": "0-2",
   "columnName": "contact|association_label",
   "propertyName": null,
   "idColumnType": "FLEXIBLE_ASSOCIATION_LABEL"
}

Explanation:

• columnObjectTypeId: the ID of the object where the association label was created
• toColumnObjectTypeId: the ID of the associated object
• columnName: has to match the column header from the csv or excel sheet
• propertyName: this has to be null
• idColumnType: this is the tricky part that you won't find anywhere. This will be equal to "FLEXIBLE_ASSOCIATION_LABEL", in order to signal to HubSpot, that this column will be used to identify association labels

Step 3: I've added the association labels to the csv under the column I've created (contact|association_label) after all the other columns.

Note: If you have more than one, separate them with semicolons.

After these steps, I built the request and sent it to HubSpot. For that, you can find documentation here. 

Many thanks to Gonzalo Torreras, who helped me figure out the solution.

Hopefully, this will help many of you.

Wish you all a wonderful day,

Hunor Szondi

[MDev28]

Import API does saves a lot of hassle of dealing with object associations, currently working on multifle imports .

[rocketman22]

Hello @HunorSZ,

First of all, thank you for your post. It helped me a lot with a use case I was solving, which involves file imports between contacts and deals.

If you'll allow me, I have a question about a new use case that is very similar to this one, but unfortunately this solution didn't work. Or at least what I tried to do.

It would basically be using the association between the same object (contacts to contacts).

All my attempts to populate the column with the association label always led to the same error when importing the file: "Association label not found". Despite the existence of these labels in HubSpot.

Have you ever experienced this type of situation? Do you have any advice to give?

Thank you,

rocketman22

[MDev28]

Try using associationtype id , it should be in documentation contacts to contacts.

[SIves6]

Do you happen to have and examples of how to just do a straight CSV import?  I just need to replace all data in a given table daily and can't find an examples of what the json might look like.  Any hep would be appreciated.

[03345]

Hi @HunorSZ , Many Thanks for sharing this info! 

[Jaycee_Lewis]

Hi, @HunorSZ 👋 Thank you very much for sharing! — Jaycee