Make your first FootballAPI.net request
Create an account, activate the right football plan, keep your API key server-side and make a first authenticated scores request with cURL or PHP.
Step 1: Account
Choose a plan and activate access
Step 2: Private key
Create a customer API key
Step 3: Server request
Send the key in a header
Step 4: Your website
Render your saved response
Start with an account and an activated plan
Create your FootballAPI.net account and review pricing before collecting data. Registration alone does not activate a feed or start a trial. Starter offers a seven-day trial after completed checkout with a card; it covers five selected leagues and caps successful requests at 5,000 per UTC day. Save your Starter league selection in Dashboard → Settings before making requests. Growth and Pro include all available package leagues.
Create a customer REST key in Dashboard → API keys and save it in your server's secret manager as FOOTBALLAPI_KEY. This guide uses scores because it is in Starter's league-scoped service set as well as Growth and Pro. The global competition directory, standalone profiles and image lookups require Growth or Pro. Widget installation keys cannot replace REST keys.
Try your first scores request from your server
Set FOOTBALLAPI_KEY on your server, then run this Bash command. It uses no query parameters and Starter receives only its saved leagues. A successful empty collection can simply mean no relevant fixtures are present in this snapshot; it is not an authentication failure.
Send credentials through Authorization: Bearer or X-API-Key. Never put a key into a query string, browser script, public repository or image URL. The 60-second timeout leaves room for bounded recovery on a cold source read; it is not a promised response time. Your visitors should read your own saved response rather than waiting on a fresh external request.
curl --fail-with-body --max-time 60 \
'https://footballapi.net/api/v1/football/scores' \
-H "Authorization: Bearer ${FOOTBALLAPI_KEY:?Set FOOTBALLAPI_KEY on your server}" \
-H 'Accept: application/json'Make the same request in PHP
This server-side PHP example requires PHP 7.3 or newer and the cURL extension. Save it as scores.php and run php scores.php with FOOTBALLAPI_KEY available to that process. It checks the transport status and JSON before exposing football records to the rest of your application.
This snippet fetches and parses a response; it does not yet create a complete public scoreboard. In a production page, render only the fields you need and escape output using your template framework. Handle exceptions with a controlled error response, not a raw stack trace or a log of authentication headers.
<?php
$key = getenv('FOOTBALLAPI_KEY');
if (!$key) { throw new RuntimeException('Set FOOTBALLAPI_KEY'); }
$ch = curl_init('https://footballapi.net/api/v1/football/scores');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key, 'Accept: application/json'],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($body === false || $status !== 200) {
throw new RuntimeException('Football request failed: HTTP ' . $status);
}
$payload = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
$data = $payload['data'];
$meta = $payload['meta'];
echo json_encode(['data' => $data, 'meta' => $meta], JSON_PRETTY_PRINT);Inspect the envelope before building the page
The normal successful response separates data from meta. The scores feed contains competition categories inside data.scores; it is not a flat data.matches array. Some field names use an @ prefix. Repeated collections can be a single object or an array, so normalise the correct collection boundary before rendering.
Starter users can take selected league IDs from Dashboard → Settings and match/team IDs from permitted fixtures or squads. Growth and Pro users can also use the global competition directory. Follow the specific endpoint guide next; each one explains its plan access, parameters and required environment variables.
Turn the experiment into a safe application
Add a server timeout, a shared cache and a small request budget before you allow public traffic. A successful API request can count toward usage even when our server reuses its own cached response. Reusing your saved result is what prevents your application from making another customer API request.
Rotate a key immediately if it has been exposed and update the secret on every server that uses it. Do not try to solve a 401 response by repeatedly retrying the same invalid credential.
- Verify access in the signed-in playground.
- Discover IDs from actual directory and fixture records.
- Keep a fetched timestamp next to cached data.
- Handle empty, missing and failed responses separately.
Related tutorials
Getting started / 8 min
Understand football IDs and response shapes
Learn static fixture IDs, competition and stage mappings, object-or-array collections and null-safe normalisation for football API responses.
Endpoint tutorials / 6 min
Discover football competition identifiers
Build a competition selector using stable league IDs, separate stage mappings and season metadata, then reuse the directory throughout your integration.
Performance and operations / 12 min
Save requests with shared football API caches
Design server-side caching, request coalescing, prewarming and usage budgets so football pages load quickly without unnecessary API calls.
Performance and operations / 9 min
Diagnose API errors and missing football data
Handle authentication, entitlement, validation, rate limits, temporary failures and empty collections with bounded retries and useful diagnostics.