mark/vibn-agent-runner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
81994d4b6ca45270a6bdd1ebd0d1ae9c72c5f2bb
vibn-agent-runner/prd-template/campreg-api-and-integrations.md

13 KiB
Raw Blame History

CampReg API and Integration Specification

Version: 0.1
Date: 2026-06-01

1. API Philosophy

CampReg should be API-first from the beginning.

Competitors often expose APIs as enterprise add-ons or guided integration services. CampReg can differentiate by treating API access, event data, and webhooks as core infrastructure for modern providers, marketplace operations, AI agents, marketing automation, and custom workflows.

The API should support:

  • Provider integrations
  • Marketplace synchronization
  • Missinglettr/VibnAI workflows
  • Accounting and finance exports
  • CRM integrations
  • Custom reporting
  • Partner integrations
  • Future ecosystem apps

2. Reference API Landscape

2.1 CampMinder

CampMinder publicly describes its API as a way to connect camp data with other applications including Mailchimp, Constant Contact, Salesforce, Zapier, Google Sheets, marketing platforms, business intelligence dashboards, and accounting tools.

Relevant design lessons:

  • Camp data becomes more valuable when it can power marketing, reporting, and automation.
  • Contact/status syncing is important for outreach.
  • Financial and session data should be available for reporting.
  • API services may require guided setup for non-technical camps.

References:

2.2 CampSite

CampSite publicly documents that its API can add, edit, delete, and retrieve certain supported data. Publicly listed areas include families, campers, staff, groups, guests, donors, medical, advanced reports, financial transactions, enrollment, custom fields, bunking boards, bunking assignments, and transportation.

Relevant design lessons:

  • CampReg API should cover operational primitives, not only read-only reporting.
  • Financial, enrollment, bunking, medical, and transportation domains matter in camp software.
  • REST API access is useful, but webhooks are needed to avoid forcing external systems to poll.
  • API access is often sold separately by incumbents; CampReg can make API access part of its platform advantage.

References:

2.3 ACTIVE Network

ACTIVE’s public Activity API is read-only and exposes public activity/event data, including youth camps. This is useful as a reference for marketplace discovery APIs, not provider operations.

Relevant design lessons:

  • Public activity discovery can be modelled around searchable assets.
  • CampMatch can expose or consume public activity-style data.
  • Read-only discovery APIs are materially different from provider operational APIs.

Reference:

2.4 Hi.Events

Hi.Events is an open-source event ticketing and management platform. It is useful for registration/checkout/ticketing architecture, product add-ons, promo codes, self-hosting, analytics, webhooks, and event management flows.

References:

2.5 Attendize

Attendize is an older open-source Laravel event registration/ticketing system. It is useful for custom checkout questions, payment gateway patterns, attendee management, messaging, affiliate tracking, QR check-in, and reporting concepts.

Reference:

2.6 eCamp v3

eCamp is open-source camp planning software. It does not solve registration/payments, but is useful as a reference for camp planning, schedules, activities, printable plans, and responsive camp workflows.

References:

3. API Design Principles

3.1 API First, Product Safe

The API should be powerful but not expose unsafe shortcuts around consent, payments, child data, or health information.

3.2 Webhooks First for Event Automation

Many competitor APIs require polling. CampReg should support webhooks from the beginning so integrations can react to changes immediately.

3.3 Scoped Access

API keys must be scoped by provider organization and permission set.

Example scopes:

  • listings:read
  • listings:write
  • sessions:read
  • sessions:write
  • registrations:read
  • registrations:write
  • families:read
  • campers:read
  • payments:read
  • attendance:read
  • attendance:write
  • messages:send
  • campaigns:write
  • webhooks:manage

3.4 No Raw Payment Data

API should never expose raw card data. Payment APIs should use processor IDs, payment summaries, transaction statuses, and ledger entries.

3.5 Sensitive Data Guardrails

Health, medication, incident, and child data require special scopes, logging, and minimization.

3.6 Developer Experience Matters

Required:

  • OpenAPI documentation
  • Sandbox environment
  • API key management UI
  • Webhook test tool
  • Example payloads
  • SDK or client examples
  • Rate limits
  • Error codes
  • Idempotency keys

4. API Resource Map

4.1 Marketplace Resources

Listings

Endpoints:

  • GET /v1/listings
  • GET /v1/listings/{listing_id}
  • PATCH /v1/listings/{listing_id}
  • POST /v1/listings/{listing_id}/claim
  • POST /v1/listings/{listing_id}/publish

Use cases:

  • Sync provider listing details
  • Update categories, ages, dates, pricing, images, and registration links
  • Support claim workflow
  • Support marketplace publishing

