API 3.0
Football API 3.0
Ask or search…


Since the release of API3 and onwards, we will list any additions and changes made in the API on this page, in chronological order (YYYY-MM-DD format)


  • Introducing the ability to perform custom sorting on Sportmonks API3 endpoints! With this enhancement, users can now include the sortBy parameter to sort base entities in ascending or descending order. The feature supports sorting on fields like starting_at and name for fixtures, providing users with greater flexibility in organising and retrieving data.
    You can find more information on the dedicated sorting page.


  • An endpoint to retrieve extended squad details has been added. This endpoint shows all players that were active in the current seasons for the team. If a player is no longer part of the squad or is currently a youth team player, the in_squad field is marked false.
  • Periods now contain a has_timer attribute. It marks whether we have detailed timer information for minutes and seconds attributes available.
  • Minor updates and optimisations to our back-end infrastructure.


  • Historical records and value changes are now available for the Premium Odds Feed. They are available via the history include (updates since 5 minutes ago) on PremiumOdd records, or via the respective All and Updated endpoints (all updates).
  • An endpoint that lists all the supported timezones has been added.
  • Passing your preferred time zone now also has direct effect on the query results on the League By Date endpoint.


  • Due to a deviation in the aggregation of API3 request logs, we have cleared the tables records and added a fix for the behaviour. The API usage endpoint now returns the correct results again.


  • A new event type has been implemented which tracks VAR checks related to cards. From today onwards all VAR events that are related to cards are covered under the VAR_CARD event type.
"id": 90673921,
"fixture_id": 18867346,
"period_id": 4993000,
"participant_id": 7790,
"type_id": 1697,
"section": "event",
"player_id": 435939,
"related_player_id": null,
"player_name": "Federico Baschirotto",
"related_player_name": null,
"result": null,
"info": null,
"addition": "Redcard confirmed",
"minute": 56,
"extra_minute": null,
"injured": null,
"on_bench": false,
"coach_id": null,
"sub_type_id": null,
"type": {
"id": 1697,
"name": "VAR_CARD",
"code": "VAR_CARD",
"developer_name": "VAR_CARD",
"model_type": "event",
"stat_group": null


  • An endpoint for insights into your API usage has been added. This endpoint will return your usage aggregated per endpoint per 5 minutes. You may for example use this endpoint to build your own monitoring dashboards, or to gain insights into how you can optimize your traffic to our API by spreading your usage. 📊💻


  • Both Referee and Coach entities now offer the possibility to add the latest include. The include providers their latest fixtures records from the past 6 months.


  • When available, a code field has been added to the API error response, these errors include a link to our documentation pages where the errors are explained more briefly. The code corresponds to one of the entries in the listed table.
Errors now contain a code attribute when available.
  • When using the statistics include on a Season, using the nested Type include caused the original type field for the object to be overridden. To prevent this behaviour from happening, the relational Type object will now be available under the statistic_type attribute.
    Type object now available under statistic_type attribute.


  • TV station BT Sport has been renamed to TNT Sports due to rebranding. (affecting ID 46 and 860). TNT Sports 2, 3, 4 are newly added under ID 928, 929, 930.



  • Endpoints for retrieving statistics have been added. These allow you to easily retrieve statistics for specific seasons, stages, or rounds, instead of having to propagate through includes to retrieve them.
  • A new include called 'currentPeriod' has been added. It allows for retrieval of the inplay period in a more convenient way compared to using the periods include. Please note the include may return NULL. For example when the match has not yet started, is in half-time, or has ended.
  • The PlayerStatistic entity now contains a has_values field, indicating whether a Player has any statistics available for the given season.
  • We have renamed the BEATS type to SUCCESSFUL_DRIBBLES to better reflect the type of statistic.
A tutorial which covers all the new features added with this release



  • We have added the currentPeriod include. You can use this as a more convenient way to get the current inplay period for a fixture. Note that the result can be null, for example when the fixture itself is not inplay or the fixture is currently in half-time break.


  • The Multiple Fixtures by Id endpoint now allows a maximum of 50 unique id's, this reflects the maximums (per_page) we allow on default paginated endpoints.


  • The developer name of Type "Screwsnails Removal" (id: 830) has been renamed to SCREWS_NAILS_REMOVAL for naming convention.


As per an earlier announcement, we have released some changes to the API on this date.

Removed fields:

  • State: is_live, is_pending, is_period_end, is_final_state, is_cancelled, is_final_standing_state, is_completed, type_id, is_deleted, is_notstarted, period_length_setting, deactivate_inplay
  • Period: period_length_internal, final_minute, home_score, away_score
  • Fixture: last_processed_at

Renamed fields:

  • Squad: yersey_number was renamed to jersey_number
Added fields:
  • League: category (basic tier like indicator for the size / popularity of the league. Ranges from 1-4, where 1 are the most 'popular' leagues.
Ordering on endpoints:
  • Paginated endpoints now support ordering, you can pass a query parameter order with your request to indicate the desired order. Currently order=desc and order=asc are supported. Visit the documentation of the endpoint you are wishing to use ordering on to obtain the field that the ordering applies on.
Threshold adjustments:
  • The threshold of the Latest Updated Fixtures endpoint was lowered from 5 minutes, to 10 seconds. The previous threshold of 5 minutes fetched too much results at times, causing requests to time out.