Division Agent Integration Guide

How to integrate your division with the SphereUs Network for automatic engagement tracking

Automatic Engagement Tracking (Updated)

The reportTransaction function now automatically creates Engagement records. No additional integration needed!

✓ Already Integrated

When divisions call reportTransaction, the system now:

  • Creates Order records (as before)
  • Awards SU Coins to buyer and seller (as before)
  • NEW: Creates Engagement records for both buyer and seller
  • NEW: Tracks which divisions each member uses
Integration Code (Unchanged)

Continue using the same reportTransaction API endpoint:

// Division Agent calls this after successful transaction
const response = await fetch('https://sphereus.base44.app/functions/reportTransaction', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_DIVISION_AUTH_TOKEN'
  },
  body: JSON.stringify({
    division_name: "Guided Aim",
    transaction_id: "GA-12345",
    buyer_email: "customer@example.com",
    seller_email: "coach@example.com",
    total_amount: 100.00,
    transaction_type: "purchase",
    item_title: "Life Coaching Session",
    item_description: "1-hour personal development session"
  })
});

const result = await response.json();
// Returns: { success, order_id, buyer_su_earned, seller_su_earned }
What Gets Tracked Now

Purchase Engagement

Buyer gets an engagement record showing they purchased from your division

Sale Engagement

Seller gets an engagement record showing they sold through your division

Division Activity Dashboard

Members see "My Division Activity" on their dashboard showing all divisions they've engaged with

Listing Sync API (Marketplace Integration)

To publish listings to SphereUs Marketplace (SUM) with sphere-based discovery:

⚠️ REQUIRED FIELDS UPDATE

As of December 2025, seller_county and seller_state are now REQUIRED for all listings to appear in sphere-based searches.

// POST to https://sphereus.base44.app/functions/syncDivisionListing
const response = await fetch('https://sphereus.base44.app/functions/syncDivisionListing', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_DIVISION_AUTH_TOKEN'
  },
  body: JSON.stringify({
    title: "Math Tutoring - Algebra & Geometry",
    description: "Expert math tutoring for middle and high school students",
    category: "services", // services, physical_products, digital_products, classifieds, experiences, partnerships
    division: "Grade Level Up",
    price_usd: 50.00,
    pricing_type: "per_hour", // one_time, per_hour, per_session, monthly, annual
    seller_email: "tutor@example.com",
    seller_county: "Orange County", // REQUIRED for sphere discovery
    seller_state: "California", // REQUIRED for sphere discovery
    images: ["https://example.com/image1.jpg"],
    location: "Online or In-Person",
    tags: ["math", "tutoring", "algebra"]
  })
});

Note: Without seller_county and seller_state, listings will still be created but won't appear in county-based sphere searches.

NEW
Calendar & Booking Integration

Members have a unified calendar at SphereUs.com. When users book tutoring sessions, schedule meetings, or arrange meetups, add events to their calendars:

Calendar API Endpoints

  • Add Event: POST /functions/addCalendarEvent
  • Update Event: POST /functions/updateCalendarEvent
  • Delete Event: POST /functions/deleteCalendarEvent
  • Create Booking: POST /functions/createBookingWithConflictCheck (auto-adds calendar events)

Example: Grade Level Up Tutoring Session

// When student books a tutoring session
const response = await fetch('https://sphereus.com/functions/addCalendarEvent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${userToken}`  // From localStorage after SSO
  },
  body: JSON.stringify({
    user_email: "tutor@example.com",  // Or student email
    title: "Algebra Tutoring Session",
    description: "Help with quadratic equations",
    division: "Grade Level Up",
    start_datetime: "2026-01-15T14:00:00.000Z",
    end_datetime: "2026-01-15T15:00:00.000Z",
    location: "Virtual - Zoom",
    is_virtual: true,
    metadata: {
      session_id: "session_123",
      student_name: "John Doe"
    }
  })
});

Example: SplitZen Attorney Meeting

// When scheduling a consultation
await fetch('https://sphereus.com/functions/addCalendarEvent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${userToken}`
  },
  body: JSON.stringify({
    user_email: "attorney@example.com",
    title: "Business Separation Consultation",
    description: "Initial consultation with John Smith",
    division: "SplitZen",
    start_datetime: "2026-01-20T10:00:00.000Z",
    end_datetime: "2026-01-20T11:00:00.000Z",
    location: "123 Main St, Suite 200",
    metadata: { case_id: "case_456" }
  })
});

Example: Swicket Ticket Swap

// When arranging a meetup to exchange tickets
await fetch('https://sphereus.com/functions/addCalendarEvent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${user1Token}`
  },
  body: JSON.stringify({
    user_email: "user1@example.com",
    title: "Ticket Exchange - Taylor Swift Concert",
    description: "Meeting with Sarah to swap tickets",
    division: "Swicket",
    start_datetime: "2026-02-10T18:00:00.000Z",
    end_datetime: "2026-02-10T18:30:00.000Z",
    location: "Starbucks on Main St",
    metadata: { swap_id: "swap_789" }
  })
});

// Add to both users' calendars
await fetch('https://sphereus.com/functions/addCalendarEvent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${user2Token}`
  },
  body: JSON.stringify({
    user_email: "user2@example.com",
    title: "Ticket Exchange - Taylor Swift Concert",
    description: "Meeting with Mike to swap tickets",
    division: "Swicket",
    start_datetime: "2026-02-10T18:00:00.000Z",
    end_datetime: "2026-02-10T18:30:00.000Z",
    location: "Starbucks on Main St",
    metadata: { swap_id: "swap_789" }
  })
});

✓ Benefits

  • Members see ALL their commitments in one unified calendar
  • Automatic conflict prevention across all divisions
  • Visible in Dashboard → My Calendar on SphereUs.com
  • Works for current and future divisions

Full documentation: Visit sphereus.com/pages/CalendarAPIGuide

Required Division Names

Use these exact names in your division_name parameter:

Guided Aim
Grade Level Up
Golf Your Age
Anvilar Group
Quality Charters
Federal Programs
Wompus Games
Hey Lorne Michaels
SplitZen
Swicket
BudVan
Foundation
Marketplace