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

Admin-only tool: Retrieve the product information of the users with the given emails.

hyros_admin_find_user_product_information

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. Each call's firstSource and lastSource are stored on it, not computed by an attribution model, so they can differ from FIRST_CLICK and LAST_CLICK reports.

hyros_get_calls

Counts the calls from a search by grouping them according to the tag of their first or last source, or their qualification stage. It is used to determine how many calls there are per source or per stage; for example, to break down the booked calls of a period between paid and organic traffic, or across the stages of the call funnel. The response contains three numbers that answer different questions: "groups" field shows how the calls that have a value for the selected attribute are distributed; "remainingCount" field indicates how many calls 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 calls matched the search. A call has at most one value of each attribute, so it belongs to at most one group, and a call without a value (no source, or no qualification stage yet) belongs to none: totalCount minus the sum of the groups is the number of calls with no value for that attribute. When grouping by FIRST_SOURCE_TAG or LAST_SOURCE_TAG, each group also carries a "details" object whose "source" describes the source link: name, organic and disregarded flags, traffic source, category, goal, and ad source (platform and ad account). This makes it possible to calculate paid vs. organic traffic, as well as calls by traffic source or ad account, from this call. FIRST_SOURCE_TAG and LAST_SOURCE_TAG group by the source stored on each call, not by an attribution model, so counts can differ from FIRST_CLICK and LAST_CLICK reports.

hyros_get_calls_aggregation

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. Each sale carries the "orderId" of the order it belongs to, so sales with the same "orderId" were made in the same purchase.

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

Create a GitHub access token that can clone, pull and push the account's dashboard repository, valid for one hour. Returns the token, its expiry and the repository's HTTPS clone URL. Git authenticates with the username x-access-token and the token as password. Request a new token when the current one expires or git reports an authentication error. Fails while the account's dashboard is not set up yet.

hyros_get_dashboard_repository_token

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. Use it to reconstruct everything Hyros knows about a person's path from first click to purchase.

hyros_get_lead_journey

Retrieve the lead stage rules of the account's active integrations, as the integration's Lead Stage Rules settings show them: for each rule, the stage it applies, the integration events that apply it (for HighLevel, the contact tags), and whether it is active. Use it to confirm which event feeds which stage. When useDefaultLeadStages is true the rules are not consulted: each event applies the stage named after it. Saving a rule does not backfill: it applies its stage to events received from then on, so a lead that already carried the tag or event gets the stage only when a new event for it arrives (for HighLevel, any tag update on the contact, which carries all its tags).

hyros_get_lead_stage_rules

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. Each lead's firstSource and lastSource are stored on it, not computed by an attribution model, so they can differ from FIRST_CLICK and LAST_CLICK reports.

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. When grouping by FIRST_SOURCE_TAG or LAST_SOURCE_TAG, each group also carries a "details" object whose "source" describes the source link: name, organic and disregarded flags, traffic source, category, goal, and ad source (platform and ad account). This makes it possible to calculate paid vs. organic traffic, as well as leads by traffic source or ad account, from this call. FIRST_SOURCE_TAG and LAST_SOURCE_TAG group by the source stored on each lead, not by an attribution model, so counts can differ from FIRST_CLICK and LAST_CLICK reports.

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. Read notes before quoting any figure: INSUFFICIENT_DATA means the curve rests on fewer than 10 days with spend, fewer than 10 new customers or fewer than 2 spend levels that acquired any, so it is too thin to act on and no saturation point is reported. At ACCOUNT level there is no LTV to fall back on: pass cacCeiling, or the only saturation it can find is spend that buys no extra customers. 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. It is always measured under LAST_CLICK; no other attribution model can be chosen.

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. They are stored on the sale, not computed by an attribution model, so they can differ from FIRST_CLICK and LAST_CLICK reports. Use it for revenue reporting, or to find sales whose attribution is missing because both sources are absent. 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

Counts the sales from a search by grouping them according to the tag of their first or last source. It is used to determine how many sales there are per source; for example, to break down the sales of a period between paid and organic traffic. The response contains three numbers that answer different questions: "groups" field shows how the sales that have a value for the selected attribute are distributed; "remainingCount" field indicates how many sales 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 sales matched the search. A sale has at most one source of each kind, so it belongs to at most one group, and a sale without a source belongs to none: totalCount minus the sum of the groups is the number of sales with no source of that kind. Each group also carries a "details" object with two parts: "source" describes the source link (name, organic and disregarded flags, traffic source, category, goal, and ad source with platform and ad account), and "revenue" is the sum of the stable USD price of the sales counted in the group, with its currency. This makes it possible to calculate paid vs. organic traffic, and revenue as well as sales by traffic source or ad account, from this call. FIRST_SOURCE_TAG and LAST_SOURCE_TAG group by the source stored on each sale, not by an attribution model, so counts can differ from FIRST_CLICK and LAST_CLICK reports.

hyros_get_sales_aggregation

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. To classify or count the account's sources, set includeOrganic and includeDisregarded to true: both default to false, so the default response holds neither the organic sources nor the disregarded ones, and any paid-vs-organic split computed from it undercounts both sides. 'organic' is a flag the account sets on the source, not something derived from ad spend. Two definitions of 'paid' are in play and they disagree on a source with no ad spend that was never flagged organic, such as a ManyChat growth tool (organic=false, disregarded=true, no adSource, trafficSource 'ManyChat'). Paid as 'not organic' (organic is false) is what Hyros itself means by paid: it is what sourceConfiguration ONLY_PAID selects on the attribution report and what the account's report screens apply, and a ManyChat growth tool counts as paid under it. Paid as 'has ad spend' (adSource present) counts only sources on an ad platform, and excludes that growth tool. Pick one, say which one the figures use, and never mix them in a single report.

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