Leads

Endpoints:

  • GET /v1/leads
  • GET /v1/leads/{lead_id}
  • PATCH /v1/leads/{lead_id}
  • POST /v1/leads/{lead_id}/convert

Use cases:

  • Provider follow-up
  • CRM integration
  • VibnAI follow-up automation

Search Events

Internal or partner endpoints:

  • GET /v1/analytics/search-demand
  • GET /v1/analytics/listing-performance

Use cases:

  • Provider demand insights
  • Growth automation recommendations

4.2 Provider Operations Resources

Organizations

  • GET /v1/organizations/{organization_id}
  • PATCH /v1/organizations/{organization_id}

Locations

  • GET /v1/locations
  • POST /v1/locations
  • GET /v1/locations/{location_id}
  • PATCH /v1/locations/{location_id}
  • DELETE /v1/locations/{location_id}

Programs

  • GET /v1/programs
  • POST /v1/programs
  • GET /v1/programs/{program_id}
  • PATCH /v1/programs/{program_id}
  • DELETE /v1/programs/{program_id}

Sessions

  • GET /v1/sessions
  • POST /v1/sessions
  • GET /v1/sessions/{session_id}
  • PATCH /v1/sessions/{session_id}
  • DELETE /v1/sessions/{session_id}

Session fields should include:

  • Name
  • Description
  • Program
  • Location
  • Start/end date
  • Daily times
  • Age range
  • Capacity
  • Price
  • Deposit
  • Registration status
  • Waitlist settings

4.3 Family and Camper Resources

Families

  • GET /v1/families
  • GET /v1/families/{family_id}
  • PATCH /v1/families/{family_id}

Parents / Guardians

  • GET /v1/families/{family_id}/guardians
  • POST /v1/families/{family_id}/guardians
  • PATCH /v1/guardians/{guardian_id}

Campers

  • GET /v1/campers
  • GET /v1/campers/{camper_id}
  • PATCH /v1/campers/{camper_id}

Important: Provider-scoped access should only return camper data relevant to that provider’s relationship.

4.4 Registration Resources

Registrations

  • GET /v1/registrations
  • POST /v1/registrations
  • GET /v1/registrations/{registration_id}
  • PATCH /v1/registrations/{registration_id}
  • POST /v1/registrations/{registration_id}/cancel

Enrollments

  • GET /v1/enrollments
  • GET /v1/enrollments/{enrollment_id}
  • PATCH /v1/enrollments/{enrollment_id}
  • POST /v1/enrollments/{enrollment_id}/transfer

Waitlists

  • GET /v1/waitlists
  • POST /v1/waitlists/{session_id}/entries
  • PATCH /v1/waitlists/entries/{entry_id}
  • POST /v1/waitlists/entries/{entry_id}/offer
  • POST /v1/waitlists/entries/{entry_id}/convert

4.5 Forms and Documents

Form Templates

  • GET /v1/forms/templates
  • POST /v1/forms/templates
  • GET /v1/forms/templates/{form_template_id}
  • PATCH /v1/forms/templates/{form_template_id}

Form Submissions

  • GET /v1/forms/submissions
  • GET /v1/forms/submissions/{submission_id}
  • PATCH /v1/forms/submissions/{submission_id}
  • POST /v1/forms/submissions/{submission_id}/approve
  • POST /v1/forms/submissions/{submission_id}/reject

Documents

  • GET /v1/documents
  • POST /v1/documents/upload-url
  • GET /v1/documents/{document_id}
  • DELETE /v1/documents/{document_id}

4.6 Payments and Ledger

Invoices

  • GET /v1/invoices
  • GET /v1/invoices/{invoice_id}
  • POST /v1/invoices
  • PATCH /v1/invoices/{invoice_id}

Payments

  • GET /v1/payments
  • GET /v1/payments/{payment_id}
  • POST /v1/payments/{payment_id}/refund

Ledger

  • GET /v1/ledger
  • POST /v1/ledger/manual-adjustment

Payment API notes:

  • Support Stripe Connect architecture.
  • Store and expose processor IDs.
  • Use idempotency keys for payment-affecting operations.
  • Avoid direct card data.

4.7 Attendance and Pickup

Attendance

  • GET /v1/attendance
  • POST /v1/attendance/check-in
  • POST /v1/attendance/check-out
  • PATCH /v1/attendance/{attendance_id}

Authorized Pickups

  • GET /v1/campers/{camper_id}/authorized-pickups
  • POST /v1/campers/{camper_id}/authorized-pickups
  • PATCH /v1/authorized-pickups/{pickup_id}
  • DELETE /v1/authorized-pickups/{pickup_id}

