Zapier Integratrion

Vega AI provides a comprehensive API for integrating with Zapier to automate workflows, sync data to CRM systems, and trigger actions based on student activities. This document covers all REST API endpoints designed specifically for Zapier integration.

Base URL

https://backend.myvega/api/zapier

Authentication

All API endpoints require authentication using an API key. The API key can be provided in one of the following ways:

Headers

• x-api-key: Your organization's API key

• Authorization: Bearer token or direct API key

Query Parameters (for compatibility)

• apiKey: Your organization's API key

Example Request with Authentication

curl -X GET "https://backend.myvega/api/zapier/healthcheck" \
  -H "x-api-key: your-api-key-here"

---

API Endpoints

1. Health Check

Validates API key and returns service status information.

Endpoint: GET /api/zapier/healthcheck

Authentication: Required

Response:

{
  "success": true,
  "status": "healthy",
  "message": "API is operational and your credentials are valid",
  "authentication": {
    "valid": true,
    "organizationName": "Your Organization Name"
  },
  "timestamp": "25-12-2024",
  "endpoints": [
    {
      "path": "/api/zapier/healthcheck",
      "method": "GET",
      "description": "Health check with API key validation",
      "authenticated": true
    },
    {
      "path": "/api/zapier/userinfo",
      "method": "POST",
      "description": "Get organization users list with subscription info (supports pagination with page and limit in request body)",
      "authenticated": true
    },
    {
      "path": "/api/zapier/new-student-signups",
      "method": "GET",
      "description": "Get new student signups for CRM integration (supports ?limit=50&since=ISO_DATE for basic signup data)",
      "authenticated": true
    },
    {
      "path": "/api/zapier/student-diagnostic-tests",
      "method": "POST",
      "description": "Get all diagnostic test data for the organization. Supports filtering by date, test type, and pagination",
      "authenticated": true
    },
    {
      "path": "/api/zapier/students-analytics",
      "method": "POST",
      "description": "Get students analytics data (similar to GraphQL getStudentsAnalytics). Supports filtering by test types, dates, names, course, and status",
      "authenticated": true
    },
    {
      "path": "/api/zapier/students-practice-analytics",
      "method": "POST",
      "description": "Get students analytics data for quiz, assignment, homework, and exit ticket tests with pagination support",
      "authenticated": true
    }
  ]
}

2. Organization Users Information

Retrieves a paginated list of users in the organization with subscription details.

Endpoint: POST /api/zapier/userinfo

Authentication: Required

Request Body:

{
  "page": 1,
  "limit": 10
}

Parameters:

• page (optional): Page number for pagination (default: 1)

• limit (optional): Number of users per page (default: 10, max: 100)

Response:

{
  "success": true,
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "count": 10,
  "users": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "email": "[email protected]",
      "parentEmail": "[email protected]",
      "phoneNumber": "[phone]",
      "role": "STUDENT",
      "createdAt": "25-12-2024",
      "isOnboardingCompleted": true,
      "intentLevel": "high",
      "reasoning": "Student shows strong interest in SAT preparation",
      "subscription": "PRO",
      "userType": "paid"
    }
  ]
}

3. New Student Signups (Trigger)

Retrieves new student signups for CRM integration. Designed for polling triggers in Zapier.

Endpoint: GET /api/zapier/new-student-signups

Authentication: Required

Query Parameters:

• limit (optional): Number of students to return (default: 10, max: 100)

• since (optional): ISO date string to filter students created after this date (e.g., "2024-01-01T00:00:00Z")

Response: Returns an array of student objects for easy mapping in Zapier:

[
  {
    "firstName": "Jane",
    "lastName": "Smith",
    "fullName": "Jane Smith",
    "email": "[email protected]",
    "phoneNumber": "[phone]",
    "role": "STUDENT",
    "signupDate": "2024-12-25",
    "isOnboardingCompleted": false,
    "lastLogin": null,
    "intentLevel": "medium",
    "intentReasoning": "Interested in college preparation"
  }
]

