---------------------------------------------------

Zendesk level:  Intermediate 
Knowledge:  JSON 
Time Required:  10 minutes

----------------------------------------------------

If you are a HubSpot user, you have probably tried the free integration found in the Zendesk Marketplace. While the integration will probably suit the needs of most users who just want the ticket added to their HubSpot account, there may be instances where you need more control over what data Zendesk sends to HubSpot. For example, you may want to populate custom properties/fields in HubSpot with Zendesk data.

About This Article

This article will show you how to use a Zendesk trigger that sends JSON to HubSpot to populate just about any data. My example will focus on HubSpot contacts, but it can be adapted for other HubSpot objects if needed.

What You Will Learn 

By following this article you will learn how to

• Obtain a HubSpot API key
• Create a notification target to call HubSpot
• Create a trigger to send JSON to update the relevant HubSpot fields
• Check and troubleshoot errors
• Bonus: working the HubSpot datepicker

 

While the process isn’t that difficult, it can be a daunting task if you are not familiar with any of the above techniques. But don’t worry, I’ll try to explain so anyone can follow. 

 

I will make the assumption that you are an administrator and have full access to Zendesk & HubSpot and you have the relevant Zendesk and HubSpot subscription level to access the features.

Step 1 - HubSpot API Key

You are going to need to obtain your HubSpot API key. You’ll find this in HubSpot by:

 

1. Clicking your account profile in the top right corner
2. Clicking ‘Profile & Preferences’ under your user name
3. On the left hand side of the screen, under Integrations you should see API key

• Note if you don’t see this, you will need to talk to your HubSpot administrator
• Under API key, you will be able to copy the API key that is unique to your HubSpot instance

• Couple of things to note here. 

1. The API key should never be shared, the key allows you to access/update HubSpot without a password. So if you share it, you are essentially giving people access to your HubSpot instance. You really don’t want to do that. 
2. Secondly, if for some reason you change your API key (as is good practice to update it on a regular basis) you’ll need to update the Zendesk notify target we’ll create in the next step

 

Step 1 Checkpoint

At this stage you should have obtained the HubSpot API key and have it safe for the next step.

 

Step 2 - Creating The HubSpot Target In Zendesk

In this step we will configure Zendesk so it notifies HubSpot in our trigger. To do this we are going to create a HTTP Target. The HTTP target is just a HubSpot URL that is waiting to be passed some data. In this case we are going to use the ‘createOrUpdate’ endpoint on a Contact. 

POST /contacts/v1/contact/createOrUpdate/email/:contact_email

 

We’ll be passing the ticket requester's email address and as the naming of the endpoint suggests, if the email address doesn’t exist it will create the HubSpot contact record. Whereas, if it does exist, it will update the HubSpot contact record. 

 

More information on the HubSpot endpoint can be found here: https://legacydocs.hubspot.com/docs/methods/contacts/create_or_update  its also a good starting point once you have finished this tutorial if you want to update other objects in HubSpot as the endpoint maybe different.

 

To create the HTTP target, follow these steps.

1. In Zendesk, click the cog to enter Zendesk Admin
2. Under ‘Settings’ click ‘Extensions’
3. Click ‘Add Target’ and select ‘HTTP Target’

 

You should be on the following screen but with blank data.

Now we need to fill out the HTTP Target with the following details

 

In the title box, give it a friendly name so you know what it is and can find it again easily later. 

 

URL: 

 

• https://api.hubapi.com/contacts/v1/contact/createOrUpdate/email/{{ticket.requester.email}}/?hapikey=the_hubspot_api_key_you_copied_earlier

 

Note in the URL we use {{ticket.requester.email}} which is a Zendesk helper function to get the email address of the request on the current ticket. At the end of the URL you need to copy the HubSpot API key that you obtained from the previous step. 

 

It will be a lot easier if you copy and paste the example above and replace the ‘the_hubspot_api_key_you_copied_earlier’ text with your API key. Once added, the URL will look something like

 

• https://api.hubapi.com/contacts/v1/contact/createOrUpdate/email/{{ticket.requester.email}}/?hapikey=xxxx-yyyy-aaaa-bbbb-cccc-dddd

 

Set the Method to Post and the Content Type to JSON

 

Important. Save the HTTP target by changing the dropdown from ‘Test target’ to ‘Create target’

 

Step 2 Checkpoint

We are almost there. So far you have obtained the HubSpot API key and created a HTTP Target which when called will pass the email address from the current ticket to your HubSpot instance which is identified with the API key.  The next step is to create the JSON with the fields you want to add/update in HubSpot.

 

Step 3 - Sending JSON to update the relevant HubSpot fields

As Triggers are a core part of every day Zendesk, I’ll assume you are familiar with creating them. I’ll leave you to decide how and when you want Zendesk to update HubSpot, but for testing you’ll probably want to do it on a ticket update rather than a new ticket.

 

Tip:  When testing I always build a trigger that responds to a tag ‘I_am_testing’ on the ticket to avoid being actioned unnecessary. 

 

In your Zendesk trigger, add whatever criteria that makes sense for the trigger to action, bearing in mind my tip above about testing.

 

Under Actions select ‘Notify target’ and from the dropdown list, select the HTTP Target you created in the previous step. Once done, you should be looking at a screen that resembles the image below.

