Data Layer

With the Data Layer, your server learns during a visit which company is behind it, for example Bergquell Mineralbrunnen GmbH. At the end you'll have:

• a Data Layer key
• a request that returns the ID and name of the company behind a visit's IP address, or null if Webmetic knows none

For Matomo, the ready-made Matomo plugin is available and uses the same key.

Before you startCopy Anchor Link

• Time: The key and the first request take a few minutes to set up.
• Account: You need a Webmetic account on the Enterprise plan.
• Access: Your server must reach https://hub.webmetic.de over the internet.
• Rights: An admin generates the key. Other users don't see the API keys window and ask an admin for the key. If a partner manages your account, the partner decides whether API appears in the menu.
• Plan: Server-side identification is part of the Enterprise plan. The lookup currently costs no credits.

Create the keyCopy Anchor Link

You need the key from the Data Layer card, because the key from the Visitor Intelligence card doesn't work here.

The other way round, the Data Layer key doesn't work on the API endpoints.

1. Open Menu > Integrations > API. The API keys window opens.
2. If the Data Layer card shows the text No key generated yet., click Generate key. Webmetic shows the new key.
3. In the Data Layer card, click the Copy icon. Webmetic copies the full key, even when it's masked.

Your account has exactly one Data Layer key, which applies to all your websites and doesn't expire.

Don't click Regenerate if you already use the key. After the second click, the old key stops working at once, in the Matomo plugin too, and this can't be undone.

Send the request from your serverCopy Anchor Link

For every visit whose company you want to know, send a request to GET https://hub.webmetic.de/dl with two headers:

• Authorization: your Data Layer key, unchanged and without Bearer in front.
• X-Data-Source: the public IP address of the visit.

curl "https://hub.webmetic.de/dl" \
  -H "Authorization: wmtc_YOUR_API_KEY" \
  -H "X-Data-Source: 203.0.113.42"

The JavaScript and Python samples give up after two seconds, a value you choose yourself, so your page never waits long for the answer.

You don't need Enterprise or an account to try it. With the public demo key wmtc_demo and X-Data-Source: 203.0.113.42, /dl answers with the invented example company Bergquell Mineralbrunnen GmbH, and with null for any other address.

If X-Data-Source is missing, Webmetic looks up the address the request comes from, which is your server's address and not the visit's.

Webmetic compares the address character by character, so for a wrongly copied address /dl answers with null rather than an error. Watch for these points:

• If a proxy, a content delivery network (CDN), or a load balancer sits in front of your server, your server sees its address. Take the visit's address from the header it passes on, for example X-Forwarded-For.
• If that header holds several addresses, send only the visit's address.
• Send IPv4 addresses without the ::ffff: prefix that some servers put in front.
• Send IPv6 addresses in the usual short form in lower case, as most servers return them.

Each request accepts exactly one address, so send one request per visit.

Read the responseCopy Anchor Link

When Webmetic knows a company for the address, /dl answers with status 200 and a JSON object with exactly two fields:

{
  "cid": "41ea486a9c95",
  "cn": "Bergquell Mineralbrunnen GmbH"
}

• cid: the company's ID in Webmetic. If the company visited your website, you find it in the API under the same company_id.
• cn: the company's name. It's null when Webmetic knows no name for the ID.

When Webmetic knows no company, the body is null, also with status 200, so check the body in your code rather than the status.

/dl doesn't return the industry, size, or domain.

/dl names every company Webmetic knows for the address, even if the company has never visited your website.

A lookup creates no visit and no company in the dashboard. The domain blacklist doesn't apply to the Data Layer.

Pass the response to the tag managerCopy Anchor Link

If your tags in Google Tag Manager need the company, your server writes the response into window.dataLayer when it serves the page. Despite the name, Webmetic itself writes nothing there.

The key stays on your server, because only the response goes into the page.

Webmetic defines no events or variables, so you choose the names yourself, for example:

<script>
  // Rendered into the page by your server. Event and field names are your choice.
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'company_identified',
    company_id: '41ea486a9c95',
    company_name: 'Bergquell Mineralbrunnen GmbH',
  });
</script>

ReferenceCopy Anchor Link

/dl isn't part of the generated API reference, so everything about the endpoint is on this page.

RequestCopy Anchor Link

ResponseCopy Anchor Link

ErrorsCopy Anchor Link

Data Layer errors have a shorter body than the API endpoints: detail is a string, not an object with error and message, for example {"detail": "DATA_LAYER_KEY_MISSING"}. So on /dl, check detail as a string.

The errors of the API are listed under Errors.

Data protectionCopy Anchor Link

Clarify with your privacy advisor on which legal basis you send your visits' IP addresses to Webmetic.

Next stepsCopy Anchor Link