Zapier Setup:

1. Create a "Polling" trigger in Zapier

2. Use: GET /api/zapier/new-student-signups

3. Add your API key to headers

4. Configure polling interval (recommended: every 15 minutes)

5. Map response fields to your CRM fields

4. Student Diagnostic Tests

Retrieves diagnostic test data for the organization with detailed analytics.

Endpoint: POST /api/zapier/student-diagnostic-tests

Authentication: Required

Request Body:

{
  "limit": 100,
  "since": "2024-01-01T00:00:00Z",
  "testType": "DIAGNOSTIC"
}

Parameters:

• limit (optional): Number of test records to return (default: 100, max: 500)

• since (optional): ISO date string to filter tests created after this date

• testType (optional): Filter by test type ("DIAGNOSTIC" or "STRUCTURED_TEST", default: "DIAGNOSTIC")

Response:

{
  "success": true,
  "message": "Diagnostic test data retrieved successfully",
  "count": 25,
  "data": [
    {
      "testName": "SAT Diagnostic Test - Math",
      "testType": "DIAGNOSTIC",
      "studentName": "John Doe",
      "studentEmail": "[email protected]",
      "courseName": "SAT Math Preparation",
      "masteryScore": 75,
      "overallCompletionStatus": "COMPLETED",
      "createdAt": "2024-12-25T10:30:00.000Z",
      "completedAt": "25-12-2024",
      "computedMetrics": [
        {
          "metricName": "Algebra",
          "value": 80,
          "maxScore": 100
        },
        {
          "metricName": "Geometry",
          "value": 70,
          "maxScore": 100
        }
      ]
    }
  ]
}

5. Student Analytics (Structured Tests)

Retrieves student analytics data for structured tests with detailed metrics and pagination.

Endpoint: POST /api/zapier/students-analytics

Authentication: Required

Request Body:

{
  "page": 1,
  "limit": 50
}

Parameters:

• page (required): Page number for pagination

• limit (required): Number of results per page (1-100)

Response:

{
  "success": true,
  "message": "Success",
  "totalPages": 5,
  "totalTests": 250,
  "currentPage": 1,
  "nextPage": 2,
  "previousPage": null,
  "hasNextPage": true,
  "hasPreviousPage": false,
  "tests": [
    {
      "name": "John Doe",
      "courseName": "SAT Math Preparation",
      "testName": "Chapter 5 Practice Test",
      "testType": "STRUCTURED_TEST",
      "masteryScore": 85,
      "maxScoreForAllQuestions": 100,
      "projectedScore": 1450,
      "overallCompletionStatus": "COMPLETED",
      "aiFeedback": "Excellent performance on algebra concepts",
      "date": "2024-12-25T10:30:00.000Z",
      "retaken": false,
      "timeZone": "America/New_York",
      "computedMetrics": {
        "Algebra Mastery": 90,
        "Algebra Mastery_maxScore": 100,
        "Geometry Mastery": 80,
        "Geometry Mastery_maxScore": 100,
        "Data Analysis": 85,
        "Data Analysis_maxScore": 100
      }
    }
  ]
}

6. Student Practice Analytics

Retrieves student analytics for practice tests (Quiz, Assignment, Homework, Exit Ticket).

Endpoint: POST /api/zapier/students-practice-analytics

Authentication: Required

Request Body:

{
  "page": 1,
  "limit": 50
}

Parameters:

• page (required): Page number for pagination

• limit (required): Number of results per page (1-100)

Response:

{
  "success": true,
  "message": "Success",
  "totalPages": 10,
  "totalTests": 500,
  "currentPage": 1,
  "nextPage": 2,
  "previousPage": null,
  "hasNextPage": true,
  "hasPreviousPage": false,
  "tests": [
    {
      "name": "Jane Smith",
      "courseName": "SAT Math Preparation",
      "testName": "Weekly Quiz - Linear Equations",
      "testType": "QUIZ",
      "masteryScore": 92,
      "maxScoreForAllQuestions": 100,
      "overallCompletionStatus": "COMPLETED",
      "aiFeedback": "Perfect score! Strong understanding of linear equations",
      "date": "2024-12-25T14:20:00.000Z",
      "retaken": false,
      "timeZone": "America/New_York"
    }
  ]
}

