API Endpoints Specification

Base URL

Development: http://localhost:8000/api/v1
Production: https://impactpulse-api.catalyzeupdev.com/api/v1

Authentication Endpoints

Register

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "full_name": "John Doe",
  "timezone": "America/New_York"
}

Response: 201 Created
{
  "success": true,
  "data": {
    "user_id": "ObjectId",
    "email": "user@example.com",
    "full_name": "John Doe",
    "email_verified": false
  },
  "message": "Registration successful. Please verify your email."
}

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response: 200 OK
{
  "success": true,
  "data": {
    "access_token": "jwt_token",
    "refresh_token": "refresh_token",
    "token_type": "bearer",
    "expires_in": 900,
    "user": {
      "id": "ObjectId",
      "email": "user@example.com",
      "full_name": "John Doe",
      "organizations": ["org_id_1", "org_id_2"]
    }
  }
}

Refresh Token

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "refresh_token"
}

Response: 200 OK
{
  "success": true,
  "data": {
    "access_token": "new_jwt_token",
    "expires_in": 900
  }
}

Get Current User

GET /auth/me
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": {
    "id": "ObjectId",
    "email": "user@example.com",
    "full_name": "John Doe",
    "email_verified": true,
    "organizations": [
      {
        "id": "org_id",
        "name": "Acme Corp",
        "role": "admin"
      }
    ],
    "stats": {
      "surveys_taken": 5,
      "last_survey_at": "2024-01-15T10:00:00Z"
    }
  }
}

Verify Email

POST /auth/verify-email
Content-Type: application/json

{
  "token": "verification_token"
}

Response: 200 OK
{
  "success": true,
  "message": "Email verified successfully"
}

Organization Endpoints

Create Organization

POST /organizations
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "description": "Leading innovation company",
  "industry": "Technology",
  "size": "50-100"
}

Response: 201 Created
{
  "success": true,
  "data": {
    "id": "ObjectId",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "created_at": "2024-01-15T10:00:00Z",
    "role": "owner"
  }
}

List User's Organizations

GET /organizations
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": [
    {
      "id": "ObjectId",
      "name": "Acme Corporation",
      "slug": "acme-corp",
      "role": "owner",
      "member_count": 25,
      "survey_count": 5
    }
  ],
  "metadata": {
    "total": 2,
    "page": 1,
    "limit": 20
  }
}

Get Organization Details

GET /organizations/{org_id}
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": {
    "id": "ObjectId",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "description": "Leading innovation company",
    "created_at": "2024-01-15T10:00:00Z",
    "settings": {
      "max_surveys": 100,
      "features": ["advanced_analytics"]
    },
    "stats": {
      "member_count": 25,
      "survey_count": 10,
      "total_responses": 250,
      "avg_completion_rate": 0.75
    }
  }
}

Update Organization

PUT /organizations/{org_id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Acme Corp Updated",
  "description": "New description",
  "settings": {
    "reminder_enabled": true
  }
}

Response: 200 OK
{
  "success": true,
  "data": {
    "id": "ObjectId",
    "name": "Acme Corp Updated",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Invite Member

POST /organizations/{org_id}/invite
Authorization: Bearer {token}
Content-Type: application/json

{
  "emails": ["user1@example.com", "user2@example.com"],
  "role": "member",
  "custom_message": "Welcome to our team!"
}

Response: 201 Created
{
  "success": true,
  "data": {
    "invitations_sent": 2,
    "invitations": [
      {
        "email": "user1@example.com",
        "token": "invite_token_1",
        "status": "sent"
      }
    ]
  }
}

List Organization Members

GET /organizations/{org_id}/members
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": [
    {
      "id": "member_id",
      "user": {
        "id": "user_id",
        "email": "user@example.com",
        "full_name": "John Doe"
      },
      "role": "admin",
      "joined_at": "2024-01-15T10:00:00Z",
      "stats": {
        "surveys_taken": 5,
        "completion_rate": 0.8
      }
    }
  ]
}

Accept Invitation

POST /invitations/{token}/accept
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": {
    "organization": {
      "id": "org_id",
      "name": "Acme Corporation"
    },
    "role": "member"
  },
  "message": "Successfully joined Acme Corporation"
}

