Hyros

Create a source link so traffic and sales arriving through it are attributed to it. Sources can be organic, non-organic, or tied to an ad platform such as Google or Facebook. Use it to start tracking a new traffic source, campaign or placement. Processed asynchronously; the change is typically visible within ~10 seconds. The response carries a requestId; check the outcome with hyros_get_request_status.

hyros_create_source

Record a subscription for a lead, with its product, price, billing period and state. Creates the lead first if no lead exists for the given email. Use it to bring recurring plans from a billing system into Hyros so recurring revenue is attributed to the traffic that produced it. Processed asynchronously; the change is typically visible within ~10 seconds. The response carries a requestId; check the outcome with hyros_get_request_status.

hyros_create_subscription

Create a simple URL rule that tags leads whose tracked URL matches the given words. The tag prefix sets the flavor: '!' action tag, '@' source tag, '$' sale tag, '#' subscription tag. Use it to bulk-create URL-based tagging, e.g. for dynamically generated webinar or booking URLs.

hyros_create_url_rule

Delete a booked call by its call id, removing it from call reporting and from its lead's journey. Use it to remove a call that was recorded in error or duplicated. Processed asynchronously; the change is typically visible within ~5 minutes. The response carries a requestId; check the outcome with hyros_get_request_status.

hyros_delete_call

Delete a custom cost by its id, removing it from profit and ROI reporting. Use it to remove a cost entered in error or one that no longer applies. The change applies immediately.

hyros_delete_custom_cost

Permanently erase a lead, identified by lead id or email: personal data is redacted, phone numbers, sales and tracking data are deleted, and subscriptions are cancelled. The lead's email address and phone numbers are also blacklisted, so later events carrying them are discarded instead of re-creating the lead. Use it for data-erasure requests such as GDPR or CCPA. This cannot be undone. The erasure applies immediately; the lead takes up to ~5 minutes to disappear from lead retrieval. The response carries a requestId; check the outcome with hyros_get_request_status.

hyros_delete_lead

Delete a product by its id. Use it to retire a product from the catalogue so it is no longer offered for attribution of new sales. The change applies immediately.

hyros_delete_product

Delete a sale by its sale id, removing it from revenue and attribution reporting. Use it to remove a sale that was reported in error or duplicated. Processed asynchronously; the change is typically visible within ~5 minutes. The response carries a requestId; check the outcome with hyros_get_request_status.

hyros_delete_sale

Delete a source link by its tag. The source is soft-deleted and stops appearing in attribution. Use it to retire a tracked link that is no longer in use. The deletion applies immediately; the source takes up to ~5 minutes to disappear from source retrieval.

hyros_delete_source

Delete a URL rule by its id, so it no longer tags matching traffic. Use it to retire a rule the account no longer needs.

hyros_delete_url_rule

Start generating a report over the account's attribution and revenue data, grouped by source, ad, creative, keyword, geography, referrer, cohort, lead journey or sale item, over a date range. Use it to answer questions the individual retrieval tools cannot, such as which sources drove the most profit, which keywords earned their spend, or which products sold best. Pass 'timeZone' as the requester's UTC offset (+HH:mm / -HH:mm) whenever it is known, so that relative ranges such as 'yesterday' resolve in their day rather than the account's. Returns a report id immediately; the report itself is computed asynchronously, so read it with 'hyros_poll_public_report_result'.

hyros_generate_public_report

Retrieve the account's default HYROS tracking script, ready to install on a site. Use it when the snippet is needed as-is, with no domain override and no tracking options.

hyros_get_account_tracking_script

Retrieve the account's active integrations of one external platform type, with their configuration. Use it to confirm whether a platform is connected and how, for example when ad spend or sales from that platform are missing. The configuration carries the settings that govern what the integration imports, never its credentials.

hyros_get_active_external_integrations

Retrieve the attribution report aggregated per ad account for a date range, rather than per campaign, ad set or ad. Use it for account-level spend and revenue totals, or to compare whole ad accounts against each other; prefer it over hyros_get_attribution_report when you only need totals, since it sums all sources in one call with no pagination. Ad account ids are the id values of the connected ad accounts listing.

hyros_get_ad_account_report

Retrieve the ad accounts connected to the Hyros account, with the ad platform and ad account id of each. Use it to see which ad platforms are connected, or to obtain the ad account ids that the ad account attribution report takes as input. When ids are provided only the matching ad accounts are returned; otherwise every connected ad account is returned.

