Skip to main content

Organizer Listing API

If you run a camp and already keep your sessions in a registration system, a spreadsheet or a booking platform, the Organizer Listing API lets you push them to kiddinglab yourself. Your listing stays exactly as you publish it, updates land in minutes instead of waiting for our next crawl, and parents see the same registration links you give them.

1. Get an API key

Sign in to the provider dashboard and open Dashboard → API keys. You need an approved claim on the organization or camp first, and your organization must have accepted the current Provider Agreement (version 7 or later, which covers API keys in Section 24); the API keys page prompts you to review and sign it if it has not.

  • Give the key a label and pick its scope: an organization key covers every camp under that organization; a camp key covers one camp.
  • The key is shown once. Store it in a secrets manager or environment variable; kiddinglab keeps only a hash.
  • Keys look like klk_<12 hex>_<64 hex>. Up to 10 live keys per account; an optional expiry date can be set when you create one.
  • A key never grants more than your current approved claims. If a claim is withdrawn, every key that relied on it stops working immediately. Revoke a key from the same page at any time.

Send the key as a bearer token on every request: Authorization: Bearer klk_…. GET /me is the quickest way to confirm a key works and see which camps it covers.

curl "https://www.kiddinglab.com/api/v1/organizer/me" \
  -H "Authorization: Bearer klk_YOUR_KEY"

2. One feeder per camp

Each camp has exactly one listing source. By default kiddinglab's scraper reads your website. Once you switch a camp to API, the scraper stops for that camp and your pushes own the session list. Writes to a camp that is still on the scraper are refused with 409 listing_source_not_api, so nothing you push is quietly overwritten by a crawl.

Switch in either of two ways:

  • In the dashboard: open the camp, find the Listing source card and turn on the API switch.
  • Over the API, acknowledging that scraping stops:
curl -X PUT "https://www.kiddinglab.com/api/v1/organizer/camps/123/listing-source" \
  -H "Authorization: Bearer klk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"api","acknowledge_scraper_off":true}'

Dry runs work in any mode, so you can test a batch before switching. To go back to the scraper, use Resume scraping on the camp's Listing source card: sessions that came from the API are retired and the next crawl rebuilds the list from your website. Edits made in the dashboard to an API-managed session are overwritten by your next push; the dashboard marks those sessions with an API badge.

3. Endpoints

Organizer Listing API endpoints
MethodPathWhat it does
GET/meThe key, its scope and every camp it may write, with each camp's listing source and last push time.
GET/camps/{camp_id}/sessionsRead the camp's sessions in the same shape you push (plus sess_id, managed_by, is_active, updated_at). Query: include_inactive, since.
POST/camps/{camp_id}/sessions/batchCreate, update, adopt or cancel up to 200 sessions in one request. Supports dry_run, replace and adopt.
PUT/camps/{camp_id}/listing-sourceSwitch the camp to the API ({"source":"api","acknowledge_scraper_off":true}). Switching back to the scraper is done from the dashboard.
PATCH/camps/{camp_id}Update camp description, URLs, contact details and categories. Works whatever the listing source.

Paths are relative to https://www.kiddinglab.com/api/v1/organizer. Bodies and responses are JSON. Every response carries an X-Request-Id header; quote it when you contact support.

4. The Session object

One item in sessions[] describes one session completely. Pushes use full-replace semantics: a field you leave out is cleared on that session, so always send the whole record, not just what changed. Every field except external_id and name is optional and nullable: a JSON null means the same as leaving the field out.

