HubSpot Object XML

This XML format represents objects in HubSpot, along with their properties and the values of those properties.

Tasks

Minimal XML Sample

<?xml version="1.0" encoding="utf-8"?>
<HubSpotObjects ObjectType="contacts">
  <HubSpotObject>
    <Id>151</Id>
    <Properties>
      <Property Name="email" Value="[email protected]" />
      <Property Name="firstname" Value="John" />
      <Property Name="lastname" Value="Smith" />
    </Properties>
  </HubSpotObject>
</HubSpotObjects>

In each of the following sections most of the XML has been omitted to make the samples easier to read. The whole structure of the HubSpotObjects schema is used below as a reference of where fields should be in the object model.

HubSpotObjects

The HubSpotObjects element represents a collection of objects to be uploaded to HubSpot. This element appears at the root of the XML document.

XML Field	Example	Field Type	Input	Description
@ObjectType	contacts	string	Required	The type of object contained within the collection. You can either provide the object name, or it's ID (e.g. 0-1)
HubSpotObject	See below	HubSpotObject	Optional	A list of 0 or more `HubSpotObject` elements.

<?xml version="1.0" encoding="utf-8"?>
<HubSpotObjects ObjectType="contacts">
  <HubSpotObject>
    <!-- See below -->
  </HubSpotObject>
</HubSpotObjects>

HubSpotObject

The HubSpotObject element represents an individual object to be uploaded to HubSpot. This element appears as a child of the HubSpotObjects collection.

XML Field	Example	Field Type	Input	Description
Id	151	integer	Optional	You can specify the ID of an existing record to update here
Key	email	string	Optional	Used to specify a property to use to look up the ID of an existing record
Properties	See below	Collection	Required	A collection of `Property` elements, indicating the values to set each property to.
Associations	See below	Collection	Optional	A collection of `Association` elements, indicating other objects of a particular type to associate with this object. Multiple `Associations` collections can be specified if you want to associate objects of different types.

<?xml version="1.0" encoding="utf-8"?>
<HubSpotObjects ObjectType="contacts">
  <HubSpotObject>
    <Id>151</Id>
    <Key>email</Key>
    <Properties>
      <!-- See below -->
    </Properties>
    <Associations ObjectType="companies">
      <!-- See below -->
    </Associations>
  </HubSpotObject>
</HubSpotObjects>

Property

The Property element represents an individual property and the value you want to set it to. This element appears within the Properties collection of the HubSpotObject element.

XML Field	Example	Field Type	Input	Description
@Name	email	string	Required	The internal name of the property. You can't use the label that's shown in the front end of HubSpot.
@Value	[email protected]	string	Optional	The value to set the property to. More info on the different types of property can be found below. If not specified, the existing value of the property will be cleared.
LookupProperty/@Name	email	string	Optional	`LookupProperty` elements can only be used when setting the owner of a record. The `name` attribute represents which property to use to lookup the owner, valid values are `email`, `firstName`, `lastName`. `id` and `userId`.
LookupProperty/@Value	[email protected]	string	Optional	`LookupProperty` elements can only be used when setting the owner of a record. The `value` attribute represents the value to use when searching for an owner.

How to Set the Value Attribute for Different Property Types

We would recommend populating the Value attribute as follows for different property types:

Boolean Properties - For boolean fields such as check boxes, use either true or false
Date & Date/Time Properties - For fields that use a date picker, we recommend providing an ISO 8601 formatted date/time, e.g. 2024-01-31T09:59:59Z
Enumeration - For fields that allow you to pick from a pre-defined list of options, you will need to provide one of the existing options. If the field allows you to choose multiple options, they should be provided as semi-colon separated list e.g. value1;value2;value3
Numeric Properties - For numeric fields, we recommend providing the number using decimal notation, e.g. 1234.5678
Owner Properties - You can either provide the ID of the owner in the Value attribute, or look up the owner using one or more LookupProperty child elements. If more than one LookupProperty is specified, only owners where all properties match will be considered.
Other Properties - All other properties have values that are simply provided as a string.

