> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hyros

> PII-based ad attribution for Hyros — survives iOS ITP, adblockers, and cross-device flows

# Hyros

[Hyros](https://hyros.com) is fundamentally different from every other tracker in this section. Instead of relying on click\_ids and cookies, Hyros identifies customers by **email and phone** — deterministic identity matching that survives iOS Smart Tracking Protection, adblockers, and cross-device flows.

<Info>
  **No cookies. No click\_ids. No URL parameters.** TagadaPay sends each paid order's customer details (email, phone, line items, amount) to Hyros's `/orders` API. Hyros stitches those PII signals back to the original ad click on its own infrastructure.
</Info>

***

## When to Use Hyros

| Situation                                     | Hyros vs Postback Tracker                                                       |
| --------------------------------------------- | ------------------------------------------------------------------------------- |
| High-LTV product (>\$100 AOV)                 | **Hyros** — better cross-device matching pays for itself                        |
| Heavy mobile / iOS audience                   | **Hyros** — Safari ITP destroys cookie-based trackers                           |
| TikTok / YouTube ad spend                     | **Hyros** — those platforms strip click\_ids more aggressively than Meta/Google |
| Long sales cycle (days/weeks)                 | **Hyros** — click\_id cookies expire; PII doesn't                               |
| Pure direct-response affiliate funnel         | **Postback tracker** (cheaper, simpler)                                         |
| You don't capture phone or email pre-purchase | **Postback tracker** (Hyros needs at least one to attribute)                    |

Hyros is **stackable** with everything else. You can run Hyros alongside ClickFlare, Voluum, Meta Pixel, etc. — they identify users via different signals and don't conflict.

***

## Setup

<Steps>
  <Step title="Generate a Hyros API key">
    In Hyros: **Settings → Integrations → API**. Click **Create New Key**, give it a label like "TagadaPay", and copy the key.
  </Step>

  <Step title="Enable Hyros in TagadaPay">
    Dashboard → **Settings → Integrations → Hyros → Connect**. Paste the API key (it will be encrypted at rest in TagadaPay's vault) and save.

    Optionally check **Push only the first paid order per customer** if you want to track new-customer acquisition cost only and ignore repeat orders.
  </Step>

  <Step title="Verify in Hyros">
    Place a test order. The conversion should appear in Hyros's **Sales → Recent Sales** view within \~60s. Hyros will show the attribution chain — which ad, ad set, and campaign drove the click that led to the order.

    If the customer is new to Hyros, attribution may take a few minutes while Hyros backfills the click history.
  </Step>
</Steps>

***

## What TagadaPay Sends

For every paid order, TagadaPay POSTs to `https://api.hyros.com/v1/orders` with this payload:

```json theme={null}
{
  "email": "customer@example.com",
  "phone": "+15551234567",
  "firstName": "Jane",
  "lastName": "Doe",
  "country": "US",
  "ip": "203.0.113.42",
  "orderId": "ord_abc123",
  "amount": 49.99,
  "currency": "USD",
  "paidAt": "2026-05-02T18:45:21.000Z",
  "items": [
    { "name": "Premium Plan", "price": 49.99, "quantity": 1 }
  ]
}
```

**Required fields** (Hyros rejects orders missing these): at least one of `email` or `phone`. TagadaPay only fires the postback if at least one is present on the order.

**PII handling:** TagadaPay forwards email/phone in clear-text over HTTPS to Hyros's API (this is how Hyros works — they hash on their side). The keys are stored encrypted at rest in your TagadaPay vault and only decrypted at the moment of firing.

***

## How Hyros Attributes the Click

This is the part that's worth understanding because it's unlike anything else in this section:

1. Visitor sees an ad. Hyros's tracking pixel on the lander captures their **fingerprint** (browser, IP, screen, etc.) and any contact info entered in pre-purchase forms (email opt-ins, phone fields, etc.).
2. Hyros stores the fingerprint + contact info linked to the ad source.
3. Visitor goes through your funnel — possibly switching devices, clearing cookies, taking days to convert.
4. Customer pays on TagadaPay's checkout. TagadaPay POSTs the order to Hyros with `email` + `phone`.
5. Hyros matches the email/phone back to the original click via deterministic identity matching, then credits the ad source.

**You don't need Hyros's lander pixel for TagadaPay-hosted funnels** — TagadaPay captures and pushes everything Hyros needs server-side. But if you have lander pages outside TagadaPay (WordPress blogs, lead-gen forms, etc.), install Hyros's pixel there for the deepest attribution.

***

## Settings

* **Push only the first paid order per customer** — if checked, repeat orders from the same customer are skipped. Useful when you only care about new-customer CAC. Detection is based on Hyros's customer-side dedup (email match), so it's correct even if the customer uses different shipping addresses across orders.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Order didn't arrive in Hyros">
    1. Check the order's customer record — both `email` AND `phone` must be present (technically Hyros accepts either, but having both maximises match rate).
    2. Verify the API key in TagadaPay still works — generate a new one in Hyros if in doubt.
    3. Check TagadaPay's **External Request Logs** (CRM → Logs → External Requests) for the Hyros call. The response will show `200 OK` on success or an error message describing what Hyros rejected.
  </Accordion>

  <Accordion title="Order arrived but is unattributed">
    Hyros couldn't find a click history for this customer. Possible causes:

    1. The customer's first interaction was outside Hyros's tracking (organic search, direct visit, ad campaign without Hyros pixel installed).
    2. The customer's email/phone in TagadaPay differs from what Hyros has from the lander click. Hyros uses fuzzy matching but capitalisation-only or domain-only mismatches can throw it off.
    3. Hyros's attribution window has passed (default 30 days, configurable per workspace).
  </Accordion>

  <Accordion title="Duplicate orders in Hyros">
    Hyros is supposed to dedup by `orderId` — TagadaPay always sends `ord_…` IDs which are globally unique. If you see duplicates, check whether you have **multiple Hyros integrations** in TagadaPay (e.g. two different stores with the same Hyros API key). Either consolidate to one integration or partition orders by store inside Hyros.
  </Accordion>
</AccordionGroup>

***

## References

* [Hyros API documentation](https://hyros.docs.apiary.io/)
* [Tracking & Attribution overview](/developer-tools/tracking/overview)