Hyros API + n8n: The "No-Tax" Attribution Blueprint (JSON Included) | Code Boost
Description: If you are scaling your ad spend, you have likely hit the "Zapier Wall." You start with a simple integration to track your leads. But as soon as you hit 10,000 leads a month, you a...

Article

# Hyros API + n8n: The "No-Tax" Attribution Blueprint (JSON Included)

By Matt · Jan 21, 2026

If you are scaling your ad spend, you have likely hit the "Zapier Wall."

You start with a simple integration to track your leads. But as soon as you hit 10,000 leads a month, you are suddenly paying $500+ per month just to move data from point A to point B.

Even worse? Standard integrations often strip the data you need most.

Most generic "Hyros connectors" (Zapier, Make, native integrations) fail to pass the user's original IP address or browser cookies (`fbp`, `fbc`). Without these, Hyros’s "AI Print" cannot function at full capacity, and your attribution accuracy drops.

In this guide, I’m going to show you how to build a Server-Side Attribution Pipeline using n8n and the Hyros API. It’s cheaper, it’s faster, and it passes 100% of the data Hyros needs to track your sales perfectly.

## Prerequisites (The Setup)

To follow this guide, you will need three things:

1. An Active Hyros Account: You will need your API Key (Found in Settings -> API).

2. An n8n Instance: This can be the n8n Cloud version or a self-hosted version on your own server (recommended for maximum savings).

3. A Data Source: This works for any source that can send a Webhook (Stripe, WooCommerce, GTM Server Container, Typeform, etc.).

## Step 1: Preparing the Data (The "Cleaner" Node)

The biggest mistake developers make with the Hyros API is sending "raw" data.

If you send a phone number like `(555) 123-4567` or `555-123-4567`, the API might accept it, but the matching engine often fails to link it to the customer's history. To fix this, we need to normalize the data before it leaves n8n.

Place a Code Node right before your API request node and paste this JavaScript. It strips non-numeric characters and ensures you always have a valid IP address.

### The "Phone & IP Cleaner" Script

JavaScript

    // n8n Code Node: "Clean Phone & Params"
    // Loop over input items
    for (const item of items) {
      const rawPhone = item.json.phone || "";

      // 1. Remove all non-numeric characters (dashes, spaces, parens)
      let cleanPhone = rawPhone.toString().replace(/\D/g, '');

      // 2. Normalize Country Code
      // If the number is 10 digits (USA standard), add '1' to the front.
      if (cleanPhone.length === 10) {
        cleanPhone = '1' + cleanPhone;
      }

      // 3. Fallback for IP Address
      // If no IP is found, use a placeholder to prevent the API from crashing.
      const userIp = item.json.ip_address || item.json.ip || "0.0.0.0";

      // Output the cleaned data back to the workflow
      item.json.clean_phone = cleanPhone;
      item.json.final_ip = userIp;
    }

    return items;

## Step 2: The Universal Lead Payload (The Core Value)

The standard Hyros documentation lists fields alphabetically. It doesn't tell you which ones actually matter for attribution.

If you just send an email, you are creating a contact, but you aren't creating tracking. To enable Hyros's "AI Print," you must pass "Identity Fields" that allow the system to fingerprint the user.

In your n8n HTTP Request node, select JSON as the body format and use this payload. I call this the "Universal Lead Object":

JSON

    {
      "email": "{{ $json.email }}",
      "phone": "{{ $json.clean_phone }}",
      "first_name": "{{ $json.first_name }}",
      "last_name": "{{ $json.last_name }}",
      "ip": "{{ $json.final_ip }}",
      "tag": "n8n-api-import",
      "fields": [
        {
          "field": "fbp",
          "value": "{{ $json.fbp }}"
        },
        {
          "field": "fbc",
          "value": "{{ $json.fbc }}"
        },
        {
          "field": "user_agent",
          "value": "{{ $json.user_agent }}"
        }
      ]
    }

### Why these specific fields?

- `ip`: This is critical. Hyros uses the IP address to link the click to the conversion. If you rely on a 3rd party tool, they often send their server IP instead of the user's IP, breaking your tracking.

- `fbp` / `fbc`: These are Facebook's browser cookies. Capturing these on your landing page and passing them to Hyros drastically improves the match quality when Hyros pushes data back to Facebook CAPI.

## Step 3: Configuring the Request (The Implementation)

Now, let's configure the HTTP Request node in n8n to send this data to Hyros.

- Method: `POST`

- URL: `https://api.hyros.com/v1/api/v1/users`

- Authentication: None (We will use a Header)

Headers:

- Name: `API-Key`

- Value: `{{ $env.HYROS_API_KEY }}` (Note: Always store your API keys in n8n credentials or environment variables, never hardcode them!)

### The "Upsert" Advantage

A common question I see is: "Do I need to check if the user exists first?"

No. The Hyros `POST /users` endpoint is an Upsert (Update/Insert) function.

- If the email does not exist, Hyros creates a new lead.

- If the email does exist, Hyros updates the lead and adds the new tag.

This saves you an entire "Search" operation step in your workflow, cutting your API usage in half.

## Troubleshooting & "Deep Cuts"

If you are running into issues, check these three common pitfalls:

### 1. Rate Limiting (The 5,000 Lead Batch)

Hyros has API rate limits. If you are migrating 5,000 leads at once, n8n is fast enough to crash your request limit.

- Fix: Use the Split in Batches node in n8n. Set it to process 10 items at a time, and add a Wait node of 1 second between batches.

### 2. The "Missing Attribution" Mystery

If leads are showing up in Hyros but not attributing to ads, check your Source Data.

- Are you capturing the IP address on the frontend?

- If you are using a backend webhook (like Stripe), Stripe usually does not send the customer's IP. You may need to capture the IP during checkout and store it in Stripe metadata to retrieve it later.

### 3. Error 400 (Bad Request)

This is almost always a JSON formatting error.

- Fix: Check your phone numbers. If you accidentally send a `null` value or a string with letters to the phone field, the entire request will fail. Use the "Cleaner Node" script above to prevent this.

## Conclusion & The "Lazy" Button

You now have a robust, server-side attribution pipeline that costs fractions of a cent to run. You have full control over your data, better matching scores, and you've eliminated the "Zapier Tax."

Don't want to build this from scratch?

I've exported this exact workflow into a JSON file. It includes the Error Handling, the Cleaner Script, and the API configuration pre-set.