<?xml version="1.0" encoding="utf-8"?>
<HubSpotObjects ObjectType="contacts">
  <HubSpotObject>
    <Properties>
      <Property Name="email" Value="[email protected]" />
      <Property Name="hubspot_owner_id">
        <LookupProperty Name="email" Value="[email protected]" />
      </Property>
    </Properties>
  </HubSpotObject>
</HubSpotObjects>

Association

The Association element represents an individual object to be associated with the parent object. This element appears within the Associations collection of the HubSpotObject element.

XML Field	Example	Field Type	Input	Description
HubSpotObject	See above	HubSpotObject	Required	The object to associate.

The HubSpotObject child element of the Association element supports all of the functionality as the main HubSpotObject elements. So you can either provide the ID of the object, or use a key to look it up. You can also specify further associations for the associated object, in a recursive nature.
If you want to associate an existing object without updating it, you can do so by not specifying a Properties collection (or in the case where you are performing a lookup via a key, specifying only the key property).
If you want to create or update the object being associated, simply provide all of the properties you want to set.

<?xml version="1.0" encoding="utf-8"?>
<HubSpotObjects ObjectType="contacts">
  <HubSpotObject>
    <Associations ObjectType="companies">
      <Association>
        <HubSpotObject>
          <!-- See above -->
        </HubSpotObject>
      </Association>
    </Associations>
  </HubSpotObject>
</HubSpotObjects>

Complete XML Sample

This sample shows all data that can be provided via our HubSpot Object XML format.

<?xml version="1.0" encoding="utf-8"?>
<HubSpotObjects ObjectType="deal">
  <HubSpotObject>
    <Key>dealname</Key>
    <Properties>
      <Property Name="amount" Value="2000" />
      <Property Name="closedate" Value="2024-03-15T00:00:00Z" />
      <Property Name="dealname" Value="T-Shirts" />
      <Property Name="dealstage" Value="closedwon" />
      <Property Name="dealtype" Value="newbusiness" />
      <Property Name="description" Value="A large order of t-shirts" />
      <Property Name="pipeline" Value="default" />
      <!-- Example of setting the owner of the deal to the user whose email address is '[email protected]' -->
      <Property Name="hubspot_owner_id">
        <LookupProperty Name="email" Value="[email protected]" />
      </Property>
    </Properties>
    <!-- Example of associating an existing contact with the deal, based on email address. The contact won't be updated -->
    <Associations ObjectType="contact">
      <Association>
        <HubSpotObject>
          <Key>email</Key>
          <Properties>
            <Property Name="email" Value="[email protected]" />
          </Properties>
        </HubSpotObject>
      </Association>
    </Associations>
    <!-- Example of associating an existing company with the deal, based on ID. The company won't be updated -->
    <Associations ObjectType="companies">
      <Association>
        <HubSpotObject>
          <Id>8502592015</Id>
        </HubSpotObject>
      </Association>
    </Associations>
    <!-- Example of creating 2 new line items and associating them with the deal -->
    <Associations ObjectType="line items">
      <Association>
        <HubSpotObject>
          <Properties>
            <Property Name="description" Value="Red T-Shirt" />
            <Property Name="discount" />
            <Property Name="name" Value="Red T-Shirt" />
            <Property Name="price" Value="10" />
            <Property Name="quantity" Value="100" />
            <Property Name="tax" Value="0" />
          </Properties>
        </HubSpotObject>
      </Association>
      <Association>
        <HubSpotObject>
          <Properties>
            <Property Name="description" Value="Blue T-Shirt" />
            <Property Name="discount" />
            <Property Name="name" Value="Blue T-Shirt" />
            <Property Name="price" Value="10" />
            <Property Name="quantity" Value="100" />
            <Property Name="tax" Value="0" />
          </Properties>
        </HubSpotObject>
      </Association>
    </Associations>
  </HubSpotObject>
</HubSpotObjects>