Integration Guide

REST API Integration

Use our API endpoints to integrate compliance tracking into your existing application.

Authentication

// Login to get JWT token
const response = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password'
  })
});

const { token } = await response.json();

// Use token for authenticated requests
const data = await fetch('/api/vr/enrollment', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Create VR Enrollment

POST /api/vr/enrollment
Content-Type: application/json
Authorization: Bearer {token}

{
  "userId": "user-123",
  "vrAgency": "State VR Agency",
  "vrCounselor": "Jane Smith",
  "vrCounselorEmail": "jane@vr.gov",
  "programType": "self_employment",
  "currentPhase": "assessment",
  "status": "active"
}

View Full API Documentation →

Database Schema Import

Copy our battle-tested schemas into your own Drizzle ORM project.

Import Schemas

// From shared/schema.ts
import { 
  vrEnrollment,
  vrServiceRecords,
  vrMilestones,
  workforceProgramEnrollment,
  employmentOutcomes
} from './magician-platform/shared/schema';

// Use with your Drizzle instance
import { db } from './your-db';

// Create VR enrollment
const enrollment = await db
  .insert(vrEnrollment)
  .values({
    userId: user.id,
    vrAgency: 'State VR',
    programType: 'job_placement'
  })
  .returning();

Schema Validation

import { insertVREnrollmentSchema } from './schema';

// Validate input with Zod
const validatedData = insertVREnrollmentSchema.parse({
  vrAgency: 'State VR Agency',
  programType: 'self_employment',
  // ... other fields
});

View Schema Definitions →

Webhook Integration

Subscribe to compliance events and receive real-time notifications.

Register Webhook

POST /api/webhooks/register
Content-Type: application/json
Authorization: Bearer {token}

{
  "url": "https://your-app.com/webhooks/compliance",
  "events": [
    "vr.milestone.completed",
    "workforce.outcome.recorded",
    "vr.service.created"
  ],
  "secret": "your-webhook-secret"
}

Handle Webhook Events

// In your application
app.post('/webhooks/compliance', (req, res) => {
  // Verify signature
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifySignature(
    req.body, 
    signature, 
    webhookSecret
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process event
  const { event, data } = req.body;
  
  switch(event) {
    case 'vr.milestone.completed':
      handleMilestoneCompleted(data);
      break;
    case 'workforce.outcome.recorded':
      handleOutcomeRecorded(data);
      break;
  }
  
  res.status(200).send('OK');
});

View Webhook Documentation →

GitHub Actions Workflows

Use automated compliance checks in your CI/CD pipeline.

Add Workflow File

# .github/workflows/compliance.yml
name: Compliance Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  vr-compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: VR Compliance Check
        run: |
          npm install
          npm run validate:vr
          
  accessibility:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Accessibility Audit
        run: |
          npm install
          npm run test:accessibility

View Example Workflows →