hyros_get_ad_accounts

Search and retrieve the ad-level sources of the account, filtering by ad spend type and id. Use it when reporting needs individual ads rather than the source links above them. Results are paginated.

hyros_get_ads

Retrieve the ads attribution report for a date range, broken down by campaign, ad set or ad. Returns the ad spend, revenue and conversion metrics Hyros attributes to each ad source under the requested attribution model. With isAdAccountId it pages over the account's sources, oldest first unless newestFirst is set. With leadStage every attributed lead and sale is filtered to the given account lead stages, matched on the lead's current stage, so leads, sales, revenue and ROAS all narrow while ad spend does not. That is how ads are ranked by a funnel outcome such as approvals or booked calls, and the stage names come from hyros_get_stages. Use it for ad performance questions such as which campaigns or ad sets are profitable, or to compare how the same period looks under different attribution models.

hyros_get_attribution_report

Search and retrieve booked calls by creation date, last-modified date, lead email, lead id, product tag, call id, qualification state or qualification stage. Use it to review call volume and outcomes over a period, or to find the calls belonging to a specific lead. Filter by updatedFromDate to fetch only what changed since a previous sync instead of the whole window. Results are paginated.

hyros_get_calls

Search and retrieve carts by creation date, purchased state, lead email or lead id. Each cart includes its items and the lead that owns it. Use it for abandoned-cart work, for example carts created more than a couple of hours ago that still have no orderId. When both emails and leadIds are given they are combined with AND. Results are paginated.

hyros_get_carts

Retrieves the conversions of one type (sales, calls or leads) in a date range together with the ordered source touches each one was attributed with, so an external attribution model can be computed over them.

hyros_get_conversion_paths

Retrieve the manually entered costs of the account. A cost matches the requested window when its active range overlaps it. Use it to review costs that are not imported from an ad platform, or to obtain the id needed to update or delete one. Results are paginated.

hyros_get_custom_costs

Retrieve the external integration types Hyros supports, each with its identifier and display name, or only the ad-spend subset when adspendOnly is set. Use it to obtain the valid type value that the integration tools take as input. Lists the supported types themselves, not the account's connections.

hyros_get_integrations_types

Retrieve the keywords tracked by the account, or only those of one Google ad group when adgroupId is supplied. Use it for keyword-level search reporting, or to confirm which keywords Hyros has ingested from a connected Google Ads account. Results are paginated.

hyros_get_keywords

Retrieve the clicks recorded for one or many leads, identified by a single lead id, a list of lead ids or a list of emails, each click with its URL and ad source. Exactly one of those three selectors is accepted, and each click carries the id and email of the lead it belongs to. Use it to see the traffic that brought a lead in, or to find clicks whose URL has no matching source link and is therefore untracked. Results are paginated.

hyros_get_lead_clicks

Retrieve the click and attribution journey of one or more leads, identified by lead ID and/or email: sales, calls, carts, subscriptions and linked leads. At least one id or email is required. An email may resolve to more than one lead, in which case one journey is returned per matched lead. Use it to reconstruct everything Hyros knows about a person's path from first click to purchase.

hyros_get_lead_journey

Retrieve the lead stages defined for the account, each with a count of leads in it. Without stageFromDate/stageToDate the count is the leads whose current stage it is; with them it is the leads the stage was applied to inside that period, which is what answers questions like how many leads entered a stage this week. The two counts are not comparable: applications accumulate, so a lead that moved between stages inside the period is counted under both. Use it to see the funnel Hyros tracks leads through, or to obtain the stage names that lead retrieval and the ads attribution report filter on. Results are paginated.

hyros_get_stages

Search and retrieve leads by join date, last-modified date, email, phone number, lead id, current stage, tags or the date a tag was applied. Use it to look up a specific person, to list leads that entered or changed within a period, to report on who was tagged during a period, or to obtain the lead ids other lead tools take as input. Results are paginated.

hyros_get_leads

Counts the leads from a search by grouping them according to an attribute, which can be a tag, the current stage, or the tag of the first or last source. It is used to determine how many leads there are rather than which leads they are; for example, to understand how leads are distributed across stages, which tags are most frequently used, or where leads from a given period came from. The response contains three numbers that answer different questions: "groups" field shows how the leads that have a value for the selected attribute are distributed; "remainingCount" field indicates how many leads were left out because their group did not fit within "groupsLimit" request param, so increasing this limit by that number is enough to retrieve all remaining groups; and "totalCount" field indicates how many leads matched the search. The groups should not be summed to obtain a total, since a lead without the attribute does not belong to any group, while a lead with multiple values can belong to more than one group.

