{ "openapi": "3.1.0", "info": { "title": "RoundUp API", "version": "1.0.0", "description": "The RoundUp public API gives a center's own integrations read access to its roster, attendance, billing and incidents, lets them create enrollment inquiries, and delivers real-time events by webhook.\n\n**Authentication.** A director creates an API key in the director portal or the RoundUp app (Integrations → API keys), choosing its scopes. Send it as `Authorization: Bearer rk_live_…`. A key only ever sees its own center.\n\n**Rate limits.** 120 requests per minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 carries Retry-After.\n\n**Errors.** `{ \"error\": \"\", \"message\": \"…\" }` with codes invalid_api_key (401), insufficient_scope (403, plus `requiredScope`), not_found (404), invalid_request (400), rate_limited (429).\n\n**Versioning.** Breaking changes ship as a new version path (/v2); fields may be added to v1 responses at any time.\n\n**Webhooks.**\n\nEvery delivery is signed with the subscription's secret (whsec_…, shown once when the webhook is created):\n\n RoundUp-Signature: t=1759680000,v1=<64 hex characters>\n\nTo verify: take `t`, build the string `.`, compute HMAC-SHA256 of it with the secret, and compare it (constant-time) to `v1`. Reject the request when `t` is more than 300 seconds from your clock — that is what stops a captured request being replayed. Always verify against the raw bytes you received, before parsing the JSON.\n\nDeliveries also carry RoundUp-Event, RoundUp-Event-Id, RoundUp-Delivery-Id and RoundUp-Attempt. Delivery is at-least-once: dedupe on the event id. Answer with any 2xx within 10 seconds; anything else is retried after 1 min, 5 min, 30 min, 2 h, 5 h, 10 h and 24 h, then kept as a failed delivery a director can retry. Answer 410 Gone to unsubscribe. An endpoint that fails continuously for 3 days is turned off and the center's directors are notified.\n\nDeprecated: X-RoundUp-Signature (sha256=) and X-RoundUp-Event are still sent until 2027-01-31 for receivers built before timestamped signatures. Move to RoundUp-Signature.", "contact": { "name": "RoundUp developer support", "email": "developers@roundupece.com", "url": "https://roundupece.com/developers/" } }, "servers": [ { "url": "https://api.roundupece.com/api", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account", "description": "The key and its center" }, { "name": "Children" }, { "name": "Classrooms" }, { "name": "Attendance" }, { "name": "Billing" }, { "name": "Incidents" }, { "name": "Staff" }, { "name": "Enrollment" }, { "name": "Webhooks", "description": "REST-hook subscriptions (used by Zapier)" } ], "paths": { "/v1/me": { "get": { "operationId": "getMe", "summary": "The calling key and its center", "description": "Works with any valid key, whatever its scopes. Use it to test a connection.", "tags": [ "Account" ], "x-scope": null, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/center": { "get": { "operationId": "getCenter", "summary": "The key's center", "tags": [ "Account" ], "x-scope": "read:center", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Center" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/children": { "get": { "operationId": "listChildren", "summary": "List children", "tags": [ "Children" ], "x-scope": "read:children", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "WITHDRAWN" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Child" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/children/{id}": { "get": { "operationId": "getChild", "summary": "Get a child", "tags": [ "Children" ], "x-scope": "read:children", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "6-digit public id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Child" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Two children at the center share this id (rare); list /v1/children instead." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/classrooms": { "get": { "operationId": "listClassrooms", "summary": "List classrooms", "tags": [ "Classrooms" ], "x-scope": "read:classrooms", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Classroom" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/attendance": { "get": { "operationId": "listAttendance", "summary": "Attendance for one day", "tags": [ "Attendance" ], "x-scope": "read:attendance", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Defaults to today in the center's time zone." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttendanceDay" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices, newest first", "tags": [ "Billing" ], "x-scope": "read:billing", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "DRAFT", "OPEN", "PARTIAL", "PAID", "VOID" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get an invoice", "tags": [ "Billing" ], "x-scope": "read:billing", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/incidents": { "get": { "operationId": "listIncidents", "summary": "List incidents", "tags": [ "Incidents" ], "x-scope": "read:incidents", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/staff": { "get": { "operationId": "listStaff", "summary": "List staff", "tags": [ "Staff" ], "x-scope": "read:staff", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffMember" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/inquiries": { "post": { "operationId": "createInquiry", "summary": "Create an enrollment inquiry", "description": "Adds a prospective family to the center's waitlist and emails the guardian a confirmation — the same as the center's public inquiry form.", "tags": [ "Enrollment" ], "x-scope": "write:inquiries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InquiryInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "const": "WAITLISTED" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List the center's webhook subscriptions", "tags": [ "Webhooks" ], "x-scope": "write:webhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createWebhook", "summary": "Subscribe a URL to events (REST hook)", "description": "The response carries the signing secret, once. Subscriptions created here appear in the director's Webhooks screen.", "tags": [ "Webhooks" ], "x-scope": "write:webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "description": "https:// on a public host", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" }, "minItems": 1 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "whsec_… — verify RoundUp-Signature with it" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/webhooks/{id}": { "delete": { "operationId": "deleteWebhook", "summary": "Unsubscribe (REST hook)", "description": "Only subscriptions created through the API can be deleted with a key.", "tags": [ "Webhooks" ], "x-scope": "write:webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/events/sample": { "get": { "operationId": "sampleEvent", "summary": "An example event envelope for a type", "tags": [ "Webhooks" ], "x-scope": "write:webhooks", "parameters": [ { "name": "type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/EventType" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "webhooks": { "child.checked_in": { "post": { "summary": "child.checked_in", "description": "A child was checked in.", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "child.checked_in" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "child.checked_in" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "child.checked_in", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "childId": 482913, "at": "2026-10-05T15:02:11.000Z", "date": "2026-10-05" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "child.checked_out": { "post": { "summary": "child.checked_out", "description": "A child was checked out.", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "child.checked_out" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "child.checked_out" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "child.checked_out", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "childId": 482913, "at": "2026-10-05T23:31:40.000Z", "date": "2026-10-05" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "child.enrolled": { "post": { "summary": "child.enrolled", "description": "A child became actively enrolled (a new child, or a re-enrollment).", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "child.enrolled" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "child.enrolled" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "child.enrolled", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "childId": 482913, "classroom": "Sunflowers", "enrolledAt": "2026-10-05T16:00:00.000Z" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "child.withdrawn": { "post": { "summary": "child.withdrawn", "description": "An enrolled child was withdrawn.", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "child.withdrawn" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "child.withdrawn" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "child.withdrawn", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "childId": 482913, "exitReason": "MOVED", "exitDate": "2026-10-31", "withdrawnAt": "2026-10-05T16:00:00.000Z" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "invoice.created": { "post": { "summary": "invoice.created", "description": "An invoice was issued (draft or open).", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "invoice.created" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "invoice.created" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "invoice.created", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "invoiceId": "inv_3f0c7a1e", "familyId": "fam_8a21", "number": "INV-1042", "status": "OPEN", "amountDueCents": 125000, "dueDate": "2026-11-01", "createdAt": "2026-10-05T16:00:00.000Z" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "invoice.paid": { "post": { "summary": "invoice.paid", "description": "An invoice was paid in full, by any payment method.", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "invoice.paid" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "invoice.paid" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "invoice.paid", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "invoiceId": "inv_3f0c7a1e", "familyId": "fam_8a21", "number": "INV-1042", "amountDueCents": 125000, "amountPaidCents": 125000, "paidAt": "2026-10-06T09:12:00.000Z" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "invoice.payment_failed": { "post": { "summary": "invoice.payment_failed", "description": "A payment on an invoice failed: a declined autopay charge or a returned bank debit.", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "invoice.payment_failed" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "invoice.payment_failed" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "invoice.payment_failed", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "invoiceId": "inv_3f0c7a1e", "familyId": "fam_8a21", "number": "INV-1042", "amountCents": 125000, "methodType": "us_bank_account", "failureCode": "insufficient_funds", "failedAt": "2026-10-06T09:12:00.000Z" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "incident.created": { "post": { "summary": "incident.created", "description": "Staff logged an incident. Type, severity and dates only — never the description.", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "incident.created" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "incident.created" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "incident.created", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "incidentId": "inc_51b2", "childId": 482913, "type": "Injury", "severity": "Minor", "incidentDate": "2026-10-05", "createdAt": "2026-10-05T18:20:00.000Z" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "staff.hired": { "post": { "summary": "staff.hired", "description": "Someone was added to this center's staff.", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "staff.hired" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "staff.hired" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "staff.hired", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "staffId": 731045, "role": "TEACHER", "classroom": "Sunflowers", "hiredAt": "2026-10-05T16:00:00.000Z" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "staff.terminated": { "post": { "summary": "staff.terminated", "description": "Someone was removed from this center's staff (including a move to another center).", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "staff.terminated" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "staff.terminated" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "staff.terminated", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "staffId": 731045, "role": "TEACHER", "terminatedAt": "2026-10-05T16:00:00.000Z" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } }, "message.sent": { "post": { "summary": "message.sent", "description": "A family message was sent, by staff or a guardian. Never includes the text or image.", "parameters": [ { "name": "RoundUp-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.`)>" }, { "name": "RoundUp-Event", "in": "header", "required": true, "schema": { "const": "message.sent" } }, { "name": "RoundUp-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "RoundUp-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "createdAt", "centerId", "data" ], "properties": { "id": { "type": "string", "description": "Event id (evt_…). Stable across retries and redeliveries — dedupe on it." }, "type": { "const": "message.sent" }, "createdAt": { "type": "string", "format": "date-time" }, "centerId": { "type": "string" }, "data": { "type": "object" } }, "example": { "id": "evt_2b6f0c4e-8d1a-4c7e-9b1f-0a5e6d7c8b9a", "type": "message.sent", "createdAt": "2026-10-05T16:00:00.000Z", "centerId": "c0ffee00-0000-4000-8000-000000000000", "data": { "messageId": "6f1d2c3b-0000-4000-8000-000000000001", "conversationId": "fam_8a21", "senderRole": "STAFF", "hasImage": false, "sentAt": "2026-10-05T19:45:00.000Z" } } } } } }, "responses": { "410": { "description": "Unsubscribe this endpoint." }, "2XX": { "description": "Received. Anything else is retried." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "rk_live__", "description": "A center API key", "x-scopes": { "read:center": "Read the center's name, time zone and settings summary", "read:children": "Read the child roster", "read:classrooms": "Read classrooms", "read:attendance": "Read daily check-in and check-out times", "read:billing": "Read invoices", "read:incidents": "Read incident type, severity and dates", "read:staff": "Read staff names, roles and classrooms", "write:inquiries": "Create enrollment inquiries", "write:webhooks": "Create and delete webhook subscriptions" } } }, "responses": { "Unauthorized": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key lacks the operation's scope (see requiredScope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Over 120 requests per minute; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found at this key's center", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requiredScope": { "type": "string" } } }, "EventType": { "type": "string", "enum": [ "child.checked_in", "child.checked_out", "child.enrolled", "child.withdrawn", "invoice.created", "invoice.paid", "invoice.payment_failed", "incident.created", "staff.hired", "staff.terminated", "message.sent" ] }, "Me": { "type": "object", "properties": { "keyId": { "type": "string" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "center": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] } } } } }, "Center": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "currency": { "type": "string" } } }, "Child": { "type": "object", "properties": { "id": { "type": "integer", "description": "The child's 6-digit public id — the same id webhook payloads carry." }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dateOfBirth": { "type": [ "string", "null" ], "format": "date" }, "classroom": { "type": [ "string", "null" ] }, "enrollmentStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "WITHDRAWN" ] }, "enrolledAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "Classroom": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ageGroup": { "type": [ "string", "null" ] }, "capacity": { "type": [ "integer", "null" ] }, "status": { "type": "string" } } }, "AttendanceDay": { "type": "object", "properties": { "childId": { "type": "integer", "description": "The child's 6-digit public id — the same id webhook payloads carry." }, "date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "Checked In", "Checked Out", "Absent" ] }, "checkInTime": { "type": [ "string", "null" ], "format": "date-time" }, "checkOutTime": { "type": [ "string", "null" ], "format": "date-time" } } }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": [ "string", "null" ] }, "familyId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "OPEN", "PARTIAL", "PAID", "VOID" ] }, "amountDueCents": { "type": "integer" }, "amountPaidCents": { "type": "integer" }, "currency": { "type": "string", "description": "ISO 4217, lowercase" }, "dueDate": { "type": [ "string", "null" ], "format": "date" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Incident": { "type": "object", "properties": { "id": { "type": "string" }, "childId": { "type": [ "integer", "null" ] }, "type": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ] }, "incidentDate": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "StaffMember": { "type": "object", "properties": { "id": { "type": "integer", "description": "6-digit public id, the same as staff.* webhook payloads" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "classroom": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "InquiryInput": { "type": "object", "required": [ "guardianName", "guardianEmail", "childName" ], "properties": { "guardianName": { "type": "string" }, "guardianEmail": { "type": "string", "format": "email" }, "guardianPhone": { "type": "string" }, "childName": { "type": "string" }, "childDob": { "type": "string" }, "desiredStartDate": { "type": "string" }, "program": { "type": "string" }, "message": { "type": "string" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "active": { "type": "boolean" }, "source": { "type": "string", "enum": [ "app", "api" ] }, "createdAt": { "type": "string", "format": "date-time" } } } } } }