Company API

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 one identifier; give me that one Company profile." Backed by our system of record. Returns licenses, Domains, enumerated payment methods, and content suppliers. Request include[]=firmographics and/or include[]=people for paid optional sections on the same resolved Company; each section is also available as a standalone query endpoint.
• 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

▸ Catalogue Companies carry an opaque company_ref (e.g. igfc_3uSBTwEXnRo1rfvmRs6fgdMr). Store and reuse it as a follow-up identifier, but do not parse, sort, or construct one: it is not a database ID. Page-only profiles may have company_ref: null; their page_url is a valid identifier for paid sections.

See Data Availability for current payment, provider, affiliate, export, and demo coverage, and what a missing value means.

Returned Company fields

Resolve profile

GET /companies/resolve supports these customer fields for each Company:

Each licenses[] item has license_ref, jurisdiction, license_number, status, license_type, and authorized_domains. Each apps[] item has store, app_id, and url.

Search row

GET /companies/search supports these customer fields for each ranked hit:

conference_count counts the conferences the company was seen exhibiting at, one per dated event: a firm standing at SiGMA Malta 2026 and SiGMA Rome 2026 counts two, and two stands at one show count one. It is 0, never absent, for a company we have seen at none. | Completeness and time | data_completeness, last_observed_at, last_updated_at | | Ranking | rank, score, matched_fields, highlight | | Availability hints | firmographics_available, contacts_available |

Resolve a Company

Send exactly one identifier. Resolve returns one Company, or it refuses and charges nothing. It never returns a list.

• No identifier returns 400 missing_identifier. Two or more return 400 one_identifier; domain_ref is not a Company identifier.
• Resolve does not take a licence number or a Company name search query. Search names with GET /companies/search?q=<name>, then use the returned identifier. Resolve the licence with GET /licenses/resolve, then pass its company_ref.
• A profile does not include the company page URL. The company page URL is part of firmographics: firmographics.page_url. A base profile can resolve without any page; this does not authorize a paid section without an exact page.

{
  "success": true,
  "data": {
    "resolved_by": "company_ref",
    "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"],
        "supplier_brands": ["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"
    }
  }
}

When an identifier names several Companies

When the identifier names more than one Company, resolve returns 409 ambiguous_company and charges nothing. The response gives the number of Companies and the search that lists them. It does not name the Companies. For paid sections, one catalogue Company holding several pages is also ambiguous: the error instead gives the actual page count and points to search?related=<company_ref> to pick a page. It never chooses the first held page. An explicit page_url selects the exact page and can succeed even when its catalogue Company holds several.

{
  "success": false,
  "message": "This identifier names 2 companies. Nothing was charged; search to see them.",
  "errors": {
    "code": "ambiguous_company",
    "candidate_count": 2,
    "next_action": {
      "type": "search",
      "method": "GET",
      "href": "/v1/companies/search?related=example.com",
      "preview_href": "/v1/companies/search/preview?related=example.com"
    },
    "billing": { "returned_count": 0, "credits_charged": 0, "billing_reason": "no_payload_delivered" }
  },
  "doc_url": "https://igamingfinder.com/docs/errors.md",
  "timestamp": "2026-09-28T10:30:00Z"
}

• candidate_count counts Companies for a multi-Company collision, or standing pages for a paid request on a Company holding several pages. The error message distinguishes them.
• next_action.href is the paid search that lists them. For a colliding legal_entity it is search?q=<value>; for company_ref, domain, and page_url collisions it is search?related=<value>. Unsupported Company name requests point to search?q=<value>. For several held pages on one catalogue Company it is always search?related=<company_ref>.
• next_action.preview_href is the same search as a free preview: the count and the price.

A paid request on a catalogue Company with no held page instead returns 409 company_page_required at zero credits. Supply that Company's page as page_url; an empty related search cannot find a page for it. An explicit page_url remains usable even when the page has no catalogue Company.

Resolve by company page URL

page_url takes a company page URL. The scheme must be https and the path must be /company/<slug>. The query, the fragment, and a trailing slash are ignored.

A short profile has company_ref: null and company_name. Its catalogue fields are empty: no licenses, Domains, payment data, or suppliers, and role is ["unknown"]. It can still carry firmographics and people when requested or queried via the standalone endpoints; availability is determined by the exact company page, not by a catalogue company_ref. Reading it does not create a catalogue Company or identity.

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 Domain in a profile carries an opaque domain_ref (for example, igfd_9mT7…) for Domain-specific features. Firmographics and people identify a Company by one of four Company identifiers, not by domain_ref.

Paid Company sections

Firmographics and people are independent paid sections. Request either alongside GET /companies/resolve with include[]=firmographics or include[]=people (repeat include[] for both), or use GET /companies/firmographics and GET /companies/people with exactly one of company_ref, domain, page_url, or legal_entity. Company names are search text: search with q and use a returned identifier. The standalone endpoints do not require a previously purchased profile. They do not accept domain_ref; 400 unsupported_enrichment_option is returned if it is sent. An unknown include[] or a role without include[]=people returns 400 invalid_include. A page-only Company with company_ref: null can be identified by its page_url.

