Getting Started With the Pickleball API in 5 Minutes

This guide takes you from a new Pickleball-API.com account to your first match-data response. You do not need an SDK or any previous API experience—just a terminal, an API key and a few minutes.

In this guide

Create your account
Copy your API key
Make your first request
Find matches in progress
Add live updates

Step 1 — Create your account

After registering, open the verification link sent to your email address. Your trial API key will not work with the production service until your email has been verified.

The trial includes both REST and WebSocket access, so you can test the complete service before choosing a plan.

Step 2 — Copy your API key

Your API key is available from the developer dashboard.

Keys begin with:

pbl_live_

The full secret is shown when the key is created or rotated. Copy it somewhere secure, such as an environment variable or secrets manager.

Do not put the key in public browser code, a mobile app bundle or a Git repository. Your backend should call Pickleball API and return only the data your frontend needs.

For the examples below, create two environment variables:

export PICKLEBALL_API_URL="https://pickleball-api.com"
export PICKLEBALL_API_KEY="pbl_live_YOUR_KEY"

Use the API base URL shown in the documentation.

Step 3 — Make your first request

Every REST request uses your API key as a Bearer token in the Authorization header.

Start by requesting a small list of matches:

curl -s "$PICKLEBALL_API_URL/v1/matches?limit=5" \
  -H "Authorization: Bearer $PICKLEBALL_API_KEY"

A successful response returns JSON in a consistent envelope:

{
  "data": [
    {
      "id": "match_...",
      "status": "in_progress"
    }
  ],
  "meta": {
    "request_id": "req_...",
    "server_time": "2026-05-18T14:30:00Z"
  }
}

The exact match fields will depend on the available data, but the overall response structure remains consistent.

Keep meta.request_id in your logs. It identifies the individual request and is useful if you ever need support.

Step 4 — Find live matches

To return only matches currently in progress, add live=true:

curl -s "$PICKLEBALL_API_URL/v1/matches?live=true" \
  -H "Authorization: Bearer $PICKLEBALL_API_KEY"

An empty data array does not necessarily mean anything is wrong—it may simply mean that no covered matches are live at that moment.

Once you have a match ID, request its latest scoreboard state:

curl -s "$PICKLEBALL_API_URL/v1/matches/MATCH_ID/state" \
  -H "Authorization: Bearer $PICKLEBALL_API_KEY"

The match state includes the current score and two especially useful fields:

data_status tells you whether the feed is live, delayed or stale.
resource_version increases when the match state changes, helping your app order updates correctly.

You can also retrieve:

GET /v1/matches/{id}
GET /v1/matches/{id}/games
GET /v1/matches/{id}/timeline

These provide match details, the game-by-game breakdown and the ordered scoring timeline.

The same request in JavaScript

Here is a small server-side JavaScript example:

const baseUrl = process.env.PICKLEBALL_API_URL;
const apiKey = process.env.PICKLEBALL_API_KEY;

if (!baseUrl || !apiKey) {
  throw new Error(
    "PICKLEBALL_API_URL and PICKLEBALL_API_KEY must be configured."
  );
}

const response = await fetch(`${baseUrl}/v1/matches?live=true`, {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    Accept: "application/json",
  },
});

const body = await response.json();

if (!response.ok) {
  console.error("API request failed:", {
    status: response.status,
    code: body.code,
    requestId: body.request_id,
  });

  process.exit(1);
}

console.log(body.data);

Run this code on your server rather than in a public webpage. That keeps the API key private and allows you to cache one response for all your users.

Step 5 — Add live updates

REST is a good starting point and works well for pages that can check an active match every 10–15 seconds.

When your product needs score changes to arrive automatically, use the Pro WebSocket feed.

A typical live integration works like this:

Use REST to find matches in progress.
Retrieve the complete state for the match you want to follow.
Open a WebSocket connection.
Subscribe to match.<match_id>.state.
Receive an initial snapshot.
Apply subsequent match.score updates.

You can also subscribe to:

matches.live

This topic follows matches currently in progress.

The WebSocket feed is best for live scoreboards, alerts and trading dashboards. REST remains useful for initial state, history and recovery if a live connection needs to resynchronise.

Read REST or WebSockets for Live Pickleball Data? for a fuller comparison.

What should you build next?

Once you can list matches and retrieve a scoreboard, you already have the basis of a useful product.

Good first projects include:

A page showing matches in progress
A live scoreboard for one match
An alert when a match begins or ends
A results and match-history page
A dashboard that records score changes

For more inspiration, read What Can You Build With a Pickleball API?.

Frequently asked questions

Do I need a payment card to try the API?

No. New verified accounts receive a 14-day Pro trial without entering card details.

How do I authenticate requests?

Send your API key as a Bearer token in the Authorization header:

Authorization: Bearer pbl_live_YOUR_KEY

Do not pass the permanent key in a query string.

What format does the API return?

REST responses use JSON. Successful responses contain a data value and a meta object with information such as the request ID and server time.

Why did the live-match request return no results?

There may be no covered matches in progress. Try the general matches endpoint, or repeat the live request during an event.

Should I begin with REST or WebSockets?

Begin with REST. It is the quickest way to understand the data and display your first match. Add WebSockets once you know which parts of your product need automatic live updates.

Create your free trial account or open the documentation.