Survey Endpoints

Create Survey

POST /surveys
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Q1 2024 Maslow Assessment",
  "description": "Quarterly wellbeing check",
  "type": "maslow",
  "organization_id": "org_id",
  "settings": {
    "allow_multiple_attempts": true,
    "reminder_enabled": true,
    "reminder_schedule": [24, 48, 168]
  }
}

Response: 201 Created
{
  "success": true,
  "data": {
    "id": "survey_id",
    "public_id": "surv_abc123",
    "title": "Q1 2024 Maslow Assessment",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

List Surveys

GET /surveys?organization_id={org_id}&status=published
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": [
    {
      "id": "survey_id",
      "title": "Q1 2024 Maslow Assessment",
      "type": "maslow",
      "status": "published",
      "response_count": 25,
      "completion_rate": 0.75
    }
  ]
}

Get Survey with Questions

GET /surveys/{survey_id}
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": {
    "id": "survey_id",
    "title": "Q1 2024 Maslow Assessment",
    "description": "Quarterly wellbeing check",
    "questions": [
      {
        "id": "question_id",
        "text": "How satisfied are you with your work-life balance?",
        "type": "rating",
        "required": true,
        "category": "safety",
        "validation": {
          "min": 1,
          "max": 10
        }
      }
    ],
    "user_attempts": [
      {
        "attempt_number": 1,
        "completed_at": "2024-01-01T10:00:00Z",
        "score": 75
      }
    ]
  }
}

Survey Session Endpoints

Start Survey Session

POST /surveys/{survey_id}/start
Authorization: Bearer {token}

Response: 201 Created
{
  "success": true,
  "data": {
    "session_id": "session_id",
    "survey_id": "survey_id",
    "attempt_number": 2,
    "status": "in_progress",
    "total_questions": 20,
    "resume_token": "resume_token"
  }
}

Save Progress

PUT /sessions/{session_id}/save
Authorization: Bearer {token}
Content-Type: application/json

{
  "current_question_index": 5,
  "responses": {
    "question_id_1": "answer",
    "question_id_2": 7
  }
}

Response: 200 OK
{
  "success": true,
  "data": {
    "session_id": "session_id",
    "questions_answered": 5,
    "questions_remaining": 15,
    "last_saved_at": "2024-01-15T10:15:00Z"
  }
}

Get Session Status

GET /sessions/{session_id}
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": {
    "session_id": "session_id",
    "status": "in_progress",
    "current_question_index": 5,
    "questions_answered": 5,
    "partial_responses": {
      "question_id_1": "answer",
      "question_id_2": 7
    },
    "time_spent_seconds": 300
  }
}

Complete Survey

POST /sessions/{session_id}/complete
Authorization: Bearer {token}
Content-Type: application/json

{
  "responses": {
    "question_id_1": "answer",
    "question_id_2": 7
  }
}

Response: 200 OK
{
  "success": true,
  "data": {
    "response_id": "response_id",
    "session_id": "session_id",
    "scores": {
      "total": 85,
      "by_category": {
        "physiological": 0.90,
        "safety": 0.85
      }
    },
    "comparison": {
      "previous_attempt": 1,
      "score_delta": 10,
      "improvement_areas": ["self_actualization"]
    }
  }
}

List User's Survey Attempts

GET /surveys/{survey_id}/attempts
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": [
    {
      "attempt_number": 2,
      "session_id": "session_id",
      "status": "completed",
      "started_at": "2024-01-15T10:00:00Z",
      "completed_at": "2024-01-15T10:30:00Z",
      "score": 85
    },
    {
      "attempt_number": 1,
      "session_id": "session_id_1",
      "status": "completed",
      "started_at": "2023-10-15T10:00:00Z",
      "completed_at": "2023-10-15T10:25:00Z",
      "score": 75
    }
  ]
}

Maslow-Specific Endpoints

Get Maslow History

GET /maslow/history
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": [
    {
      "attempt_number": 3,
      "date": "2024-01-15T10:00:00Z",
      "scores": {
        "physiological": 0.85,
        "safety": 0.72,
        "love_belonging": 0.68,
        "esteem": 0.61,
        "self_actualization": 0.55,
        "overall": 0.682
      }
    }
  ]
}

