Company.info template for server-side Google Tag Manager

A guide for using the Company.info API in server-side GTM

Wouldn't it be great if you know in real-time which companies are visiting your website? By linking the Company.info API to server-side Google Tag Manager (GTM) this is easier than ever. Company.info is a leading provider of business data, specializing in Dutch registered companies. The Company.info API gives subscribers access to among others: real-time financial (health) information, company shareholder data, real estate data and vehicle registration information. The API data can also be enriched with your own CRM data, so that it can return information about customer status and segments.

I've created a template that can be used to call their API and make the company details available in the browser and in server-side Google Tag Manager. This provides many options to personalize the website experience in real-time, enrich segments in a DMP/CDP, trigger campaigns, enrich web analytics data, or enrich data exchanged with marketing partners like Google Ads for targeting purposes.

The data from the API is presented as event data in server-side Google Tag Manager, and as an object in the browser - see the two images below.

  • In Server-Side Google Tag Manager the API data is made available as event data, which can be converted into variables (the company key and name are masked for privacy reasons):
  • Example of Company Info data in server-side Google Tag Manager
  • In the browser the data is returned as an object, which can be used in other scripts:
  • Example of Company Info data returned to the browser

This guide describes the prerequisites, recommendations and implementation instructions for this template.


Prerequisites

  • An active Company.info subscription with access to the API.
  • Have API details, which can be requested at your Company.info contact person. The API details consist out of a "Company.info Company Card" and a "Company.info Contract Card" ID, which are unique to your instance.
  • Have working knowledge of server-side Google Tag Manager and asynchronous JavaScript. This guide assumes you have a base level of working knowledge, including an understanding of GTM clients, using GTM preview mode, and calling clients asynchronously from the browser.

Implementation recommendations

  • Whitelist all base domains (eTLD+1s or registrable domains) in the dedicated field in the template. Only whitelisted domains can make requests to the client when they are specified. This way third parties can't abuse the API by calling it from third party websites.
  • Throttle API calls, e.g., to once per 30 minutes per website visitor. This will limit the number of calls made to the server-side Google Tag Manager container and Company.info API. Even though the IP address of the visitor may change during a website visit through switching the VPN on or off, or switching from WIFI to mobile internet, this will probably happen infrequently for visitors from company networks.
  • Throttle the API calls through a browser cookie once an API response is received, also when the response is empty (no company network recognized). To limit API calls, it is recommended to only call the API when the cookie does not exist. The most straightforward implementation method is to set and read the cookie with browser side JavaScript.
  • Company.info can whitelist IP addresses that are allowed to call the API. If your server-side Google Tag Manager container is deployed to a static IP, or a limited number of IP addresses, this is highly recommended additional security layer.

Steps to import the template

  1. Download the server-side Google Tag Manager template from the GitHub repository.
  2. Import the template in your server-side Google Tag Manager container. In server-side GTM, go to "Templates" and click the "New" button in the "Client Templates" section to add a new template. Open the menu (three dots in the top right corner) and click "Import". Select the template downloaded in step 1 and click "Open". Validate that the template is imported and click "Save" in the template editor.
    The template is now imported in GTM and the client is ready for configuration.

Steps to configure the client

After importing the Company.info you can configure it. The instructions below describe the configuration steps. An example of a configured template can be found in the image below.

  • Example configuration of the Company.info client

Configuration steps:

  1. Go to "Clients", click "new" to add a new client, and select the "Company.info client" as client type.
  2. Keep 0 as the priority, unless your specific server-side GTM implementation requires a different value.
  3. Set a desired Request Path, which is the path used in the browser to call this template. The value must start with a forward slash. By default, the Request Path will be set to /c-info, but you can change it to any value of your preference.
  4. Set the Allowed Top Level Domains (a.k.a. base domain, eTLD+1, or registrable domain). Each Top Level Domain should be presented on a new line.
    Important: the values should NOT start with a dot.
    The Allowed Top Level Domains are the domains that are allowed to make requests to this template. If your website is hosted on www.example.com and your blog on blog.example.com, then you should set the Allowed Top Level Domains to: example.com. In that case requests from "example.com" are accepted, but requests from other domains like www.domain.com or www.michelbieze.com are not processed.
    The default value is *, which allows requests from all websites (not recommended).
  5. Set the Company.info Company Card with the value provided by Company.info.
  6. Set the Company.info Contract Card with the value provided by Company.info.
  7. Set the Fields to return to browser (case sensitive). You may not want to return all API fields to the browser, like the company name or company ID. This field allows you to whitelist the API fields that are to returned to the browser. Each field should be presented on a new line. The values are care sensitive, like the field name suggests.
    You can leave this field blank in case you would not like to return any fields to the browser. In that case an empty object {} is returned.
  8. Save the client.
    You can now follow the instructions below to test and use the client.

Call the client from the browser

Now the client is configured, it is time to call it from the browser. The following code snippet provides an example to call client:

          
/** 
  * Update https://gtm.your-domain.com/c-info 
  * to your GTM container URL and client path
  */

async function getCompanyInfoData() {
  try {
    const response = await fetch('https://gtm.your-domain.com/c-info', { 
      mode: 'cors', 
      credentials: 'include' 
    })
    const data = await response.json();
    return JSON.parse(data);
  } catch (error) {
    /* handle error */
    return;
  }
};

async function logCompanyData() {
  const companyData = await getCompanyInfoData();
  if (typeof companyData !== 'object') {
    /* add fallback, API call failed */
    console.log('Company.info API call failed')
    return;
  }
  console.log('Company.info data returned by API:', companyData);
}

logCompanyData();
         
      

Notes to the getCompanyInfoData function:

  • Replace "https://gtm.your-domain.com" with the URL of your tag manager instance, and "/c-info" with the path specified in the template in the fetch request URL.
  • The getCompanyInfoData function returns an empty object literal {} in case the API call was successful, but the IP address was not matched to a company network by the API.
  • In case the fetch requests fails, the getCompanyInfoData function returns the value undefined (in the return statement in the catch block). For this purpose, the typeof companyData !== 'object' validation is added in the logCompanyData function, so that undefined values can be handled in a different manner. In this scenario you may want to call the API again on the next page load.

Testing the client in GTM preview mode with a manual set IP address

The template can be tested in preview mode by adding a "test_ip" query parameter to the request URL, with its value set with the IP address you would like to emulate. This functionality only works in preview mode, to prevent any abuse or leaking of API data. To run the test, you can update the fetch request URL in the above code snippet. The "test_ip" parameter can be set in this format:

  • https://gtm.your-domain.com/c-info?test_ip=333.333.1.22

And there you have it. A simple to implement template for calling the Company.info API through server-side GTM.

In case you have questions or comments with regards to this article, feel free to reach out on LinkedIn

  • Was this article helpful?