Two jobs: resolve vs search

Company is the customer-facing unit — any operator, supplier, studio, aggregator, platform, or PSP, licensed or grey. The Company API splits two different jobs:

• Resolve (GET /companies/resolve) — "I know an identifier; give me the authoritative Company profile." Backed by our system of record. Returns the full nested profile: licenses, Domains, enumerated payment methods and game providers, and provenance. Add include[]=firmographics only when you need paid operating-organization data for one or more exact Domains.
• Search (GET /companies/search) — "I have criteria; give me ranked candidates." Returns thin discovery rows (categories + counts), not full profiles. Preview the size and cost first with GET /companies/search/preview.

$ help --topic=company-ref

▸ Every Company carries an opaque company_ref (e.g. igfc_3uSBTwEXnRo1rfvmRs6fgdMr). It is the only stable follow-up handle: store it and pass it back to resolve. Treat it as a black box — do not parse it, sort by it, or construct new refs from it. It is not an internal database id.

Resolve a Company

Resolve has two input modes:

• company_ref mode — company_ref is authoritative and exclusive. Any natural identifiers sent alongside it are treated as assertions; a disagreement returns 409 conflicting_lookup_input.
• Natural identifier mode — use one or more natural identifiers. Resolve applies deterministic precedence license_number → domain → legal_entity → name; lower-precedence inputs are echoed under ignored_inputs.

Natural identifiers:

• license_number (+ optional jurisdiction) — a bare number matching multiple jurisdictions returns 409 ambiguous_license_number (charge 0); resend with jurisdiction.
• domain — a casino URL or host. Canonicalized to its registrable domain (scheme / subdomain / path / IDN stripped), then resolved to every Company behind it: licensee companies plus the brand owner, each tagged in matched_as (licensee, brand_owner, or both). An un-normalizable input (IP or junk) returns 400 invalid_domain; a normalizable domain absent from our data returns 404 not_found.
• legal_entity — exact legal company name match.
• name — exact company/brand name; collisions return matches[] candidates (charge 0).

Resolve does not fall through to a lower-precedence natural identifier when the highest-precedence input is ambiguous.

{
  "success": true,
  "data": {
    "resolved_by": "company_ref",
    "ignored_inputs": {},
    "input_company_ref": "igfc_3uSBTwEXnRo1rfvmRs6fgdMr",
    "resolved_company_ref": "igfc_3uSBTwEXnRo1rfvmRs6fgdMr",
    "ref_status": "active",
    "companies": [
      {
        "company_ref": "igfc_3uSBTwEXnRo1rfvmRs6fgdMr",
        "company_name": "Medium Rare N.V.",
        "legal_entity": "Medium Rare N.V.",
        "role": "operator",
        "matched_as": [],
        "domains": [
          { "domain_ref": "igfd_9mT7…", "domain": "stake.com", "inferred_geo": null }
        ],
        "licenses": [
          { "jurisdiction": "curacao", "license_number": "…", "status": "active",
            "license_type": "…", "authorized_domains": [
              { "domain_ref": "igfd_9mT7…", "domain": "stake.com", "inferred_geo": null }
            ] }
        ],
        "payment_methods": ["Bitcoin", "Visa"],
        "payment_categories": ["crypto", "card"],
        "game_providers": ["Evolution"],
        "affiliate_program": true,
        "geo_hints": ["EN"],
        "data_completeness": 0.82
      }
    ],
    "billing": {
      "returned_count": 1,
      "credits_per_profile": 3,
      "credits_charged": 3,
      "billing_reason": "company_profile_delivered"
    }
  }
}

company_ref lifecycle

An active company_ref resolves to exactly one Company. Stale refs are managed-stable: every company_ref-mode response echoes ref_status.

Every materialized Domain carries an opaque domain_ref (for example, igfd_9mT7…). Store it as the managed-stable selector for Domain-scoped follow-up requests; do not derive or construct it.

Paid Domain-scoped firmographics

firmographics is an explicit paid composition on Company resolve. It is never included in the base profile. The operating organization is matched from an exact eligible Domain; the resolver never guesses from the Company's legal name.

curl -G -H "X-API-Key: igf_demo_9457cf242d0c43404fb69b8273d7f4371716682a12c74e3c3274fd8957ebeae7" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-urlencode "company_ref=igfc_3uSBTwEXnRo1rfvmRs6fgdMr" \
  --data-urlencode "include[]=firmographics" \
  --data-urlencode "domain_ref=igfd_9mT7…" \
  --data-urlencode "max_age_days=30" \
  --data-urlencode "allow_stale_on_error=true" \
  "https://api.igamingfinder.com/v1/companies/resolve"

