Logbook API

Introduction

The PingDX API lets a member keep their PingDX logbook in sync with another logging program, a script or their own website: download QSOs, add new ones, correct or delete them. It only gives access to the logbook of the member who created the key.

Requests and responses are JSON (UTF-8). Send Content-Type: application/json with every request that has a body. Dates are ISO 8601 strings; the server always answers in UTC (2026-10-05T18:42:00.000Z).

A machine-readable description (OpenAPI 3.1, public, no key needed) is available for code generators and tools such as Postman: https://pingdx.org/api/v1/openapi.json

Getting a key

Every member creates their own keys in Profile → API access. Give each key a name (the program or site that uses it) and choose its rights:

• Read only (READ): can read the logbook (GET requests) — enough to display your QSOs on a website.
• Read and write (WRITE): can also create, update and delete QSOs — needed for a two-way sync with a logging program.
• The full key is shown only once, right after creation: copy it straight away. PingDX only keeps a fingerprint of it and can't show it again.
• You can revoke a key at any time: it stops working immediately. At most 10 active keys per member.

Authentication

Send the key with every request, in the Authorization header (Bearer) or in the X-API-Key header. Your PingDX login session is not accepted by this API, and cookies are never used.

Authorization: Bearer pdx_…
# or
X-API-Key: pdx_…

Without a valid key the API answers 401; a READ key trying to write gets 403:

• 401 API_KEYS.INVALIDMissing, unknown or revoked key (or account no longer active).
• 403 API_KEYS.READ_ONLYThe key is read-only: create a WRITE key to write.

Endpoints

All paths are relative to the base URL. Each QSO is identified by its clientId, a UUID chosen by your program.

{
  "callsign": "14KM001",
  "locator": "JN03ql",
  "scope": "WRITE"
}

{
  "items": [
    {
      "id": "cmgd4w1x70003s60e8k2v9qhz",
      "clientId": "0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f",
      "band": "ELEVEN_METERS",
      "frequencyMhz": "27.555",
      "channel": null,
      "ctcssTone": null,
      "dcsCode": null,
      "mode": "USB",
      "callsignWorked": "14KM123",
      "operatorCallsign": "14KM001",
      "dxLocator": "JN18du",
      "dxLat": null,
      "dxLng": null,
      "txPowerW": 4,
      "myLocator": "JN03ql",
      "splitKhz": null,
      "path": null,
      "qsoStatus": null,
      "rstSent": "59",
      "rstReceived": "57",
      "qslSent": false,
      "qslReceived": false,
      "qslVia": null,
      "qsoAt": "2026-10-05T18:42:00.000Z",
      "notes": null,
      "radio": "President Lincoln II+",
      "antenna": "Sirio 827",
      "crossConfirmedAt": null,
      "spottedAt": null,
      "createdAt": "2026-10-05T18:43:10.512Z",
      "syncedAt": "2026-10-05T18:43:10.512Z"
    }
  ],
  "nextCursor": null,
  "serverTime": "2026-10-05T18:45:12.345Z"
}

{
  "items": [
    { "id": "cmgd4w1x70003s60e8k2v9qhz", "clientId": "0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f" },
    { "id": "cmgd51b2c0007s60efq3m1abc", "clientId": "7d1f2a90-3b4c-4e5f-8a6b-9c0d1e2f3a4b" }
  ]
}

{
  "entries": [
    {
      "clientId": "0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f",
      "band": "ELEVEN_METERS",
      "frequencyMhz": "27.555",
      "mode": "USB",
      "callsignWorked": "14KM123",
      "qsoAt": "2026-10-05T18:42:00Z",
      "rstSent": "59",
      "rstReceived": "57",
      "dxLocator": "JN18DU"
    },
    {
      "clientId": "7d1f2a90-3b4c-4e5f-8a6b-9c0d1e2f3a4b",
      "band": "PMR446",
      "channel": 8,
      "ctcssTone": "67.0",
      "mode": "FM",
      "callsignWorked": "PMR-ALPHA",
      "qsoAt": "2026-10-05T19:05:00+02:00",
      "dxLocator": "JN1"
    }
  ]
}

