Hyros api

1. Confirm your tier has API access

API access is not included in all tiers. The Starter tier typically does not include API access; Growth and Scale tiers do. If you can't find the API key generation page under Settings, your tier doesn't include it. Contact your Hyros account manager to confirm before building anything that depends on API access.

2. Generate your API key

In the Hyros admin panel, navigate to Settings → API → Generate Key. The key is a long alphanumeric string. Treat it like a password - store it in your secrets manager (1Password, Vercel env vars, AWS Secrets Manager), never commit it to source control.

# Store in your env
export HYROS_API_KEY="hys_live_xxxxxxxxxxxxxxxxxxxxxxxx"

3. Make your first authenticated request

Hyros uses API key authentication via the API-Key header (not Authorization: Bearer). The base URL is api.hyros.com/v1/. Test connectivity with a simple GET to the leads or sales endpoint.

curl -X GET \
  -H "API-Key: $HYROS_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.hyros.com/v1/leads?from=2026-05-01&to=2026-05-20"

4. Decide whether you're reading, writing, or both

The Hyros API supports both read (pull lead/sale/attribution data into your warehouse or dashboard) and write (push custom conversion events from your backend into Hyros). Most integrations are read-only - pulling Hyros's attributed data into a warehouse for custom reporting. Write integrations are rarer and used when you have backend events that aren't captured by the standard JS tag or webhook integrations.

5. Build a read integration: warehouse sync

The most common Hyros API use case: pulling attributed lead/sale data into BigQuery or Snowflake for blending with other marketing data sources. Schedule a job (cron, Airflow, dbt Cloud) to pull the previous day's data each morning, dedupe against existing records, and append to your warehouse table.

// Node example: pull yesterday's sales
const yesterday = new Date(Date.now() - 86400000).toISOString().split('T')[0];
const today = new Date().toISOString().split('T')[0];

const res = await fetch(
  `https://api.hyros.com/v1/sales?from=${yesterday}&to=${today}`,
  { headers: { 'API-Key': process.env.HYROS_API_KEY } }
);
const { data } = await res.json();

// Then insert into BigQuery, dedupe by sale ID
await bigquery.dataset('marketing').table('hyros_sales').insert(data);

6. Build a write integration: custom conversion event

If you have a conversion event that isn't captured by standard integrations - for example, a successful sales call logged in a bespoke internal tool, or a renewal event from a custom billing system - push it to Hyros via the POST /v1/sales or POST /v1/leads endpoint. Include the user's email so identity resolution can stitch the event into the existing journey.

await fetch('https://api.hyros.com/v1/sales', {
  method: 'POST',
  headers: {
    'API-Key': process.env.HYROS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'customer@example.com',
    sale_id: 'internal_sale_12345',
    amount: 1500,
    currency: 'USD',
    occurred_at: '2026-05-20T14:30:00Z',
    // Custom metadata
    sales_rep: 'jane.smith',
    product: 'enterprise_plan',
  }),
});

7. Handle pagination and rate limits

List endpoints (GET /v1/leads, GET /v1/sales) paginate by default at 100 records per page. Use the page query parameter to walk through pages. Rate limits are typically 60 requests per minute per API key; back off with exponential delay on 429 responses.

let page = 1;
let hasMore = true;
const allData = [];

while (hasMore) {
  const res = await fetch(
    `https://api.hyros.com/v1/sales?from=${from}&to=${to}&page=${page}`,
    { headers: { 'API-Key': process.env.HYROS_API_KEY } }
  );

  if (res.status === 429) {
    await new Promise(r => setTimeout(r, 60000));
    continue;
  }

  const { data, has_more } = await res.json();
  allData.push(...data);
  hasMore = has_more;
  page++;
}

8. Build idempotency into write operations

Webhook-style write operations should be idempotent. Use your internal sale_id as the unique identifier and rely on Hyros's dedupe logic to ignore replays. If you're scheduling the job, expect occasional retries - your code shouldn't double-count sales because of them.

9. Monitor the integration

API integrations break silently. Wire alerting on (a) auth failures (401 responses indicating key rotation or expiry), (b) sustained 5xx responses indicating Hyros API outage, (c) zero-record days from list endpoints (likely indicates upstream data flow break), and (d) significant deltas in pulled data volumes vs expected baselines.