API Documentation - Wellness Pulse

Getting Started

To use the Wellness Pulse API, you'll need an API key. You can create and manage API keys from your dashboard.

Base URL: https://wellpulse.org/api/public/v1.php

Authentication

All API requests require authentication using your API key. You can provide it in one of three ways:

Header: X-API-Key: your_api_key_here
Query Parameter: ?api_key=your_api_key_here
Authorization Header: Authorization: Bearer your_api_key_here

⚠️ Security: Never expose your API key in client-side code. Always use it server-side.

Endpoints

GET /api/public/v1.php?endpoint=health

Check API health status. No authentication required.

Surveys

GET /api/public/v1.php?endpoint=surveys

Get all surveys for your institution.

Parameter	Type	Description
`id`	string	Get a specific survey by ID
`location_id`	string	Filter by location ID
`active_only`	boolean	Only return active surveys (default: false)

POST /api/public/v1.php?endpoint=surveys

Create a new survey.

{
  "title": "Employee Wellness Check",
  "location_id": "uuid-here",
  "template_id": "uuid-here",
  "description": "Optional description"
}
                

PUT /api/public/v1.php?endpoint=surveys&id={survey_id}

Update an existing survey.

DELETE /api/public/v1.php?endpoint=surveys&id={survey_id}

Delete (deactivate) a survey.

Responses

GET /api/public/v1.php?endpoint=responses

Get survey responses.

Parameter	Type	Description
`survey_id`	string	Filter by survey ID
`location_id`	string	Filter by location ID
`start_date`	date	Filter responses from this date (YYYY-MM-DD)
`end_date`	date	Filter responses until this date (YYYY-MM-DD)
`limit`	integer	Number of results (max 1000, default 100)
`offset`	integer	Pagination offset (default 0)

POST /api/public/v1.php?endpoint=responses

Submit a survey response.

{
  "survey_id": "uuid-here",
  "responses": [
    {
      "question_id": "q1",
      "value": 8
    },
    {
      "question_id": "q2",
      "value": 7
    }
  ]
}
                

Analytics

GET /api/public/v1.php?endpoint=analytics

Get analytics data for your surveys.

Example Response:

{
  "success": true,
  "data": {
    "total_responses": 150,
    "avg_wellness_score": 7.5,
    "avg_stress_score": 3.2,
    "low_wellness_count": 12,
    "high_stress_count": 8
  }
}
                    

Locations

GET /api/public/v1.php?endpoint=locations

Get all locations for your institution.

POST /api/public/v1.php?endpoint=locations

Create a new location.

{
  "name": "Main Office",
  "building": "Building A",
  "floor": "3rd Floor",
  "room": "301",
  "description": "Optional description"
}
                

Rate Limiting

API requests are rate-limited to prevent abuse. Default rate limit is 60 requests per minute per API key. You can adjust this when creating your API key.

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Error Responses

All errors follow a consistent format:

{
  "error": "Error type",
  "message": "Human-readable error message"
}
            

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Example Usage

cURL Example

# Get all surveys
curl -H "X-API-Key: your_api_key_here" \
  https://wellpulse.org/api/public/v1.php?endpoint=surveys

# Submit a response
curl -X POST \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"survey_id":"uuid","responses":[{"question_id":"q1","value":8}]}' \
  https://wellpulse.org/api/public/v1.php?endpoint=responses
            

JavaScript Example

const apiKey = 'your_api_key_here';
const baseUrl = 'https://wellpulse.org/api/public/v1.php';

// Get surveys
fetch(`${baseUrl}?endpoint=surveys`, {
  headers: {
    'X-API-Key': apiKey
  }
})
.then(response => response.json())
.then(data => console.log(data));

// Submit response
fetch(`${baseUrl}?endpoint=responses`, {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    survey_id: 'uuid-here',
    responses: [
      { question_id: 'q1', value: 8 }
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data));
            

Support

For API support, please contact us through your dashboard or email support@wellpulse.org

Wellness Pulse API Documentation