Session object fields
FieldTypeNotes
external_idstring, requiredYour stable id for the session (1–120 chars, no "|"). Identity across pushes; stored as api:<external_id>.
namestring, required1–200 chars. Shown to parents as the session title.
descriptionstring | nullFree text.
datesstring[] (ISO dates) | nullEvery day the session meets, 1–366 dates. Required unless date_range is given.
date_range{start, end, exclude?: string[]} | nullShorthand for dates: every day from start to end inclusive, minus exclude. Expanded before storage.
agesinteger[] (0–19) | nullAges served. Absent or null = cleared. age_range {min, max} is accepted as shorthand.
gradesinteger[] (-2–12) | nullGrades served; -2 = pre-K 3, -1 = pre-K 4, 0 = K. Absent or null = cleared. grade_range {min, max} is accepted as shorthand.
start_time / end_time"HH:MM" | nullDaily start and end, 24-hour clock.
price_min / price_maxnumber ≥ 0 | nullUS dollars. If min > max they are swapped with a warning.
price_perstring | nullWhat the price covers, e.g. "week", "day", "session".
reg_opens / reg_closesISO date | nullRegistration window. reg_opens must not be after reg_closes.
status"open" | "waitlist" | "closed" | "not_yet_open" | "cancelled" | null"cancelled" deactivates the session and marks registration closed. GET may return null for a scraped session whose label is none of these.
is_virtualboolean | nullOnline program.
registration_urlhttps:// URL | nullWhere parents register. A host that differs from the camp's website produces a warning, not an error.
address{line_1, line_2?, city, state, zip} | nullWhere the session meets. Omit for virtual sessions or when the camp address applies.
before_care{available?, start_time?, additional_cost?, blackout_dates?} | nullBefore-care option. Every member is nullable; additional_cost in US dollars; blackout_dates as ISO dates.
after_care{available?, end_time?, additional_cost?, blackout_dates?} | nullAfter-care option, same shape with end_time.
combined_care_costnumber ≥ 0 | nullPrice when before and after care are bought together.
care_notesstring | nullAnything parents should know about extended care.
adopt_sess_idinteger | null (push only)Adopt exactly this existing session instead of probing for a match. It must be active, belong to this camp and not already be API-managed, else 422 invalid_input with field "adopt_sess_id". See Adoption.

Range shorthands

date_range, age_range and grade_range are conveniences: the API expands them into dates, ages and grades before anything is stored, and GET …/sessions always returns the expanded arrays. Send one form or the other per field, not both.

What you get back

GET /camps/{camp_id}/sessions returns each session in the same shape, plus sess_id, managed_by (api, scraper or dashboard), is_active, deactivation_reason and updated_at. external_id is null for sessions you have not pushed or adopted yet. Pass include_inactive=true to see retired sessions and since=<ISO timestamp> to fetch only recent changes.

  • Empty fields are omitted, not returned as null: a session with no address has no address key, and before_care / after_care appear only when at least one care detail is set.
  • status is one of the five push values, or null for a scraped session whose registration label does not map to one of them.
  • Round trip: a GET body posts back unchanged. Drop sess_id, managed_by, is_active, deactivation_reason and updated_at, fill in external_id where it is null, and the batch reports every row as unchanged.
curl "https://www.kiddinglab.com/api/v1/organizer/camps/123/sessions?include_inactive=false&since=2027-01-01T00:00:00Z" \
  -H "Authorization: Bearer klk_YOUR_KEY"

5. Pushing sessions

curl -X POST "https://www.kiddinglab.com/api/v1/organizer/camps/123/sessions/batch" \
  -H "Authorization: Bearer klk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "dry_run": true,
    "replace": false,
    "sessions": [
      {
        "external_id": "2027-wk1-explorers",
        "name": "Explorers Week 1",
        "date_range": { "start": "2027-06-21", "end": "2027-06-25" },
        "age_range": { "min": 6, "max": 9 },
        "start_time": "09:00",
        "end_time": "15:00",
        "price_min": 395,
        "price_per": "week",
        "status": "open",
        "registration_url": "https://example.org/register/wk1",
        "before_care": { "available": true, "start_time": "08:00", "additional_cost": 40 }
      }
    ]
  }'

Response:

{
  "ok": true,
  "op": "sessions_batch",
  "camp_id": 123,
  "dry_run": true,
  "summary": { "received": 1, "inserted": 1, "updated": 0, "unchanged": 0,
               "adopted": 0, "cancelled": 0, "deactivated": 0 },
  "results": [
    { "external_id": "2027-wk1-explorers", "sess_id": null, "action": "inserted", "warnings": [] }
  ],
  "deactivated": [],
  "warnings": []
}

sess_id is null for an inserted row in a dry run, since nothing was created; a real push returns the new id.

