Skip to content
Developer docsREST · JSON and PNG · /v1

Reference

Football API reference

Download OpenAPI

Explore every REST feed endpoint, its parameters and response fields. Request examples use your own key; response examples are illustrative, not live data. Pro-plan MCP setup and tool arguments are covered in the separate MCP guide below.

Matches

Scores and results

GET/api/v1/football/scores
Availability not loaded

Scores and results. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and access

Send your FootballAPI.net key using X-API-Key or Authorization: Bearer. Keep keys on your server, not in public browser code. Creating a key does not activate a subscription or this endpoint.

Parameters

No parameters.

Success response 200

A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.

data retains the provider’s nested records and attributes; fields vary by feed. meta.fetchedAt is the retrieval time, not a match event time. meta.ttlSeconds is a cache lifetime, not a guaranteed update speed. Provider timestamp timezones are not yet certified.

  • dataobjectrequired
  • metaobjectrequired
    • feedstringrequired
    • fetchedAtstring (date-time)required
    • ttlSecondsintegeroptional
    • qualificationstringoptional
      sample_receivedpendingblocked
    • timezonestringoptional

      Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC.

X-RateLimit-Limit
string · Account safety request limit per second (100).
X-Usage-Daily-Included
string · Included successful requests per UTC day: 5000, 25000 or 250000.
X-Usage-Daily-Used
string · Successful feed requests today across all account keys, including overages.
X-Usage-Daily-Remaining
string · Included requests remaining today; zero does not block paid metered usage.
X-Usage-Daily-Reset
string · Next midnight UTC as a Unix timestamp in seconds. No rollover.
X-Usage-Overage-Rate-EUR
string · 0.002 EUR per additional successful request for paid metered subscriptions; billed monthly in arrears on the EUR subscription invoice. Failed and denied attempts are not billed.

No per-second remaining or reset header is sent.

Error responses

400

Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.

401

The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.

403

The key is recognised, but the account has no active entitlement or permission for this feed.

404

The requested football resource or image is unavailable.

429

The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.

Retry-After
string · Seconds to wait before retrying.
502

The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.

503

The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.

504

The provider request timed out. Retry with backoff rather than issuing concurrent requests.

429 carries Retry-After in seconds. Per-second and monthly exhaustion share the code quota_exceeded; compare X-RateLimit-Monthly-Remaining from earlier responses to tell them apart.

Make real calls from the signed-in dashboard playground.

Request

The working API base URL could not be loaded. Refresh the page before copying a request example.

Illustrative 200 response

Envelope only; not live data
{
  "data": {},
  "meta": {
    "feed": "scores",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 30,
    "qualification": "sample_received"
  }
}

Illustrative error body

{
  "code": "invalid_parameter",
  "error": "Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.",
  "requestId": "example-request-id"
}

Complete football endpoint reference

Every endpoint below includes its request parameters and documented response contract in the initial HTML. Open a section without JavaScript. Examples illustrate the contract, not live match records; current account permissions and service availability still apply.

GETScores and results/api/v1/football/scores

Scores and results

Scores and results. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/scores" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "scores",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 30,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETNew scores service/api/v1/football/scores-new

New scores service

The newer score service returns matches grouped by competition. JSON responses have been verified. Starter responses contain only your saved leagues; Growth and Pro receive the available package competitions. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/scores-new" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "scores-new",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 30,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETCurrently live matches/api/v1/football/live

Currently live matches

Returns currently live matches through the REST API; an empty match list can be valid when no covered matches are in play. Starter responses are filtered to saved leagues. This endpoint is separate from WebSocket streaming and ball tracking, which require their own activation and any applicable IP approval. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/live" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "live",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 15,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETRecent results/api/v1/football/recent-results

Recent results

Recent results. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
offset
queryrequired
string
1234567
A whole number from 1 to 7. For recent-results and highlights this is days before today; for upcoming it is days after today. Omit it for today's highlights.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/recent-results" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "offset=YOUR_OFFSET"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "recent-results",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 300,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETUpcoming matches/api/v1/football/upcoming

Upcoming matches

Upcoming matches. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
offset
queryrequired
string
1234567
A whole number from 1 to 7. For recent-results and highlights this is days before today; for upcoming it is days after today. Omit it for today's highlights.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/upcoming" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "offset=YOUR_OFFSET"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "upcoming",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 300,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETCompetition identifiers/api/v1/football/competitions