hyros_get_leads_aggregation

Compute how the cost of acquiring the next customer changes at every daily spend level for a single ad, ad set, campaign or ad account, from the account's own spend history. Returns the curve points (average and marginal CAC per spend level), the saturation point past which the next dollar costs more than the CAC ceiling, and the ceiling used. Customers are attributed under the first-click model with rebills included, so values differ from last-click reports such as hyros_get_roas_report; pass attributionModel to measure under last-click instead, which turns it into a closing-cost curve for retargeting and bottom-of-funnel entities. Use it to decide how far an entity's daily budget can scale before it stops paying for itself; use hyros_get_roas_report to judge past profitability at the current spend level.

hyros_get_marginal_cac_curve

Search and retrieve products by name, tag, category or recurrence. Use it to see the product catalogue Hyros attributes sales against, or to obtain the id needed to update or delete a product. Results are paginated.

hyros_get_products

Retrieve the ROAS of a single ad, ad set, campaign or ad account for a date range, from the cash Hyros attributes to it rather than from platform-reported conversions. Returns one row with roas, which is revenue over spend and so breaks even at 1.0, plus new_customers_roas, revenue including subscription rebills, cost, and the gap against what the platform reported. Use it to judge whether one entity is profitable; use hyros_get_attribution_report to compare several, to pick metrics, or to break a period down by date.

hyros_get_roas_report

Check the outcome of a write that is processed asynchronously, using the requestId the write returned. 'PENDING' means the write has not been confirmed yet, and is never a reason to resend it; 'PROCESSED' means it completed, and carries a 'result' holding the resource as its own retrieval tool returns it, as it stood when the write completed, for the writes that produce a readable one; 'FAILED' carries an 'errorMessage' explaining why. Poll this instead of resending the write, which would duplicate it. Statuses are kept for 2 hours; wait a few seconds between polls.

hyros_get_request_status

Search and retrieve sales by creation date, last-modified date, lead email, lead id, product tag, sale id, recurrence or refunded state. Each sale carries its attributed first and last source. Use it for revenue reporting, or to find sales whose attribution is missing because both sources are empty. Filter by updatedFromDate to fetch only what changed since a previous sync instead of the whole window. fromDate/toDate always bound when the sale was made, never when it was refunded, so refunded sales over a range is not the same count as refunds issued in it, each sale's own refundDate answers the second. Results are paginated.

hyros_get_sales

Search and retrieve the source links of the account, filtering by name or tag, by organic and disregarded status, or by ad spend type and id. A source link is the tracked link Hyros attributes traffic and sales to. Use it to audit which links are tracked, or to find the tag needed to update or delete one. To check whether one specific source exists, filter by its name or tag instead of paging through the whole account. Results are paginated.

hyros_get_sources

Search and retrieve subscriptions by start and end date, lead email, lead id, product tag, subscription id or state. Use it for recurring-revenue reporting, such as which subscriptions are active, cancelled or churned in a period. Results are paginated.

hyros_get_subscriptions

Retrieve the names of every tag defined in the account, as a flat list without lead counts, filtering or pagination. Use it when only the tag names are needed. Superseded by hyros_get_tags_count, which returns the same tags together with the number of leads carrying each one and supports filtering by name and pagination.

hyros_get_tags

Retrieve the tags defined in the account together with the number of leads carrying each one, filtering by name and paginating the results. A lead holding several tags is counted once under each of them. Use it to see how the audience is segmented, or to find the tag that identifies a product or campaign.

hyros_get_tags_count

Retrieve the Hyros tracking script to install on a site, optionally for a specific verified domain and with single-page-app tracking, previous-URL handling or iframe embedding enabled. Without a domain the account's default script is returned. Use it to obtain the snippet to install, or to regenerate it with different options. Supplying deleteTrackingScriptParams also stores that choice as the account's tracking preference.

hyros_get_tracking_script

Retrieve the account's HYROS tracking script rewritten to load from a custom domain. Use it when tracking must be served from the customer's own domain, for example to survive tracking blockers.

hyros_get_tracking_script_with_custom_domain

Retrieve a single URL rule by its id, with its name, tag, matching words and flavor. Returns nothing when no rule has that id.

hyros_get_url_rule