{
  "results": [
    { "clientId": "0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f", "id": "cmgd4w1x70003s60e8k2v9qhz", "spottedAt": null },
    { "clientId": "7d1f2a90-3b4c-4e5f-8a6b-9c0d1e2f3a4b", "id": null, "error": "LOCATOR_INVALID", "permanent": true }
  ]
}

HTTP/1.1 204 No Content

The QSO object

The same object is sent to POST /logs/batch and returned by GET /logs. The band field selects one of two variants:

• 11 m (CB) — "band": "ELEVEN_METERS": frequencyMhz (optional); channel, ctcssTone and dcsCode must be absent or null.
• PMR446 — "band": "PMR446": channel (1 to 16) is required, ctcssTone / dcsCode optional; frequencyMhz must be absent or null.
• An update replaces the QSO: always send the complete QSO. An omitted field is reset (empty, or false for qslSent / qslReceived), except operatorCallsign, dxLat, dxLng, txPowerW, radio and antenna, which keep their stored value when omitted.
• Text is trimmed, locators are normalised (jn18DU → JN18du) and unknown fields are ignored. Read-only fields are set by the server: there's no need to send them.

• clientIdrequired
  string (UUID)

  Your stable id for this QSO: a random UUID (e.g. crypto.randomUUID()), generated once and stored with the QSO in your program. It is the sync key.

• bandrequired
  "ELEVEN_METERS" | "PMR446"

  The band: ELEVEN_METERS (11 m / CB) or PMR446.

• qsoAtrequired
  string (ISO 8601)

  Date and time of the QSO, ISO 8601 with time zone (Z or +02:00). Stored and returned in UTC.

• frequencyMhzoptional
  string "27.555" · 26.000–28.000

  11 m only: the frequency in MHz, as a string with exactly 3 decimals, between 26.000 and 28.000.

• channelrequired on PMR446
  integer 1–16

  PMR446 only (required there): the channel, 1 to 16.

• ctcssToneoptional
  string "67.0" · ^\d{2,3}\.\d$

  PMR446 only: CTCSS tone in Hz, one decimal (67.0, 103.5).

• dcsCodeoptional
  string "D023N" · ^D?[0-7]{3}[NI]?$

  PMR446 only: DCS code, 3 octal digits with optional D prefix and N / I polarity (D023N).

• modeoptional
  "FM" | "AM" | "SSB" | "USB" | "LSB" | "CW" | "DIGITAL"

  The mode.

• callsignWorkedoptional
  string ≤ 20

  The callsign of the station worked.

• operatorCallsignoptional
  string ≤ 20

  Your own callsign for this QSO (useful if you use several). Kept when omitted on an update.

• dxLocatoroptional
  string "JN18" | "JN18du"

  Maidenhead locator of the station worked, 4 or 6 characters.

• dxLatoptional
  number −90…90

  Exact latitude of the station worked, if known. Maps prefer it over the locator.

• dxLngoptional
  number −180…180

  Exact longitude of the station worked, if known.

• txPowerWoptional
  integer 0–100000

  Your transmit power in whole watts.

• myLocatoroptional
  string "JN03" | "JN03ql"

  Your locator for this QSO (e.g. when portable), 4 or 6 characters.

• splitKhzoptional
  integer −99999…99999

  Split in kHz (difference between transmit and receive frequencies).

• pathoptional
  "SP" | "LP"

  Propagation path: short path (SP) or long path (LP).

• qsoStatusoptional
  "HRD" | "WKD" | "CFM"

  Contact status: heard (HRD), worked (WKD), confirmed (CFM).

• rstSentoptional
  string ≤ 10

  Report sent (e.g. 59).

• rstReceivedoptional
  string ≤ 10

  Report received.

• qslSentoptional
  boolean (false)

  QSL card sent. Default: false.

• qslReceivedoptional
  boolean (false)

  QSL card received. Default: false.

• qslViaoptional
  "DIRECT" | "BUREAU" | "EQSL" | "ECARD"

  How the QSL travelled: DIRECT (mail), BUREAU, EQSL (eQSL.cc) or ECARD (other electronic card).

• notesoptional
  string ≤ 2000

  Free notes.

• radiooptional
  string ≤ 80

  The radio used (free text).

• antennaoptional
  string ≤ 80

  The antenna used (free text).

