OWC

API Documentation

Base URL is deployment-specific.

GET /

• Purpose: health check
• Headers: none
• Request body: none
• Success: 200 with message
• Side effects: none

GET /categories

• Purpose: list categories
• Headers: none
• Query params: none
• Success: 200 list of categories
• DB: reads categories

GET /questions

• Purpose: list active survey questions
• Headers: none
• Query params: none
• Success: 200 list of questions
• DB: reads survey_questions

POST /generate-token

• Purpose: create verification token and email it
• Headers: Content-Type application/json
• Request body:
  • email_address: string
  • company: string
  • city: string
• Success: 200 with token and message
• Error: 500 generic failure
• Side effects:
  • creates/updates company
  • creates/updates location
  • creates verification_requests row
  • attempts email send

POST /validate-token

• Purpose: validate token and create linked submission
• Headers: Content-Type application/json
• Request body:
  • token: string
• Success: 200 with success/message/redirect_url
• Error: 500 generic failure
• Side effects:
  • updates verification status/timestamps
  • creates submission if missing

POST /submit-survey

• Purpose: store survey responses and category weighted results
• Headers: Content-Type application/json
• Request body:
  • submissionId or recordId
  • mainConsent, sensitiveDataConsent, researchConsent
  • responses[]: { questionId, value }
• Success: 200 with submission_id
• Error: 500 generic failure
• Side effects:
  • upserts survey_responses
  • marks submission submitted

GET /submissions/{submission_id}/score

• Purpose: compute and return weighted score output
• Path params:
  • submission_id: integer
• Success: 200 with overall/category scores and completion percentage
• Notes:
  • uses the same scoring computation as POST /submissions/{submission_id}/calculate-results
  • returns overall_score_0_to_10 derived from normalized score: overall_score_0_to_100 / 10
  • endpoint is read-only (no aggregate writes)
• Errors:
  • 404 if no scored answers
• Side effects: none