Options

  • dry_run: true validates and reports what would happen without writing anything. Allowed even before the camp is switched to the API. Inserted rows come back with sess_id: null.
  • replace: true treats the batch as the complete list: any API-managed session of this camp that is not in the batch is retired (removed_from_source). Sessions created by the scraper or in the dashboard are never touched. An empty batch never retires anything. If the sweep would retire more than 10 sessions and more than half of the camp's API-managed sessions, the request is refused with mass_deactivation_blocked; re-send with confirm_mass_deactivation: true if you meant it.
  • adopt: false (default true) turns off adoption for the whole batch: an external_id kiddinglab has not seen always inserts a new session, even if a scraped twin exists. Per item, adopt_sess_id names the exact row to adopt instead. See Adoption below.
  • Idempotency-Key header (optional, up to 128 characters): generate a fresh one per attempt (crypto.randomUUID(), uuidgen) and reuse it only to retry that exact request. The key is scoped to your API key, the operation and the camp, so the same value on a different camp or endpoint is simply a different key. A retry with the same key and the same body returns the stored result with replayed: true and writes nothing; the same key with a different body is refused with 409 idempotency_mismatch. Never reuse a per-day or per-run key across different payloads.
  • Up to 200 sessions per request; split larger catalogues into several batches.

Actions and identity

Each result row has an action: inserted, updated, unchanged, adopted or cancelled. Identity is your external_id; keep it stable from push to push (a database id or a slug, not the session name).

Adoption

When a camp switches to the API it usually already has sessions the scraper found. The first time you push an external_id kiddinglab has not seen, it looks for an existing session of this camp that is not yet API-managed and matches on either of two rules: its stored key equals the canonical key for your external_id, or its name, first date and daily start time all equal yours. If exactly one row matches it is adopted: the row keeps its id (and any parent saves or bookings), is updated to your data and becomes API-managed. If two or more rows match the push is refused with 409 ambiguous_match and details.candidates lists them with their sess_id.

  • To resolve an ambiguous match, re-send the item with adopt_sess_id set to the candidate you mean. That row is adopted and the probe is skipped. It must be active, belong to this camp and not already be API-managed, or the item fails with invalid_input and details.field = "adopt_sess_id".
  • You can also use adopt_sess_id up front, for example after reading GET …/sessions and mapping each scraped row to your own id.
  • Set adopt: false on the batch to skip the probe entirely; every unknown external_id then inserts a new row and the scraped twins stay until you retire them in the dashboard.

Cancelling and seasons

  • status: "cancelled" deactivates the session and marks registration closed. Keep sending it (or use replace: true and leave it out) so it stays retired.
  • A session whose dates are all in the past is stored inactive with reason season_ended; if a later push gives it future dates it is reactivated.
  • Warnings never fail a push. You will see one for a registration URL on a different host than the camp's website, a date range over 120 days, or a swapped price range.

6. Updating camp details