Competition identifiers

Start here to discover competition identifiers before requesting fixtures, squads, standings or leaderboards. Preserve IDs as strings and use the returned competition ID as leagueId in those endpoints. Consult the season catalogue before requesting historical data. Match, fixture and in-play IDs are not competition IDs. A listed competition does not guarantee that every feed or season is covered. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/competitions" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "competitions",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETSeason catalogue/api/v1/football/seasons

Season catalogue

Discover available seasons before requesting historical fixtures or standings. A listed season does not guarantee that every historical field is populated. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/seasons" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "seasons",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETSeason fixtures/api/v1/football/fixtures

Season fixtures

Season fixtures. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/fixtures" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "fixtures",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 900,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETHistorical fixtures and results/api/v1/football/historical-fixtures

Historical fixtures and results

Historical fixtures and results. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.
season
queryrequired
string
pattern ^\d{4}-\d{4}$
Two consecutive four-digit years separated by a hyphen, for example 2026-2027. Discover available seasons in the season catalogue; historical coverage varies.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/historical-fixtures" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID" \
  --data-urlencode "season=YOUR_SEASON"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "historical-fixtures",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETTeam abbreviations/api/v1/football/abbreviations

Team abbreviations

Team short codes are available as JSON under data.teams.team. IDs and source attributes are preserved as strings with @-prefixed attribute names. This global directory requires Growth or Pro and is not included in Starter. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/abbreviations" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "abbreviations",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETCompetition squads/api/v1/football/squads

Competition squads

Competition squads. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/squads" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "squads",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETCompetition match statistics/api/v1/football/match-statistics

Competition match statistics

Competition match statistics. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/match-statistics" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "match-statistics",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 60,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETHistorical match statistics/api/v1/football/historical-statistics

Historical match statistics

Populated by-date samples returned for commentary league 1204 on 15.08.2025 and 16.08.2025, including team/player statistics. Use a commentary league identifier and dd.MM.yyyy date with known completed fixtures. The provider's 21.09.2018 example returned a match dated 22.09.2018: exact date semantics and archive coverage still require provider confirmation. Samples do not establish customer entitlement or licensing. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.
date
queryrequired
string
pattern ^\d{2}\.\d{2}\.\d{4}$
A valid calendar date in dd.MM.yyyy format, for example 30.10.2026. ISO dates such as 2026-10-30 are not accepted.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/historical-statistics" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID" \
  --data-urlencode "date=YOUR_DATE"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "historical-statistics",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETSingle-match statistics/api/v1/football/match

Single-match statistics

Use the match static_id as id and the corresponding commentary league identifier as league. Ordinary match IDs, fixture IDs and in-play IDs are not interchangeable. Check this operation's qualification before relying on it. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
id
queryrequired
string
pattern ^[1-9]\d{0,11}$
The match static_id returned by the score/statistics feed, not its ordinary id or an in-play identifier.
league
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/match" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "id=YOUR_ID" \
  --data-urlencode "league=YOUR_LEAGUE"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "match",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 60,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETPredicted team line-ups/api/v1/football/predicted-lineups

Predicted team line-ups

Predicted team line-ups. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/predicted-lineups" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "predicted-lineups",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 300,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETInjuries/api/v1/football/injuries

Injuries

Injuries. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/injuries" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "injuries",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 900,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETCurrent standings/api/v1/football/standings

Current standings

Current standings. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/standings" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "standings",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 900,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETHistorical standings/api/v1/football/historical-standings

Historical standings

Historical standings. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.
season
queryrequired
string
pattern ^\d{4}-\d{4}$
Two consecutive four-digit years separated by a hyphen, for example 2026-2027. Discover available seasons in the season catalogue; historical coverage varies.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/historical-standings" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID" \
  --data-urlencode "season=YOUR_SEASON"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "historical-standings",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETTop scorers/api/v1/football/scorers

Top scorers

Top scorers. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/scorers" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "scorers",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 900,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETAssist leaders/api/v1/football/assists

Assist leaders

Assist leaders. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/assists" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "assists",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 900,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETCards leaders/api/v1/football/cards

Cards leaders