4.8 Health and Medication

Access to these endpoints must require special scopes and audit logging.

Medications

  • GET /v1/medications
  • POST /v1/medications
  • GET /v1/medications/{medication_id}
  • PATCH /v1/medications/{medication_id}
  • DELETE /v1/medications/{medication_id}

Dispenses

  • GET /v1/medication-dispenses
  • POST /v1/medication-dispenses

Incidents

  • GET /v1/incidents
  • POST /v1/incidents
  • GET /v1/incidents/{incident_id}
  • PATCH /v1/incidents/{incident_id}

4.9 Messaging and Campaigns

Messages

  • GET /v1/messages
  • POST /v1/messages
  • GET /v1/messages/{message_id}

Campaigns

  • GET /v1/campaigns
  • POST /v1/campaigns
  • GET /v1/campaigns/{campaign_id}
  • PATCH /v1/campaigns/{campaign_id}
  • POST /v1/campaigns/{campaign_id}/approve
  • POST /v1/campaigns/{campaign_id}/send-to-missinglettr

5. Webhooks

CampReg should support outbound webhooks for integrations.

Required webhook events:

Marketplace

  • listing.created
  • listing.updated
  • listing.claim_requested
  • listing.claim_approved
  • lead.created
  • lead.updated

Registration

  • registration.started
  • registration.completed
  • registration.cancelled
  • enrollment.created
  • enrollment.cancelled
  • waitlist.joined
  • waitlist.offer_created
  • waitlist.converted

Payments

  • invoice.created
  • payment.succeeded
  • payment.failed
  • refund.created
  • ledger.entry_created

Forms

  • form.submission_created
  • form.submission_approved
  • form.submission_rejected

Attendance

  • camper.checked_in
  • camper.checked_out
  • attendance.updated

Communication and Campaigns

  • message.sent
  • campaign.created
  • campaign.approved
  • campaign.sent_to_missinglettr
  • campaign.scheduled

Health

  • medication.created
  • medication.dispensed
  • incident.created

Health webhooks should be disabled by default and require explicit provider opt-in and scope approval.

6. Missinglettr API Integration

6.1 Purpose

Allow VibnAI and providers to create, approve, and schedule marketing campaigns through the Missinglettr API.

6.2 Campaign Types

  • Underfilled session campaign
  • New session announcement
  • Returning family reactivation
  • Local SEO content promotion
  • Seasonal camp launch campaign
  • Waitlist demand campaign
  • Provider listing improvement campaign
  • Blog-to-social campaign

6.3 Required Workflow

  1. CampReg detects campaign opportunity.
  2. VibnAI generates campaign recommendation.
  3. Provider reviews campaign.
  4. Provider approves or edits campaign.
  5. CampReg sends approved content to Missinglettr API.
  6. Missinglettr schedules/distributes campaign.
  7. Campaign status and performance return to CampReg.
  8. CampReg attributes registrations/leads to campaign where possible.

6.4 Required Campaign Fields

  • provider_organization_id
  • campaign_goal
  • target_session_ids
  • target_age_range
  • target_location
  • recommended_channels
  • generated_copy
  • image_assets
  • approval_status
  • missinglettr_campaign_id
  • scheduled_at
  • performance_metrics

7. API Security

Required:

  • Bearer token API authentication
  • API key hashing
  • Scoped permissions
  • Rate limits
  • Audit logs
  • IP allowlisting for advanced accounts
  • Webhook signing secrets
  • Idempotency keys
  • Pagination
  • Filtering
  • Sorting
  • Consistent error codes
  • Sensitive endpoint monitoring

8. Developer Portal Requirements

CampReg should eventually include a provider/developer portal with:

  • API key creation
  • Scope selection
  • Webhook configuration
  • Event delivery logs
  • Retry failed webhook
  • Test payload sender
  • Documentation
  • Example requests
  • Changelog
  • Sandbox/test mode

9. Integration Opportunities

Potential future integrations:

  • Stripe
  • QuickBooks
  • Xero
  • Google Sheets
  • Mailchimp
  • Constant Contact
  • Salesforce
  • HubSpot
  • Zapier
  • Make
  • Twilio
  • SendGrid/Postmark
  • Google Calendar
  • Apple Wallet / Google Wallet
  • Background check providers
  • School information systems

10. API Differentiation

CampReg should avoid copying the incumbent pattern of “API as a paid afterthought.” The API should be part of the product story:

CampReg is the provider operating system that connects camp discovery, registration, operations, and growth automation.

This API strategy supports VibnAI, marketplace integrations, campaign automation, analytics, and future partner ecosystem development.

Reference in New Issue View Git Blame Copy Permalink