NTL Events API

Getting started

1. In the NTL Events dashboard, go to Security → API & webhooks. Only the account owner can create keys, and two-factor authentication must be on.
2. Choose the scopes the integration needs (read and write are separate) and, optionally, an expiration. Copy the key: it is shown once.
3. Send it as a bearer token on every request.

curl https://ntl.events/api/v1/events \
  -H "Authorization: Bearer ntl_live_…"

curl https://ntl.events/api/v1/registrations \
  -H "Authorization: Bearer ntl_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2027-000123" \
  -d '{
    "event_id": "8c3f…",
    "registration_type_id": "1f0a…",
    "buyer": { "name": "Ingrid Halvorsen", "email": "ingrid@example.org" },
    "answers": { "organization": "Norwegian Defence Research Establishment" }
  }'

Authentication and scopes

Send Authorization: Bearer ntl_live_… (or X-API-Key). A missing, invalid, expired or revoked key returns 401; a key without the required scope returns 403. Keys are stored as a SHA-256 hash: we cannot recover a lost key, only revoke it and create another.

Pagination

Lists return { object: "list", data, has_more, next_cursor }, newest first. Pass next_cursor as starting_after to get the next page. limit goes from 1 to 100 (default 25). Cursors are stable even if new records arrive while you page.

curl "https://ntl.events/api/v1/registrations?event_id=8c3f…&limit=100&starting_after=eyJ0Ijoi…" \
  -H "Authorization: Bearer ntl_live_…"

Errors

Every error has the same shape. type is the stable family to program against; code is the specific case; request_id helps our support team find the request.

HTTP/1.1 409 Conflict
{
  "error": {
    "type": "conflict_error",
    "code": "sold_out",
    "message": "Not enough capacity left in this registration type.",
    "request_id": "req_3f9c…"
  }
}

Rate limits

Each key allows 120 requests per minute by default. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 includes Retry-After.

Idempotency

Send an Idempotency-Key header on POST requests. If the network fails and you retry with the same key, you get the original response (with Idempotent-Replayed: true) instead of a duplicate registration or check-in. Reusing a key with a different body returns 422. Keys are kept for 24 hours.

Amounts and dates. Amounts are integers in minor units (cents) with their ISO 4217 currency. Dates are ISO 8601 in UTC.

Webhooks

Register an HTTPS endpoint and the events you want in the dashboard. Each delivery is a signed POST with the same object the API returns for that resource. Respond 2xx within 10 seconds. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h — 8 attempts in total — and you can retry any delivery by hand from the dashboard.

Event types

• registration.created — Registration confirmed
• registration.cancelled — Registration cancelled or refunded
• payment.completed — Payment completed
• checkin.created — Check-in recorded
• abstract.decided — Abstract decided

Verifying the signature

NTL-Signature: t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(your whsec_ secret, "<t>.<raw body>"). Compare in constant time and reject if the timestamp is more than 5 minutes away from your clock. Use the raw body, before any JSON parsing.

// Node.js
import crypto from "node:crypto";

export function verifyNtlSignature(secret, header, rawBody, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"), "hex");
  const received = Buffer.from(parts.v1 ?? "", "hex");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

POST /your/endpoint
NTL-Signature: t=1789200000,v1=5f2b…
NTL-Event-Type: registration.created
NTL-Event-Id: evt_9a1c…

{
  "id": "evt_9a1c…",
  "object": "event",
  "type": "registration.created",
  "created": 1789200000,
  "data": { "object": { "id": "…", "object": "registration", "status": "confirmed", "attendees": [ … ] } }
}

API reference

The reference is in English and is generated from the same OpenAPI document the API serves.

Objects