Cards leaders. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. Starter is limited to your saved account leagues; scores are filtered server-side and league-addressed responses must match a selected league.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
leagueId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/cards" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "leagueId=YOUR_LEAGUEID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "cards",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 900,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETTeam profile/api/v1/football/team

Team profile

Team profile. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
teamId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/team" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "teamId=YOUR_TEAMID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "team",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETPlayer profile/api/v1/football/player

Player profile

Player profile. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
playerId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/player" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "playerId=YOUR_PLAYERID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "player",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETUpdated team identifiers/api/v1/football/updated-teams

Updated team identifiers

Updated team identifiers. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/updated-teams" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "updated-teams",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETUpdated player identifiers/api/v1/football/updated-players

Updated player identifiers

Updated player identifiers. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/updated-players" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "updated-players",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETHead-to-head history/api/v1/football/head-to-head

Head-to-head history

Head-to-head history. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
team1Id
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.
team2Id
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/head-to-head" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "team1Id=YOUR_TEAM1ID" \
  --data-urlencode "team2Id=YOUR_TEAM2ID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "head-to-head",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETIn-play identifier mapping/api/v1/football/inplay-mapping

In-play identifier mapping

Use this mapping to connect the relevant fixture and in-play identifier systems. Do not assume match IDs from different services are identical. Access to a mapping does not enable the separate in-play service. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

No parameters.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/inplay-mapping" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "inplay-mapping",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 300,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETTeam crests/api/v1/football/team-images

Team crests

Team crests. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
teamId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/team-images" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "teamId=YOUR_TEAMID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "team-images",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}
GETPlayer portraits/api/v1/football/player-images

Player portraits

Player portraits. Provider-compatible football data; availability varies by competition, date and account entitlement. A provider sample has been received. This does not certify live freshness, full coverage or redistribution rights. Customer feeds require an explicit entitlement and a separately enabled endpoint. This service is not included in Starter. It requires Growth or Pro and separate service activation.

Authentication and parameters

Send your private key in the X-API-Key header or the documented bearer scheme from your server. Never embed the private key in a public page.

NameType and rulesDescription
playerId
queryrequired
string
pattern ^[1-9]\d{0,11}$
A positive numeric provider identifier, sent as a string. Obtain it from the relevant directory, fixture, team or player feed; identifiers from different systems are not interchangeable.

Example request

Set FOOTBALLAPI_KEY in your server environment. Replace illustrative identifiers with IDs returned by your permitted feeds.

curl --fail-with-body --get "https://footballapi.net/api/v1/football/player-images" \
  --header "X-API-Key: ${FOOTBALLAPI_KEY}" \
  --data-urlencode "playerId=YOUR_PLAYERID"

Documented responses

200
A provider-compatible JSON envelope. The example shows the envelope only, not actual competition or match records. Empty collections are possible and do not prove that a competition is unsupported.
400
Invalid query parameters, a missing required value or an invalid date range. Correct the request before retrying.
401
The FootballAPI.net key is missing, invalid, rotated or revoked. Use a current customer key, not a provider credential.
403
The key is recognised, but the account has no active entitlement or permission for this feed.
404
The requested football resource or image is unavailable.
429
The account safety request rate has been exceeded, or a manual account without metered billing has exhausted its daily allowance. Paid metered requests continue at €0.002 per additional successful request. Observe Retry-After.
502
The provider returned an invalid, rejected, empty or oversized response. Retry cautiously; synthetic records are not substituted.
503
The endpoint is disabled, not yet qualified or otherwise not ready. Repeated requests will not activate it.
504
The provider request timed out. Retry with backoff rather than issuing concurrent requests.

Success format: application/json

Illustrative example — not live data
{
  "data": {},
  "meta": {
    "feed": "player-images",
    "fetchedAt": "2026-10-30T12:00:00.000Z",
    "ttlSeconds": 3600,
    "qualification": "sample_received"
  }
}
Response schema
{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "required": [
        "feed",
        "fetchedAt"
      ],
      "properties": {
        "feed": {
          "type": "string"
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        },
        "ttlSeconds": {
          "type": "integer"
        },
        "qualification": {
          "type": "string",
          "enum": [
            "sample_received",
            "pending",
            "blocked"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Provider timezone caveat. fetchedAt is UTC; unzoned provider match dates are not necessarily UTC."
        }
      }
    }
  }
}