Out of all the steps, this is probably the hardest step as incorrect fieldnames, extra or missing characters will cause the trigger to fail. 

 

Here is an example of the JSON you need to add to the JSON body section of the trigger. 

 

{

  "properties": [

        {

                   "property": "student_eligibility",

                   "value": "True"

  },




  {

                    "property": "firstname",

                    "value": "{{ticket.ticket_field_36001599999999}}"

   },

       

   {

                   "property": "student_license_application_date",

                   "value": "{{dc.applied_date}}"

   }

  ]

}

In my example above, 

 

Property is the name of the field in HubSpot, where Value is the value I am setting that field to. Typically this will be your Zendesk field.

 

For your specific example you’ll need both the internal names of your HubSpot fields and your Zendesk fields. The Zendesk field IDs for your custom fields can be obtained from the Zendesk admin area under Ticket Fields.

 

HubSpot Field Names

To find the Internal Name for your HubSpot fields (for the property parameter):

 

1. Login to HubSpot and select the gear icon
2. Select Properties from the left menu
3. Find the property/field name in the list and open it
4. Next to the Name, you’ll see </> click that button and the Internal Name will be shown. 

 

More information: https://support.sakari.io/hc/en-us/articles/360038865772-How-to-Find-HubSpot-Internal-Field-Names

 

Your next step is to add the JSON for each field you want to update until you have all your HubSpot fields populated. 

 

Tip:  Don’t try and do them all in one go.  You’ll likely have some errors and it's easier to build on the JSON rather than trying to troubleshoot 30 fields in one go. 

 

Step 3 Checkpoint

In this section you obtained any Zendesk custom field IDs and the HubSpot internal field names. From there you built your JSON request using property and value pair which will set the relevant HubSpot fields via the HTTP request you created in step 2.   

 

Step 4 Troubleshooting

It’s likely if you are following along, until the previous step every was going fine. Now you have tested your trigger I’ll bet the record hasn’t appeared in HubSpot. If so, help is at hand. In this section we’ll help you troubleshoot to see what might have happened.

 

• Usually the obvious error is the JSON is invalid.  Each property in JSON is separated by a comma, except the last property where no comma is necessary.  If you have added a new property it's likely you have not added a comma, or you have an extra comma. 
• Check the API log. You can check the request in Zendesk to see what has been sent to HubSpot. This is useful to see if the JSON is valid and if HubSpot returned an error.  In Zendesk, enter the Admin area and select API and then Target Failures.  If there is an entry here, it will show you why HubSpot rejected the request.   The page is made up of 2 sections.  At the top you can see the JSON complete with the values of the fields you are sending, while at the bottom you can see the error message that was returned.

Step 4 Checkpoint

In this section you troubleshooted errors by looking at the target failures in the API section. Here you were able to see the actual values that Zendesk is sending to HubSpot along with the error message returned.   

 

Step 5 Bonus Fun With The HubSpot Datepicker

I’ll add this as a bonus section as when I was updating my HubSpot contacts we used a datepicker. It turned out that the HubSpot datepicker is expecting a very specific format known as an epoch date rather than in a DD/MM/YY format.  

 

Example: 1427997766000 translates to April 2nd, 2015, 2:02:46 PM EDT (Eastern Daylight Saving Time) or 02 Apr 2015 18:02:46 UTC.

 

More information 

https://legacydocs.hubspot.com/docs/faq/how-should-timestamps-be-formatted-for-hubspots-apis

 

In my example, I wanted to send the ticket created date to HubSpot. Any value other than midnight on the date you are passing will fail, so a little manipulation was required.  I converted the date into epoch format and format it to milliseconds using Liquid Markup in a Dynamic Content item

 

In Zendesk, navigate to Dynamic Content via the Admin area and create a new item.  In the example below I use the {{ticket.created_at_with_timestamp}} placeholder and format it to dd/mm//yy then convert it to milliseconds. 

 

{% assign create_dd = {{ticket.created_at_with_timestamp | date: "%d" }}  %}{% assign create_mm = {{ticket.created_at_with_timestamp | date: "%m" }}  %}{% assign create_yy = {{ticket.created_at_with_timestamp | date: "%Y" }}  %}{% capture applieddate %}{{create_dd}}/{{create_mm}}/{{create_yy}}{% endcapture %}{{applieddate | date: "%s"}}000

 

Create, name and save the DC item using the code above as a starting point for your date field. After creating the DC item,  take note of the name. (something like {{dc.I_created_this}})  and then use the DC item in the JSON

 

       "property": "student_license_application_date",

       "value": "{{dc.I_created_this}}"

 

Tip: Formatting with Liquid Markup is important and any additional spaces may make it into the JSON making the JSON invalid. Remember you can check the API log if it fails so you can see what value is actually being passed to HubSpot. 

 

Step 5 Checkpoint

In this optional section you created a Dynamic Content item to extract the day, month and year components of a date. Then you converted the date to an epoch date and to milliseconds. 

 

Summary

Hopefully you found this article useful in helping you send extra fields to HubSpot and you were able to follow along.  Whenever I use a plug-in from the Zendesk marketplace that doesn’t quite do as much as I’m hoping, I always look to see if they have an API that accepts JSON. If so, often with a little digging around the API documentation, a notify target and some carefully created JSON,  you can get the results you need.