• With domain_ref, exactly that related Domain is selected.
• Without domain_ref, every deduplicated eligible Domain is selected in deterministic order. This is intentional fan-out, not "pick the first Domain."
• max_credits is checked against the profile plus all candidate Domains before any refresh starts.
• Each available fresh, cached, or stale Domain result uses the configured per-result rate below. Unavailable results remain in the array and cost zero optional credits.
• allow_stale_on_error defaults to true. Set it to false when a failed refresh must produce an unavailable result instead of the latest successful value.

Cost: 12 credits / delivered Domain result

The billing block reconciles the composite delivery explicitly: returned_count × credits_per_profile plus firmographics_returned_count × credits_per_firmographics_result equals credits_charged for a paid response.

When requested, firmographics is always an array, including [] when there are no eligible Domains:

{
  "firmographics": [
    {
      "domain": { "domain_ref": "igfd_9mT7…", "domain": "stake.com", "inferred_geo": null },
      "available": true,
      "cached": true,
      "stale": false,
      "reason": null,
      "fetched_at": "2026-07-15T12:00:00Z",
      "refresh": {
        "attempted": false,
        "status": "not_attempted",
        "reason": null,
        "attempted_at": null
      },
      "data": {
        "name": "Stake",
        "description": null,
        "website": "https://stake.com",
        "linkedin_url": "https://www.linkedin.com/company/stake-com",
        "industry": "Gambling Facilities and Casinos",
        "employee_count": 500,
        "company_size": [201, 500],
        "founded_year": 2017,
        "headquarters": { "city": "Limassol", "region": null, "country": "Cyprus", "postal_code": null }
      }
    }
  ]
}

The payload is closed and brand-neutral: only documented fields are returned. Raw source responses, source-specific IDs, internal cost events, and error text are never exposed.

Search Companies

Preview first to see the result size and cost, then pull paid rows. Search rows are thin discovery candidates — they carry payment/provider categories and counts, never the enumerated value lists, nested licenses, or full domain mappings (those are resolve-only). Their index-derived Domain samples can have domain_ref: null; pivot through the row's company_ref to resolve for materialized Domain selectors.

{
  "success": true,
  "data": {
    "query": { "payment_category": "crypto", "jurisdiction": "anjouan" },
    "total": 137,
    "page": 1,
    "page_size": 20,
    "hits": [
      {
        "company_ref": "igfc_7Qz…",
        "company_name": "Medium Rare N.V.",
        "role": "operator",
        "primary_domain": { "domain_ref": null, "domain": "stake.com", "inferred_geo": null },
        "domains_sample": [
          { "domain_ref": null, "domain": "stake.com", "inferred_geo": null }
        ],
        "domain_count": 1,
        "jurisdictions": ["anjouan"],
        "license_statuses": ["active"],
        "license_count": 1,
        "payment_categories": ["crypto", "card"],
        "payment_method_count": 2,
        "game_provider_count": 1,
        "affiliate_program_present": true,
        "rank": 1
      }
    ],
    "billing": {
      "returned_count": 20,
      "credits_per_result": 1,
      "credits_charged": 20,
      "page_size": 20,
      "billing_reason": "search_rows_delivered"
    }
  }
}

People contacts for a Company

GET /companies/:company_ref/people returns decision-maker contacts for a resolved Company. It is separate from GET /companies/resolve because people are not part of the base Company profile and the cost scales with contacts returned.

Billing

Charge-on-success delivery billing: you pay only for paid payload actually returned.

• No charge for: empty results, not_found, validation/conflict errors, ambiguous disambiguation matches[], retired refs with no profile, or a max_credits rejection before delivery.
• Paid GETs are non-cacheable (Cache-Control: no-store). To make a retry safe, send an Idempotency-Key header — a retry with the same key and request replays the original charge instead of charging again.
• companies/resolve has no free preview; use max_credits as its cost control. For Domain firmographics, the preflight ceiling includes the base profile and every candidate Domain. A rejected request returns required_credits so you can narrow with domain_ref or raise the ceiling.

$ help --topic=domain-inputs

▸ domain inputs to resolve, search, and search/preview (and domain assertions alongside a company_ref) are canonicalized through the shared domain normalizer — URL / subdomain / path / IDN / punycode reduce to the stored registrable domain — before matching. An un-normalizable input (IP or junk) returns 400 invalid_domain rather than an empty result.