Knowledge base

Using Components: Rest API Destination


In this short tutorial, we'll show how to create or update contacts in Hubspot as an example of writing data to any REST API destination.

Writing data to REST APIs essentially works in the same manner as reading data from REST APIs - using simple HTTP requests. HTTP requests are comprised of 4 parts:

  • Method - the most common are GET (used to read data) and POST (to write data).
  • URL - specifies the resource to read/write
  • Headers - specify additional information to the server (e.g. authentication keys, request body format)
  • Body - usually contains the data to send to the server in JSON or query string format)

In this tutorial, we'll use the Curl function to make HTTP requests to create or update contacts in Hubspot.

According to Hubspot docs, for each contact, we have to generate a URL containing the contact's email - used as the contact identifier - and a JSON string in the following form to submit in the request body:

{
  "properties": [
    {
      "property": "property name",
      "value": "property value"
    },
    ...
    ]
}

In our package, we first read data from a contacts table in a source database.

In the second component, we generate the URL and the JSON string.

Use the SPRINTF function to create the URL (see here for more information on SPRINTF.) The URL contains the email address and the Hubspot API key (which we store in a package variable - $hapikey).

SPRINTF('https://api.hubapi.com/contacts/v1/contact/createOrUpdate/email/%s/?hapikey=%s', URLEncode(email), '$hapikey')

The JSON string is generated using Xplenty's functions to build nested arrays and objects, TOBAG and TOMAP, correspondingly, and ToJson that returns a JSON string. The JSON structure specified by Hubspot is relatively complex (an array of objects within an object) where most APIS usually work well with a simple JSON object.

ToJson(TOMAP('properties',TOBAG(TOMAP('property','firstname','value',firstname),TOMAP('property','lastname','value',lastname),TOMAP('property','website','value',website),TOMAP('property','company','value',company),TOMAP('property','phone','value',phone),TOMAP('property','address','value',address),TOMAP('property','city','value',city),TOMAP('property','state','value',state),TOMAP('property','zip','value',zip))))

In the third component, the request is made, per record coming in from the source table, and a response is returned.


The response contains a status code, headers and a body. The status code determines whether the request was successful or not (200 is returned on success. Read more here).

(int)Curl(url,'POST','',body)#'status'

Finally, the contact email and the response code are stored into a database table. This helps us monitor the process.

In the same manner, you can write data to any REST API endpoint - simply go through the API docs, build the URL and request body using the source data and check the response to make sure the returned response indicates success.