Compare Maslow Attempts

GET /maslow/compare?attempt1=1&attempt2=3
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": {
    "attempt_1": {
      "number": 1,
      "date": "2023-10-15T10:00:00Z",
      "scores": { }
    },
    "attempt_2": {
      "number": 3,
      "date": "2024-01-15T10:00:00Z",
      "scores": { }
    },
    "comparison": {
      "days_between": 92,
      "deltas": {
        "physiological": 0.05,
        "safety": -0.03,
        "love_belonging": 0.08,
        "esteem": 0.11,
        "self_actualization": 0.15,
        "overall": 0.072
      },
      "biggest_improvement": "self_actualization",
      "biggest_decline": "safety"
    }
  }
}

Get Organization Maslow Analytics

GET /organizations/{org_id}/maslow/analytics
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": {
    "aggregate_scores": {
      "physiological": 0.78,
      "safety": 0.71,
      "love_belonging": 0.65,
      "esteem": 0.62,
      "self_actualization": 0.58,
      "overall": 0.668
    },
    "member_count": 25,
    "response_count": 75,
    "completion_rate": 0.80,
    "trends": {
      "improving": ["self_actualization", "esteem"],
      "declining": ["safety"],
      "stable": ["physiological", "love_belonging"]
    },
    "percentiles": {
      "25th": 0.55,
      "50th": 0.67,
      "75th": 0.78,
      "90th": 0.85
    }
  }
}

Reminder Endpoints

Get Reminder Preferences

GET /reminders/preferences
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "data": {
    "reminders_enabled": true,
    "email_preferences": {
      "reminders": true,
      "updates": false,
      "reports": true
    },
    "quiet_hours": {
      "enabled": true,
      "start": "20:00",
      "end": "08:00",
      "timezone": "America/New_York"
    }
  }
}

Update Reminder Preferences

PUT /reminders/preferences
Authorization: Bearer {token}
Content-Type: application/json

{
  "reminders_enabled": false,
  "email_preferences": {
    "reminders": false
  }
}

Response: 200 OK
{
  "success": true,
  "message": "Preferences updated successfully"
}

Error Responses

Validation Error (400)

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "field": "email", "message": "Invalid email format" },
    { "field": "password", "message": "Password must be at least 8 characters" }
  ]
}

Authentication Error (401)

{
  "success": false,
  "message": "Authentication required",
  "error_code": "AUTH_REQUIRED"
}

Authorization Error (403)

{
  "success": false,
  "message": "Insufficient permissions",
  "error_code": "INSUFFICIENT_PERMISSIONS"
}

Not Found Error (404)

{
  "success": false,
  "message": "Resource not found",
  "error_code": "RESOURCE_NOT_FOUND"
}

Rate Limit Error (429)

{
  "success": false,
  "message": "Rate limit exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

Pagination

All list endpoints support pagination:

GET /endpoint?page=1&limit=20&sort_by=created_at&sort_order=desc

Response includes:
{
  "data": [...],
  "metadata": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Rate Limiting

Anonymous: 60 requests/hour
Authenticated: 600 requests/hour
Organization Admin: 1200 requests/hour
Enterprise: Unlimited

Headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1642329600

API Endpoints

API Endpoints Specification

Base URL

Authentication Endpoints

Register

Login

Refresh Token

Get Current User

Verify Email

Organization Endpoints

Create Organization

List User's Organizations

Get Organization Details

Update Organization

Invite Member

List Organization Members

Accept Invitation

Survey Endpoints

Create Survey

List Surveys

Get Survey with Questions

Survey Session Endpoints

Start Survey Session

Save Progress

Get Session Status

Complete Survey

List User's Survey Attempts

Maslow-Specific Endpoints

Get Maslow History

Compare Maslow Attempts

Get Organization Maslow Analytics

Reminder Endpoints

Get Reminder Preferences

Update Reminder Preferences

Error Responses

Validation Error (400)

Authentication Error (401)

Authorization Error (403)

Not Found Error (404)

Rate Limit Error (429)

Pagination

Rate Limiting