Skrivebeskyttet analytics-API

HTTP-API-et api.jonot.io/v1/* gir skrivebeskyttet tilgang til organisasjonens kølapp- og kødata. Du autentiserer med et bearer-token i stedet for å logge inn i Admin. Bruk API-et til å hente data til et datavarehus, et BI-verktøy eller et eget dashbord.

Advarsel

API-et er tilgjengelig fra Pro-abonnementet og oppover. Fanen for API-tokener på integrasjonssiden viser en oppgraderingsmelding på Starter.

Skaffe et token

1. Åpne admin.jonot.io/settings/integrations.
2. Klikk fanen API tokens.
3. Klikk Create token, gi det et navn (f.eks. «Power BI»), og bekreft.
4. Kopier tokenet umiddelbart — det vises bare én gang og kan ikke gjenopprettes. Hvis du mister det, fjern det og opprett et nytt.

Tokener har prefikset jot_ og utløper aldri av seg selv; fjern dem fra samme fane når de ikke lenger trengs.

Autentisering

Fare

Send tokenet bare i Authorization-hodet. Sett det aldri i en spørrestreng — spørrestrenger havner i tilgangslogger, proxy-logger, og nettleserhistorikk. Et token oppgitt via ?token=... avvises med 401.

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Status	Betydning
401	Token mangler, er feilformatert, ukjent, eller fjernet.
402	Gyldig token, men organisasjonen har ikke API-funksjonen aktivert.
429	Hastighetsgrensen overskredet — se Hastighetsgrenser nedenfor.
400	Ugyldige spørreparametere, eller et datointervall over 90 dager.

Endepunkter

GET /v1/queues

Returnerer organisasjonens steder og køer, ufiltrert og upaginert:

curl https://api.jonot.io/v1/queues \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "locations": [
    {
      "id": "loc_…",
      "name": "Downtown",
      "slug": "downtown",
      "queues": [
        {
          "id": "q_…",
          "name": "Main Queue",
          "slug": "main-queue",
          "status": "ACTIVE"
        }
      ]
    }
  ]
}

Bruk de returnerte id-verdiene til å filtrere /v1/tickets og CSV-eksporten etter queueId / locationId.

GET /v1/tickets

Paginert lesing av kølapper, avgrenset til organisasjonen din.

Parameter	Påkrevd	Gjentagbar	Merknader
from	ja	nei	ISO-8601, inkluderende nedre grense for createdAt.
to	ja	nei	ISO-8601, ekskluderende øvre grense. Maks 90 dagers spenn.
queueId	nei	ja	Gjenta parameteren for å filtrere flere køer.
locationId	nei	ja	Gjenta parameteren for å filtrere flere steder.
status	nei	ja	Én av WAITING, CALLED, COMPLETED, CANCELED, SKIPPED, NO_SHOW.
cursor	nei	nei	Ugjennomsiktig verdi fra forrige sides nextCursor.
limit	nei	nei	Standard 100, maks 500.

curl "https://api.jonot.io/v1/tickets?from=2026-06-01T00:00:00Z&to=2026-06-08T00:00:00Z&status=COMPLETED" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "items": [
    {
      "id": "tkt_…",
      "number": 42,
      "queueId": "q_…",
      "locationId": "loc_…",
      "status": "COMPLETED",
      "createdAt": "2026-06-01T09:14:02.000Z",
      "calledAt": "2026-06-01T09:20:11.000Z",
      "completedAt": "2026-06-01T09:24:47.000Z",
      "cancelledAt": null,
      "skippedAt": null,
      "noShowAt": null,
      "calledByDeviceSessionId": "dev_…"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQi…"
}

Radene inneholder aldri kølappens bearer-hash eller kundeinnlagt PII (navn, notater, gruppestørrelse) — bare id-er, status, og livssyklustidsstemplene.

Paginering: Hvis nextCursor ikke er null, sender du verdien som cursor i neste forespørsel med de samme from-, to- og filterverdiene. Når nextCursor er null, har du nådd slutten av intervallet.

GET /v1/exports/tickets.csv

Endepunktet bruker de samme filtrene som /v1/tickets: from og to er påkrevd, og queueId, locationId og status kan gjentas. Det bruker ikke cursor eller limit. Hele intervallet strømmes som ett CSV-svar uten grensen på 500 rader per side.

Kolonnerekkefølgen er stabil, men les kolonner etter overskriftsnavn i stedet for fast posisjon. Overskriftsraden er alltid til stede og samsvarer nøyaktig med denne listen:

id,number,queueId,locationId,status,createdAt,calledAt,completedAt,cancelledAt,skippedAt,noShowAt,calledByDeviceSessionId

curl "https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o tickets.csv

Svaret strømmes med Transfer-Encoding: chunked. En eksport for 90 dager med 100 000 rader trenger derfor ikke å lagres i minnet først. Send den direkte til en fil eller parser.

90-dagers intervallgrense

Hvert endepunkt som tar from/to avviser et spenn over 90 dager med 400. Hent data trinnvis (f.eks. ett kall per uke) hvis du trenger lengre historikk — kølappens livssyklustidsstempler (calledAt, completedAt, …) lar deg rekonstruere vente-/betjeningstider uten å hente de samme radene på nytt.

Hastighetsgrenser

60 forespørsler/minutt per token (ikke per IP — budsjettet følger tokenet). Hvert svar bærer:

X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1751328000000

Et 429 bærer i tillegg Retry-After (sekunder). Vent til den perioden er over før du prøver igjen; en planlagt synkronisering hvert par minutter holder seg komfortabelt under grensen.

Demoorganisasjoner

En demoorganisasjon bruker det samme API-et, men har en ekstra grense på 50 forespørsler per dag i tillegg til minuttgrensen. Det er nok til å teste en integrasjon ved å liste køer, hente noen kølapper og kjøre én CSV-eksport. Det er ikke nok til produksjonsbruk. Hvis du overskrider grensen, får du et 429-svar som forklarer at demokvoten er brukt opp:

{
  "error": "demo_quota_exceeded",
  "limit": 50,
  "resetAt": "2026-01-02T09:00:00.000Z"
}

CSV-eksporter fra demoer er merket, slik at de ikke kan forveksles med produksjonsdata. Filnavnet får prefikset demo-, svaret inneholder X-Jonot-Demo: 1, og CSV-filen får en ekstra demo-kolonne. Betalte eksporter får ingen ekstra kolonne eller header. Et betalt abonnement fjerner den daglige kvoten og merkingen.

Python + pandas

import requests
import pandas as pd

TOKEN = "jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE = "https://api.jonot.io/v1"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def fetch_tickets(frm: str, to: str) -> pd.DataFrame:
    rows = []
    cursor = None
    while True:
        params = {"from": frm, "to": to, "limit": 500}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(f"{BASE}/tickets", headers=HEADERS, params=params, timeout=30)
        res.raise_for_status()
        body = res.json()
        rows.extend(body["items"])
        cursor = body["nextCursor"]
        if not cursor:
            break
    return pd.DataFrame(rows)

df = fetch_tickets("2026-06-01T00:00:00Z", "2026-07-01T00:00:00Z")
df["waitSeconds"] = (
    pd.to_datetime(df["calledAt"]) - pd.to_datetime(df["createdAt"])
).dt.total_seconds()
print(df.groupby("queueId")["waitSeconds"].mean())

Eller les CSV-eksporten direkte — pandas håndterer det strømmede svaret transparent:

df = pd.read_csv(
    f"{BASE}/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z",
    storage_options={"Authorization": f"Bearer {TOKEN}"},
)

Power BI (Web-kobling)

1. I Power BI Desktop: Get Data → Web.
2. Velg Advanced, og bygg URL-en med datointervallet ditt, f.eks. https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z.
3. Under HTTP request header parameters, legg til et hode kalt Authorization med verdien Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
4. Klikk OK — Power BI oppdager CSV-en og åpner tabellforhåndsvisningen.
5. Klikk Load (eller Transform Data først hvis du vil sette kolonnetyper — createdAt/calledAt/osv. importeres som tekst; konverter dem til Date/Time i Power Query).
6. Sett en planlagt oppdatering i Power BI-tjenesten hvis du henter på en fast frekvens; hold intervallet komfortabelt under 90 dager per oppdatering.

Tips

Power BIs legitimasjonslager holder Authorization-hodet utenfor spørrestrengen og utenfor den synlige M-koden i den lagrede .pbix-filen, så dette er den anbefalte måten å autentisere fra Power BI på — bygg aldri tokenet inn i selve URL-en.