• sendSpotoptional
  boolean

  Write only, never returned: true also publishes the QSO as a spot on the PingDX DX cluster (once per QSO). Only for live QSOs, never for imports of old ones.

• idread-only
  string

  The server id of the QSO.

• crossConfirmedAtread-only
  string (ISO 8601) | null

  Set by PingDX when the other station logged the same QSO on PingDX (cross-confirmation).

• spottedAtread-only
  string (ISO 8601) | null

  When the QSO was published as a cluster spot, or null.

• createdAtread-only
  string (ISO 8601)

  When the QSO was first saved on PingDX.

• syncedAtread-only
  string (ISO 8601)

  Last server-side write of the QSO (orders GET /logs).

Synchronisation guide

A robust two-way sync between your program and PingDX in six steps:

1. 1

   First full download

   Call GET /logs?limit=500 without updatedSince, then follow nextCursor until it is null. Keep the serverTime of the first page.

2. 2

   Incremental download

   Next time, call GET /logs?updatedSince=… with the saved serverTime, follow the pages the same way, then save the new serverTime (still from the first page) only once every page has been processed. Receiving a QSO twice is harmless: apply it by clientId.

3. 3

   Sending your QSOs

   Give each QSO of your program a UUID clientId once and for all, and store it. Send new or modified QSOs with POST /logs/batch, at most 200 per request. Sending the same QSO again is safe: it updates it instead of creating a duplicate.

4. 4

   Rejected QSOs

   Read every result: if id is null with permanent: true, show the QSO to the user for correction (error says why) instead of retrying. Without permanent, retry later.

5. 5

   Deletions

   To delete on PingDX: DELETE /logs/{clientId}. To find QSOs deleted on PingDX: GET /logs/ids, then remove from your copy every QSO whose clientId is no longer listed.

6. 6

   Conflicts

   The last write wins, per clientId: there is no merging field by field. The PingDX app picks up QSOs written through the API at its next sync (when it opens, or within a few seconds when online).

Errors and limits

Errors use the HTTP status code and a JSON body with a stable code (never a translated text):

{ "error": { "code": "API_KEYS.READ_ONLY" } }

• 400 VALIDATION.FAILED

  Invalid request: a bad parameter, a clientId that isn't a UUID, or a batch without valid entries array (1 to 200). details describes the problem.

• 401 API_KEYS.INVALID

  Missing, unknown or revoked key (or account no longer active).

• 403 API_KEYS.READ_ONLY

  The key is read-only: create a WRITE key to write.

• 404 GENERIC.NOT_FOUND

  No QSO with this clientId in your logbook.

• 429 GENERIC.RATE_LIMITED

  Too many requests: wait a little and try again.

• 500 GENERIC.INTERNAL_ERROR

  Server error: try again later.

Per-QSO rejection reasons

In POST /logs/batch, a rejected QSO has id: null and an error code:

• CLIENT_ID_INVALIDclientId is not a valid UUID.
• DATETIME_INVALIDqsoAt is not an ISO 8601 date-time with time zone.
• LOCATOR_INVALIDdxLocator or myLocator is not a 4- or 6-character Maidenhead locator.
• FREQUENCY_FORMAT_INVALIDfrequencyMhz must be a string with 3 decimals (27.555).
• FREQUENCY_OUT_OF_BAND_11MfrequencyMhz is outside 26.000–28.000 MHz.
• CHANNEL_OUT_OF_RANGEPMR446 channel outside 1–16.
• CTCSS_FORMAT_INVALIDctcssTone must look like 67.0.
• DCS_FORMAT_INVALIDdcsCode must look like D023N.
• CLIENT_ID_CONFLICTThis clientId already belongs to another member's QSO: generate a new UUID.

Other schema violations (missing field, unknown value in an enum, text too long…) return the validator's message in English, e.g. Invalid input: expected string, received undefined, also with permanent: true.

Limits

• 300 requests per minute per IP address, beyond that 429 (the Retry-After header says how long to wait). Group your QSOs in batches rather than sending them one by one.
• 200 QSOs at most per POST /logs/batch.
• 1 to 500 QSOs per page of GET /logs (200 by default).
• 10 active keys at most per member.

Calling from a browser (CORS)

