ACTION_ID: company_ip_data_waterfall
NAME: Enrich IP data
CATEGORY: Company Enrichment
CREDITS: 0-1 varies by provider — see the individual provider actions

Resolve a company's IP holdings by stepping down through APNIC,
HackerTarget and IP2Location until one returns data. Accepts either an
ASN or a company name.

1. INPUTS

ip_data_providers (stepDownSearch, optional) — IP Data Providers
  The ordered waterfall of providers, tried in sequence until one returns
  a hit. Providers are addressed by name and the available set changes
  over time, so resolve it rather than hard-coding it:

    POST .../actions/{action_instance_id}/options/ip_data_providers   (body: {})

  Set the order (and which providers run at all) with Configure Action:

    {"inputs": {"ip_data_providers": ["<Name A>", "<Name B>"]}}

  To run a provider on your own API key instead of Floqer credits, pass
  `{"name": "<Name A>", "use_own_key": true}` in place of the bare name.
  Full rules — key state, reorder-only updates — are
  in concepts.txt §8 "Waterfall provider fields".

asn (type: string, optional)
  ASN. Autonomous System Number

company_name (type: string, optional)
  Company Name

confidence_score_threshold (type: number, optional)
  Confidence Score Threshold. Confidence score threshold

2. OUTPUTS

total_ip_holdings (number) — IP holdings

ip_resources (raw_array) — IP resources

best_match (string) — Best Match

confidence_score (number) — Confidence Score

3. HOW TO CONFIGURE

The provider list is an ordinary input field. Set which providers run,
and in what order, through Configure Action; to reorder without touching
the enabled set, use Reorder Waterfall Providers:

  PATCH /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/waterfall/ip_data_providers
  { "providers": ["APNIC", "Hacker Target", "IP2Location"] }

Configure Action body:

{
  "inputs": {
    "company_name": "{{input.company_name}}",
    "asn": "{{formula_01ab.result}}",
    "confidence_score_threshold": "80"
  }
}

Field-by-field:
  - company_name / asn          Supply at least one. APNIC and
                                IP2Location match on name; HackerTarget
                                needs the ASN.
  - confidence_score_threshold  Slider — pass as a quoted string. Applies
                                to the name-matching providers only.

4. KEY NOTES

- Reorder Waterfall Providers only reorders: its `providers` array must
  list every currently configured provider by DISPLAY NAME exactly once.
  Use Configure Action to add or remove providers. Get Action Field
  Options on `ip_data_providers` returns the valid names.
- The three providers need different inputs: HackerTarget matches on
  `asn`, APNIC and IP2Location on `company_name`. Wire both fields,
  otherwise the steps that need the missing one are skipped and the
  waterfall looks like it failed.
- `confidence_score_threshold` is a slider field — pass it as a quoted
  string.
- The waterfall stops at the first provider that returns data, so cost
  depends on which step hits. It is not the sum of all providers.
- Chain `company_asn_lookup` before this action to supply the ASN that
  HackerTarget needs.

5. WHERE IT FITS IN A WORKFLOW

Pattern: company_asn_lookup -> formula (pluck the first ASN) ->
company_ip_data_waterfall -> filter (ip_holdings greater than 0).

6. WHEN TO USE

Use company_ip_data_waterfall when you want IP-holdings coverage across
regions and are happy to let Floqer pick the provider that answers.

7. WHEN NOT TO USE

Want to pin the lookup to APNIC and control the threshold yourself
  -> action-detail/company_ip_resources_lookup.txt

Only need the ASN list
  -> action-detail/company_asn_lookup.txt

Last updated: 2026-08-03.