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.
• 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

Provide exactly one of these, or an opaque company_ref:

• company_ref — authoritative and exclusive. Any natural identifiers sent alongside it are treated as assertions; a disagreement returns 409 conflicting_lookup_input.
• license_number (+ optional jurisdiction) — a bare number matching multiple jurisdictions returns 409 ambiguous_license_number (charge 0); resend with jurisdiction.
• legal_entity — exact legal-entity match.
• name — exact company/brand name; collisions return matches[] candidates (charge 0).

When more than one natural identifier is supplied, precedence is license_number → domain → legal_entity → name; lower inputs are echoed under ignored_inputs. Resolve does not fall through to a lower input when the highest 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.",
        "segment": "b2c_operator",
        "matched_as": [],
        "domains": ["stake.com"],
        "licenses": [
          { "jurisdiction": "curacao", "license_number": "…", "status": "active",
            "license_type": "…", "authorized_domains": ["stake.com"] }
        ],
        "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",
      "idempotent_retry": false,
      "cached_data_billable": true
    }
  }
}

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.

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).

{
  "success": true,
  "data": {
    "query": { "q": "crypto curacao" },
    "total": 137,
    "page": 1,
    "page_size": 20,
    "hits": [
      {
        "company_ref": "igfc_7Qz…",
        "company_name": "Medium Rare N.V.",
        "segment": "b2c_operator",
        "primary_domain": "stake.com",
        "domains_sample": ["stake.com"],
        "domain_count": 1,
        "jurisdictions": ["curacao"],
        "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"
    }
  }
}

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. A rejected request returns required_credits so you can raise the ceiling.

$ help --topic=domain-inputs

⚠ domain inputs to resolve, search, and search/preview are not yet available and return 501 domain_input_unavailable while canonical domain normalization ships. Use company_ref, license_number, legal_entity, or name in the meantime.