curl -G -H "X-API-Key: igf_demo_9457cf242d0c43404fb69b8273d7f4371716682a12c74e3c3274fd8957ebeae7" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-urlencode "page_url=https://www.linkedin.com/company/example-gaming" \
  --data-urlencode "max_credits=12" \
  "https://api.igamingfinder.com/v1/companies/firmographics"

Firmographics contains name, description, industry, company_size, employee_count, founded_year, headquarters, website, and page_url. The standalone endpoint returns one flat object or null under data.firmographics for every identifier; on resolve it is data.companies[0].firmographics. An available firmographics object costs 12 credits. Unavailable firmographics cost zero optional credits.

{
  "firmographics": {
    "name": "Example Gaming",
    "description": null,
    "industry": "Gambling Facilities and Casinos",
    "company_size": [201, 500],
    "employee_count": 500,
    "founded_year": 2017,
    "headquarters": { "city": "Limassol", "region": null, "country": "Cyprus", "postal_code": null },
    "website": "https://example.com",
    "page_url": null
  }
}

data.people is an array of contacts, or [] when unavailable; on resolve it is data.companies[0].people. The contact objects have the same fields in both places (full_name, role, role_key, headline, location, profile_url, summary, skills, connections, followers, personal_emails); only the enclosing response differs. The standalone response also carries availability, reason, role counts, matched_count, total, deliverable, the selected-page scope, and billing fields. matched_count is the distinct number matching role before the cursor. total is the distinct complete population when the full page is known; it is null when the population is incomplete or people are unavailable. scope names the selected company page with its label and optional company_ref; it contains no raw page URL. People cost 9 credits per contact returned; unavailable/empty results charge zero optional credits. counts_only=true returns free role counts and aggregates instead of contacts. It accepts a blank role or published glossary keys joined by OR or commas. Arbitrary text is refused before any data is read for a free count, but remains a paid title-and-headline search.

One answer holds up to page_size contacts: 10 when absent, 100 at most. When more contacts are left, the answer has next_cursor and next_action.href. Send next_cursor as after with the same other parameters to get the next contacts, and repeat until next_cursor is null. Only null means the end: an answer can hold fewer than page_size contacts and still have a cursor. With role, the walk delivers every person of the page who matches. Each call is charged for the contacts it returns; max_credits and Idempotency-Key apply to each call. A cursor works only with the same API key, company page and role, and it stays valid until the people of the page change. A cursor that is no longer valid returns 400 invalid_cursor at zero credits; start again without after. returned is the number of contacts in the answer. deliverable is the number of distinct people in the available page copy, before any role filter. A walk without role ends after deliverable contacts.

All three Company endpoints return 400 unsupported_identifier if name is sent; search names with q. Standalone people and firmographics by domain return zero-charge 404 company_page_not_found when no company page names the domain, the domain is a confirmed shared platform, or it is too broad. When the main company page of the domain is not known, they return zero-charge 409 ambiguous_company with the number of pages that name the domain and next_action using related=<domain>. Other identifiers return 404 company_not_found if no Company/page matches; company_ref_not_found is a separate error for related search with an unknown ref, not a Company resolve/paid-section error. Several catalogue Companies return 409 ambiguous_company with a candidate search. A paid section by company_ref or legal_entity on a catalogue Company holding 2+ pages returns zero-charge 409 ambiguous_company with the actual page count and next_action using related=<company_ref>. If the Company holds no standing page, it returns zero-charge 409 company_page_required, asking for a user-supplied page_url without suggesting an empty related search. An explicit normalized page_url identifies its exact page regardless of how many other pages the Company holds.

Recommended path: find the company with search, then request people or firmographics with its page_url. By domain, people and firmographics use the main company page of the domain; each returned person names its page_url and, when a catalogue Company holds the page, that holder's company_ref. When the main page is not known, the call is refused at zero credits with a related search that lists the pages. No catalogue holder is required. Base GET /companies/resolve?domain=… still identifies licensees and the brand owner, not a company page.

Company paid sections use the exact Company page. A page-only result does not create a catalogue Company or identity. max_age_days and allow_stale_on_error are unsupported (400 unsupported_enrichment_option). Set max_credits to cap the whole delivery before any charge. Reuse an Idempotency-Key with identical parameters to replay without another charge. The response does not include source-network metadata.

Cost: 12 credits / delivered company

See the firmographics and people API playgrounds for all identifier parameters.

Search Companies

Preview first to see the result size and cost, then pull paid rows. Search rows are short discovery results — they carry payment/provider categories and counts, never the enumerated value lists, nested licenses, or full domain mappings (those are resolve-only). Their Domain samples can have domain_ref: null; call resolve with the row's company_ref to get a domain_ref for each Domain.

The preview returns the total count, counts per filter value and prices. It returns company names (sample) only to the signed-in Home dashboard; an API, CLI or MCP preview returns sample: [], and paid rows start at row 1.

A successful preview with matches includes next_action.href: a ready paid-search URL with the same public filters, at most 10 rows, and max_credits set to the quoted cost of that call. On the Home dashboard a segment continues with POST /companies/search/quote instead, which prices the next 10 companies after the free rows. It is null when nothing is left to show.

