Practical setup notes for API users and Widgets V2 publishers.

Help & FAQ

Practical help for SoccersAPI and Widgets V2

Use this page to avoid the common setup mistakes: unsaved widget configurations, wrong domains, stale embed files, plan limits and API base URLs.

Create widget

Open the admin and create a saved Widgets V2 configuration.

Contact support

Send us your uid, widget-id, domain and expected traffic.

Check domains

Confirm production domains before copying the embed code.

Getting started

What should I use first: API or Widgets V2?

Use the API when you are building a custom product and need JSON data. Use Widgets V2 when you want ready-made live score, match, league, team or player screens that can be configured and embedded quickly.

Where do I create a widget?

Create an account in the SoccersAPI admin, open the Widgets V2 configurator, choose the widget type, set domains and leagues, adjust the UI, save the configuration and then copy the generated code.

Why is saving important before copying code?

The embed loads the saved widget configuration by uid and widget-id. If the configuration is not saved or published yet, the iframe can return widget_not_found or show older settings.

Embeds and delivery

How does the free iframe work?

The free plan uses an iframe hosted on embed.soccersapi.com. It supports one approved domain, one saved configuration and 25K views per month. SoccersAPI branding, bookmaker odds, affiliate links or banners may appear on the free embed.

When should I use the native web component?

Use the native web component on upgraded plans when cleaner page integration, styling and production placement matter. Use Dynamic Pages separately when a domain needs entity-aware variables and dedicated routes per match, league, team or player.

Why does the widget look different from the configurator?

The configurator and embed must use the same saved config and the same built widget bundle. If the server still serves an old bundle or stale free.html, styling such as entity headers, modal padding or Pro features can differ.

Domains, plans and limits

Why does my domain not work?

Add the exact domain in the widget configuration and save it before testing. Domain validation checks the parent domain for iframe delivery and the current host for native widgets.

What happens if I select more leagues than my plan allows?

Widgets V2 plans are limited by delivery mode, traffic, approved domains, saved configurations and Pro feature flags. API league coverage is managed by your API subscription.

How are traffic limits handled?

Widgets use heartbeat and traffic tracking. Free uses a hard cap with 80% and 100% alerts. Upgraded plans use soft thresholds so you can review usage before upgrading or adjusting the plan.

Troubleshooting

The iframe says widget_not_found. What should I check?

Confirm the uid, widget-id and saved configuration. The most common cause is copying the embed before saving the widget setup in the admin.

The iframe loads blank or shows $1 is not defined. What does that mean?

That points to an outdated or malformed free.html file on the embed host. Redeploy the latest embed file and verify it no longer contains literal replacement artifacts.

The widget requests localhost data in production. What should I check?

Verify the built widget bundle uses the production API base URL and that the server copied the latest dist assets to the static widget path.