Subscribe to Webhooks

Subscribe a Zapier webhook URL to receive real-time notifications.

Endpoint: POST /api/zapier/subscribe

Authentication: Required

Request Body:

{
  "hookUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
}

Response:

{
  "success": true,
  "message": "Webhook subscribed successfully",
  "webhook": {
    "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
    "status": "active",
    "createdAt": "2024-12-25T10:30:00.000Z"
  },
  "hookUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
}

Unsubscribe from Webhooks

Remove a webhook URL from notifications.

Endpoint: POST /api/zapier/unsubscribe

Authentication: Required

Request Body:

{
  "hookUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
}

Response:

{
  "success": true,
  "message": "Webhook unsubscribed successfully"
}

Webhook Notifications

When students register, the following payload is sent to active webhooks:

{
  "id": "507f1f77bcf86cd799439011",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "email": "[email protected]",
  "phoneNumber": "[phone]",
  "role": "STUDENT",
  "signupDate": "2024-12-25",
  "isOnboardingCompleted": false,
  "lastLogin": null,
  "intentLevel": "high",
  "intentReasoning": "Strong interest in SAT preparation"
}

Error Handling

All endpoints return standardized error responses:

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message",
  "timestamp": "25-12-2024"
}

Common HTTP status codes:

• 200: Success

• 400: Bad Request (invalid parameters)

• 403: Forbidden (invalid API key)

• 404: Not Found

• 500: Internal Server Error

Rate Limiting

• API requests are rate-limited per organization

• Standard limits apply to prevent abuse

• Contact support for increased limits if needed

Date Formats

• API responses use DD-MM-YYYY format for display dates

• ISO 8601 format (YYYY-MM-DD) for precise timestamps

• Query parameters accept ISO 8601 date strings

Test Types

• DIAGNOSTIC: Initial assessment tests

• STRUCTURED_TEST: Full practice tests

• QUIZ: Short quizzes

• ASSIGNMENT: Homework assignments

• HOMEWORK: Homework tasks

• EXIT_TICKET: End-of-lesson assessments

Subscription Tiers

• BASIC: Free tier

• PRO: Professional tier

• PRO_MAX: Premium tier

Completion Status

• PENDING: Test not started

• IN_PROGRESS: Test in progress

• COMPLETED: Test finished

• EXPIRED: Test expired

Zapier Integration Examples

1. Student Signup to CRM

1. Trigger: Polling trigger on /api/zapier/new-student-signups

2. Action: Create/update contact in CRM (HubSpot, Salesforce, etc.)

3. Schedule: Every 15 minutes

2. Test Results to Google Sheets

1. Trigger: Polling trigger on /api/zapier/students-analytics

2. Action: Add/update row in Google Sheet

3. Schedule: Every hour

3. Real-time Signup Notifications

1. Trigger: Webhook trigger on /api/zapier/subscribe

2. Action: Send Slack notification or email alert

4. Diagnostic Results to Analytics Platform

1. Trigger: Polling trigger on /api/zapier/student-diagnostic-tests

2. Action: Send data to analytics platform (Mixpanel, Amplitude, etc.)

3. Schedule: Daily

Support

For API key generation, technical support, or additional endpoints:

• Contact: [email protected]

• Documentation: https://docs.learnq.ai

Version History

• v1.0: Initial Zapier API release

  • Health check endpoint

  • User information endpoint

  • New student signups trigger

  • Student diagnostic tests endpoint

  • Student analytics endpoints

  • Webhook subscription system

---

Last Updated: December 25, 2024 API Version: v1.0