exact_name_match is true when q names a company in sample, reading case, accents and punctuation aside: GGBET names GG.BET, GG does not. Because sample is empty outside the Home dashboard, it is false there.

Next batch of a segment

POST /companies/search/quote fixes the next 10 companies of a segment that you have not seen or bought for the same query and filters. It returns a quote.token, the price, and how many of those 10 have a company profile, payment methods, suppliers and domains. The companies Home showed you free and the companies you already bought for the same q and filters are skipped. Without a Home answer the quote starts at row 1. Send the same q, role, sector (if selected) and other filters to preview and quote; otherwise they describe different lists. Home does not select a sector unless you choose one. The quote is free and is valid for 24 hours.

GET /companies/search/continuation?quote=<token> buys that batch. The rows have the same fields as the free rows: name, role, sector, jurisdiction, licence status and data counts. You are charged per row delivered. A company that left the catalogue after the quote is not delivered and not charged. A company you already bought for the same query and filters, for example through another quote, is skipped and not charged, so a batch can return 0 rows for 0 credits. A different query or filter may sell the same company again. One quote is bought once: a repeat with any Idempotency-Key returns the first delivery while it is kept (24 hours) and then 409 quote_consumed. To continue, send previous_quote=<token> to POST /companies/search/quote.

{
  "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,
        "supplier_brand_count": 1,
        "conference_count": 2,
        "platform_present": true,
        "affiliate_program_present": true,
        "geo_hints": ["en"],
        "data_completeness": 0.82,
        "last_observed_at": "2026-08-24T10:30:00Z",
        "last_updated_at": "2026-08-24T10:35:00Z",
        "rank": 1
      }
    ],
    "billing": {
      "returned_count": 20,
      "credits_per_result": 1,
      "credits_charged": 20,
      "page_size": 20,
      "billing_reason": "search_rows_delivered"
    }
  }
}

Related organizations

GET /companies/search?related=<value> lists the organizations related to one identifier, one row per company page. Send one value: a company_ref, a company page URL, or a domain. The value's shape tells which it is:

A name is not accepted: it returns 422 related_needs_identifier. Search names with q.

Each row has these fields:

Rows are sorted by relation (same_catalog_company, licensee, brand_owner, same_website), then by headcount, largest first. A row has no firmographics and no people. Resolve its page_url for a full or short profile, or query GET /companies/firmographics?page_url=<page_url> and GET /companies/people?page_url=<page_url> directly. A row with a company_ref can also use that ref when the Company holds exactly one standing page; for several held pages, use the specific page_url.

• related combines only with page, page_size, and max_credits. Any other search parameter returns 422 related_not_combinable.
• Each row is charged at the search row price (companies_search_result). GET /companies/search/preview?related=<value> is free: it returns the count and the price.
• POST /companies/search/quote does not take related (422 related_not_quotable). Buy the rows with GET /companies/search?related=<value>.
• When too many company pages list the domain, the answer is 422 related_too_broad at 0 credits.
• When the pages cannot be read, the answer is 503 related_unavailable at 0 credits. Try again later.

curl -G -H "X-API-Key: igf_demo_9457cf242d0c43404fb69b8273d7f4371716682a12c74e3c3274fd8957ebeae7" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-urlencode "related=stake.com" \
  --data-urlencode "page_size=10" \
  --data-urlencode "max_credits=10" \
  "https://api.igamingfinder.com/v1/companies/search"

People contacts for a Company

GET /companies/people returns decision-maker contacts for one Company by any of the four identifiers, including page_url when there is no catalogue company_ref. Search company names with q and use a returned identifier. It can also be included on GET /companies/resolve with include[]=people; the cost scales with contacts returned.

role narrows the page. A glossary key is a named filter — ceo, cto, marketing_leads, affiliates, compliance, payments, product_leads, decision_makers — published with its meaning and matched spellings by the free GET /people/roles. Any other term is a paid text search and matches as a substring. Terms combine with OR or commas, and the result is their union. Free counts_only accepts glossary keys only; it refuses arbitrary text before any data is read.

The job title decides the match, so a person's headline is only read when they carry no title at all, and a headline role is dropped when every company written after a role in that headline belongs to somebody else: "Founder, APEX CREATOR LABS" under an employer of Acme Bet is not an Acme Bet CEO. A headline that names no company still counts. Exclusions are applied to whichever of the two matched. That is why role=ceo does not hand you a "Vice President Human Resources".

Billing

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

• No charge for: empty results, company_not_found, validation/conflict errors (including 409 ambiguous_company and 409 company_page_required), withdrawn refs with no profile, 503 errors, 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 response without a new charge.
• companies/resolve has no free preview; use max_credits as its cost control. Included sections add 12 credits for available firmographics and 9 credits per returned contact. A rejected request reports required_credits; choose an optional section or raise the ceiling.

$ help --topic=domain-inputs

▸ domain inputs to resolve, search, and search/preview (and a domain sent as related) 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; sent as related, it returns 422 related_needs_identifier.