/api/v1 accepts requests from any origin (CORS), without cookies or credentials. A web page can therefore call it directly — but only with a READ key, since the code of a public page is visible to everyone.

Examples

Replace pdx_… with your key. These examples are ready to copy; only the comments are in English.

curl

# Who am I? (checks the key)
curl -H "Authorization: Bearer pdx_…" https://pingdx.org/api/v1/me

# Everything changed since my last sync
curl -H "Authorization: Bearer pdx_…" \
  "https://pingdx.org/api/v1/logs?updatedSince=2026-10-01T00:00:00Z&limit=500"

# Create or update a QSO (WRITE key)
curl -X POST -H "Authorization: Bearer pdx_…" \
  -H "Content-Type: application/json" \
  https://pingdx.org/api/v1/logs/batch \
  -d '{"entries":[{"clientId":"0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f",
       "band":"ELEVEN_METERS","frequencyMhz":"27.555","mode":"USB",
       "callsignWorked":"14KM123","qsoAt":"2026-10-05T18:42:00Z",
       "rstSent":"59","rstReceived":"57"}]}'

# Delete it (no body, no Content-Type)
curl -X DELETE -H "Authorization: Bearer pdx_…" \
  https://pingdx.org/api/v1/logs/0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f

JavaScript (fetch)

Works in Node.js 18+ and Deno. Keep the key on the server side (environment variable).

const BASE = "https://pingdx.org/api/v1";
const KEY = process.env.PINGDX_API_KEY; // pdx_… — keep it server-side

async function call(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      ...(body ? { "Content-Type": "application/json" } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (res.status === 204) return null;
  const data = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${data.error?.code}`);
  return data;
}

// Full download, page by page
async function pullAll(updatedSince) {
  const qsos = [];
  let cursor = null;
  let since = null;
  do {
    const q = new URLSearchParams({ limit: "500" });
    if (updatedSince) q.set("updatedSince", updatedSince);
    if (cursor) q.set("cursor", cursor);
    const page = await call("GET", `/logs?${q}`);
    since ??= page.serverTime; // keep the FIRST page's serverTime
    qsos.push(...page.items);
    cursor = page.nextCursor;
  } while (cursor);
  return { qsos, nextUpdatedSince: since };
}

// Push local QSOs (create or update by clientId)
const { results } = await call("POST", "/logs/batch", {
  entries: [{
    clientId: crypto.randomUUID(), // store it with your QSO, reuse it forever
    band: "PMR446", channel: 8, ctcssTone: "67.0", mode: "FM",
    callsignWorked: "PMR-ALPHA", qsoAt: new Date().toISOString(),
  }],
});
for (const r of results) if (r.id === null) console.warn(r.clientId, r.error, r.permanent);

Python (requests)

import os, uuid, requests

BASE = "https://pingdx.org/api/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['PINGDX_API_KEY']}"  # pdx_…

def pull(updated_since=None):
    """Every QSO changed since updated_since (all of them if None)."""
    qsos, cursor, next_since = [], None, None
    while True:
        params = {"limit": 500}
        if updated_since:
            params["updatedSince"] = updated_since
        if cursor:
            params["cursor"] = cursor
        r = S.get(f"{BASE}/logs", params=params, timeout=30)
        r.raise_for_status()
        page = r.json()
        next_since = next_since or page["serverTime"]  # first page's serverTime
        qsos += page["items"]
        cursor = page["nextCursor"]
        if not cursor:
            return qsos, next_since

def push(entries):
    """Create or update up to 200 QSOs; returns the rejected ones."""
    r = S.post(f"{BASE}/logs/batch", json={"entries": entries}, timeout=30)
    r.raise_for_status()
    return [x for x in r.json()["results"] if x["id"] is None]

rejected = push([{
    "clientId": str(uuid.uuid4()),  # keep it with your QSO
    "band": "ELEVEN_METERS", "frequencyMhz": "27.555", "mode": "USB",
    "callsignWorked": "14KM123", "qsoAt": "2026-10-05T18:42:00Z",
}])

# Deleted on PingDX? Compare clientIds with your copy
server_ids = {x["clientId"] for x in S.get(f"{BASE}/logs/ids", timeout=30).json()["items"]}

A question or a program you'd like to connect? Write to us from the Contact page.