PATCH /camps/{camp_id} uses presence semantics: fields you omit are untouched and a JSON null clears a field. Allowed fields: camp_description, camp_home_url, camp_schedule_url, camp_contact_name, camp_contact_title, camp_contact_email, camp_contact_phone and category_ids (replaces the camp's categories). The camp name is not patchable; ask support if it needs to change. This works whatever the listing source.

curl -X PATCH "https://www.kiddinglab.com/api/v1/organizer/camps/123" \
  -H "Authorization: Bearer klk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"camp_contact_email":"camps@example.org","camp_schedule_url":"https://example.org/summer","category_ids":[3,17]}'

7. Errors

Every error is {"error":{"code","message","details?","issues?"}} with a matching HTTP status:

{
  "error": {
    "code": "invalid_input",
    "message": "1 field failed validation",
    "issues": [
      { "path": "sessions.0.dates", "message": "Expected 1–366 ISO dates" }
    ]
  }
}
Error codes and HTTP statuses
CodeHTTPWhen
invalid_input422A field failed validation. issues[] lists each path and message; details carries {external_id, field, reason} for a session.
unknown_reg_status422status is not one of the five allowed values.
unauthorized401Missing or malformed bearer token, wrong key, or the key is expired or revoked. error.details.reason says which: unauthorized, expired, revoked or claim_required.
forbidden403The key is valid but the camp is outside its scope, or your claim on it is no longer approved.
dmca_blocked403The camp is blocked from listing changes. Contact support.
not_found404No such camp, or the camp is no longer listed.
conflict409A scraper duplicate of this session could not be superseded; details.sess_id names it and details.reason is twin_has_bookings (it has bookings) or twin_predates_api_row (it is the older row). Deactivate or merge it in the dashboard, or push with adopt: false.
listing_source_not_api409A real (non-dry-run) push to a camp still fed by the scraper. details.hint tells you how to switch.
ambiguous_match409A new external_id matched two or more existing scraped sessions. details.candidates lists them; pick one with adopt_sess_id (see Adoption below).
idempotency_mismatch409The Idempotency-Key was already used for this key, operation and camp with a different payload. Send the new payload under a fresh key.
mass_deactivation_blocked409replace: true would retire more than 10 sessions and more than half of the camp's API-managed sessions. Re-send with confirm_mass_deactivation: true if that is intended.
invalid_source409An unsupported listing source.
rate_limited429Too many requests. Wait for Retry-After seconds.
unavailable503The API is switched off (kill switch), under maintenance, or hit an internal error (details.db_code for a database error). Retry later with the same idempotency key.

A 4xx other than 429 means the request will fail the same way if repeated unchanged; fix the input (for idempotency_mismatch, send the changed body under a new key). Retry only on 429 and 503: wait, then resend with the same idempotency key. There is no 500; internal errors surface as 503 unavailable.

8. Rate limits

  • 60 requests per minute per API key, across all endpoints.
  • 2,000 write requests per day per key (batch, listing-source and camp updates). Reads do not count.
  • Limits are also applied per IP address. Over the limit you get 429 rate_limited with a Retry-After header.
  • Request bodies are capped at 512 KB; keep batches at or below 200 sessions.

A nightly or hourly sync with replace: true is well inside these limits for any camp. If you need more, email us.

9. Code examples

Node (fetch)

const BASE = 'https://www.kiddinglab.com/api/v1/organizer';
const KEY = process.env.KIDDINGLAB_API_KEY; // klk_...

async function pushSessions(campId, sessions, { dryRun = false, replace = true } = {}) {
  // One key per attempt. Reuse it only to retry this exact body after a
  // timeout or a 429/503; a different body under the same key is refused
  // with 409 idempotency_mismatch.
  const idempotencyKey = crypto.randomUUID();
  const res = await fetch(`${BASE}/camps/${campId}/sessions/batch`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({ sessions, dry_run: dryRun, replace }),
  });
  const body = await res.json();
  if (!res.ok) {
    throw new Error(`${res.status} ${body.error?.code}: ${body.error?.message}`);
  }
  return body; // { ok, summary, results, deactivated, warnings }
}

const result = await pushSessions(123, [
  {
    external_id: '2027-wk1-explorers',
    name: 'Explorers Week 1',
    date_range: { start: '2027-06-21', end: '2027-06-25' },
    age_range: { min: 6, max: 9 },
    start_time: '09:00',
    end_time: '15:00',
    price_min: 395,
    price_per: 'week',
    status: 'open',
    registration_url: 'https://example.org/register/wk1',
  },
], { dryRun: true });
console.log(result.summary);

Python (requests)

import os
import uuid
import requests

BASE = "https://www.kiddinglab.com/api/v1/organizer"
KEY = os.environ["KIDDINGLAB_API_KEY"]  # klk_...
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def push_sessions(camp_id, sessions, dry_run=False, replace=True):
    # One key per attempt; reuse it only to retry this exact body.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post(
        f"{BASE}/camps/{camp_id}/sessions/batch",
        headers=headers,
        json={"sessions": sessions, "dry_run": dry_run, "replace": replace},
        timeout=60,
    )
    body = r.json()
    if not r.ok:
        err = body.get("error", {})
        raise RuntimeError(f"{r.status_code} {err.get('code')}: {err.get('message')}")
    return body

result = push_sessions(123, [
    {
        "external_id": "2027-wk1-explorers",
        "name": "Explorers Week 1",
        "date_range": {"start": "2027-06-21", "end": "2027-06-25"},
        "age_range": {"min": 6, "max": 9},
        "start_time": "09:00",
        "end_time": "15:00",
        "price_min": 395,
        "price_per": "week",
        "status": "open",
        "registration_url": "https://example.org/register/wk1",
    }
], dry_run=True)
print(result["summary"])

For no-code tools such as Zapier or Make, use their generic HTTP/webhook action with the bearer header and the JSON bodies above, or import the OpenAPI document.

Privacy and scope

This API writes and reads your own camp listings only. It never returns information about parents, children or bookings. Each request is logged against your key (operation, status and a summary) and shown on the camp's Listing source card in the dashboard. See our Privacy Policy, Terms of Service and Provider Agreement. Building an assistant for parents instead? See kiddinglab for AI assistants.

Contact

Questions, a platform you would like us to integrate with, or a key you need rotated in a hurry: email support@kiddinglab.com.