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.
- Plain JSON over HTTPS with a bearer API key. No SDK required.
- Machine-readable spec: https://www.kiddinglab.com/openapi-organizer.json (OpenAPI 3.1).
- Base URL:
https://www.kiddinglab.com/api/v1/organizer
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
| Method | Path | What it does |
|---|---|---|
GET | /me | The key, its scope and every camp it may write, with each camp's listing source and last push time. |
GET | /camps/{camp_id}/sessions | Read 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/batch | Create, update, adopt or cancel up to 200 sessions in one request. Supports dry_run, replace and adopt. |
PUT | /camps/{camp_id}/listing-source | Switch 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.
| Field | Type | Notes |
|---|---|---|
external_id | string, required | Your stable id for the session (1–120 chars, no "|"). Identity across pushes; stored as api:<external_id>. |
name | string, required | 1–200 chars. Shown to parents as the session title. |
description | string | null | Free text. |
dates | string[] (ISO dates) | null | Every day the session meets, 1–366 dates. Required unless date_range is given. |
date_range | {start, end, exclude?: string[]} | null | Shorthand for dates: every day from start to end inclusive, minus exclude. Expanded before storage. |
ages | integer[] (0–19) | null | Ages served. Absent or null = cleared. age_range {min, max} is accepted as shorthand. |
grades | integer[] (-2–12) | null | Grades 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" | null | Daily start and end, 24-hour clock. |
price_min / price_max | number ≥ 0 | null | US dollars. If min > max they are swapped with a warning. |
price_per | string | null | What the price covers, e.g. "week", "day", "session". |
reg_opens / reg_closes | ISO date | null | Registration 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_virtual | boolean | null | Online program. |
registration_url | https:// URL | null | Where 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} | null | Where the session meets. Omit for virtual sessions or when the camp address applies. |
before_care | {available?, start_time?, additional_cost?, blackout_dates?} | null | Before-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?} | null | After-care option, same shape with end_time. |
combined_care_cost | number ≥ 0 | null | Price when before and after care are bought together. |
care_notes | string | null | Anything parents should know about extended care. |
adopt_sess_id | integer | 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
addresskey, andbefore_care/after_careappear only when at least one care detail is set. statusis one of the five push values, ornullfor 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_reasonandupdated_at, fill inexternal_idwhere it is null, and the batch reports every row asunchanged.
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: truevalidates and reports what would happen without writing anything. Allowed even before the camp is switched to the API. Inserted rows come back withsess_id: null.replace: truetreats 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 withmass_deactivation_blocked; re-send withconfirm_mass_deactivation: trueif you meant it.adopt: false(defaulttrue) turns off adoption for the whole batch: anexternal_idkiddinglab has not seen always inserts a new session, even if a scraped twin exists. Per item,adopt_sess_idnames the exact row to adopt instead. See Adoption below.Idempotency-Keyheader (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 withreplayed: trueand writes nothing; the same key with a different body is refused with409 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_idset 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 withinvalid_inputanddetails.field = "adopt_sess_id". - You can also use
adopt_sess_idup front, for example after readingGET …/sessionsand mapping each scraped row to your own id. - Set
adopt: falseon the batch to skip the probe entirely; every unknownexternal_idthen 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 usereplace: trueand 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" }
]
}
}| Code | HTTP | When |
|---|---|---|
invalid_input | 422 | A field failed validation. issues[] lists each path and message; details carries {external_id, field, reason} for a session. |
unknown_reg_status | 422 | status is not one of the five allowed values. |
unauthorized | 401 | Missing or malformed bearer token, wrong key, or the key is expired or revoked. error.details.reason says which: unauthorized, expired, revoked or claim_required. |
forbidden | 403 | The key is valid but the camp is outside its scope, or your claim on it is no longer approved. |
dmca_blocked | 403 | The camp is blocked from listing changes. Contact support. |
not_found | 404 | No such camp, or the camp is no longer listed. |
conflict | 409 | A 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_api | 409 | A real (non-dry-run) push to a camp still fed by the scraper. details.hint tells you how to switch. |
ambiguous_match | 409 | A new external_id matched two or more existing scraped sessions. details.candidates lists them; pick one with adopt_sess_id (see Adoption below). |
idempotency_mismatch | 409 | The 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_blocked | 409 | replace: 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_source | 409 | An unsupported listing source. |
rate_limited | 429 | Too many requests. Wait for Retry-After seconds. |
unavailable | 503 | The 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_limitedwith aRetry-Afterheader. - 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.