{ "openapi": "3.0.2", "paths": { "/v1/echo/groups": { "get": { "summary": "Get a list of all existing groups in the system", "tags": [ "Groups" ], "parameters": [ { "name": "tenant", "in": "header", "description": "Tenant URL identifier.", "required": true, "schema": { "example": "acme.wellnomics.com", "type": "string" } } ], "operationId": "getGroups", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupData" } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [ { "id": 1, "groupType": 1, "groupCategory": 1, "groupAccess": 1, "name": "John Dory", "userGroupCategory": "Organisation" }, { "id": 2, "groupType": 1, "groupCategory": 1, "groupAccess": 1, "name": "Anaru Puta", "userGroupCategory": "Organisation" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "500": { "description": "Application Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } } }, "x-codeSamples": [ { "lang": "PowerShell", "label": "PowerShell", "source": "# Windows PowerShell 5.1 and PowerShell 7+\n[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12\n\n$headers = @{\n Authorization = \"Bearer $env:WELLNOMICS_API_TOKEN\"\n tenant = \"acme.wellnomics.com\"\n}\n\n$response = Invoke-RestMethod -Method GET `\n -Uri 'https://api.your-region.wellnomics.com/v1/echo/groups' `\n -Headers $headers\n\n$response | ConvertTo-Json -Depth 8" }, { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.your-region.wellnomics.com/v1/echo/groups' \\\n -H \"Authorization: Bearer $WELLNOMICS_API_TOKEN\" \\\n -H 'tenant: acme.wellnomics.com'" } ] } }, "/v1/echo/groups/{groupId}/reports": { "get": { "summary": "Get a list of the management reporting data of each user of the given group", "tags": [ "Reports" ], "parameters": [ { "name": "groupId", "in": "path", "description": "The group ID", "required": true, "schema": { "example": "1", "type": "string" } }, { "name": "tenant", "in": "header", "description": "Tenant URL identifier.", "required": true, "schema": { "example": "acme.wellnomics.com", "type": "string" } }, { "name": "limit", "in": "query", "description": "The number of items in the response", "required": true, "schema": { "example": 100, "type": "integer", "exclusiveMinimum": true, "maximum": 2000, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "The number of items to offset", "required": true, "schema": { "example": 0, "type": "integer", "minimum": 0 } } ], "operationId": "getReports", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Group report data", "type": "object", "properties": { "groupReport": { "type": "array", "items": { "$ref": "#/components/schemas/ReportData" } } }, "required": [ "groupReport" ], "additionalProperties": false }, "totalCount": { "example": 1, "description": "The total number of reporting data", "type": "number" } }, "required": [ "data", "totalCount" ], "additionalProperties": false }, "example": { "data": { "groupReport": [ { "id": 1, "uniqueId": "jdory", "firstName": "John", "lastName": "Doe", "accountCreated": "2025-11-03T21:14:07.000Z", "firstSync": "2025-11-04T08:02:55.000Z", "lastSync": "2026-08-21T18:41:09.000Z", "clientVersion": "5.4.0.219", "dataDate": "2026-08-21T00:00:00.000Z", "reportData": { "overallWellbeing": { "rating": "Good", "score": 1 }, "computerUse": { "rating": "Good", "score": 1 }, "breaks": { "rating": "Good", "score": 1 }, "sitStand": { "rating": "Good", "score": 1 } } }, { "id": 2, "uniqueId": "aputa", "firstName": "Anaru", "lastName": "Puta", "accountCreated": "2025-11-03T21:14:07.000Z", "firstSync": "2025-11-04T08:02:55.000Z", "lastSync": "2026-08-21T18:41:09.000Z", "clientVersion": "5.4.0.219", "dataDate": "2026-08-21T00:00:00.000Z", "reportData": { "overallWellbeing": { "rating": "Good", "score": 1 }, "computerUse": { "rating": "Good", "score": 1 }, "breaks": { "rating": "Good", "score": 1 }, "sitStand": { "rating": "Good", "score": 1 } } } ] }, "totalCount": 1 } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "500": { "description": "Application Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } } }, "x-codeSamples": [ { "lang": "PowerShell", "label": "PowerShell", "source": "# Windows PowerShell 5.1 and PowerShell 7+\n[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12\n\n$headers = @{\n Authorization = \"Bearer $env:WELLNOMICS_API_TOKEN\"\n tenant = \"acme.wellnomics.com\"\n}\n\n$response = Invoke-RestMethod -Method GET `\n -Uri 'https://api.your-region.wellnomics.com/v1/echo/groups/1/reports?limit=100&offset=0' `\n -Headers $headers\n\n$response | ConvertTo-Json -Depth 8" }, { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.your-region.wellnomics.com/v1/echo/groups/1/reports?limit=100&offset=0' \\\n -H \"Authorization: Bearer $WELLNOMICS_API_TOKEN\" \\\n -H 'tenant: acme.wellnomics.com'" } ] } }, "/v1/echo/groups/{groupId}/ergonomics-report": { "get": { "summary": "Get a list of the office ergonomics reporting data of each user of the given group", "deprecated": true, "tags": [ "Ergonomics" ], "parameters": [ { "name": "groupId", "in": "path", "description": "The group ID", "required": true, "schema": { "example": "1", "type": "string" } }, { "name": "tenant", "in": "header", "description": "Tenant URL identifier.", "required": true, "schema": { "example": "acme.wellnomics.com", "type": "string" } }, { "name": "limit", "in": "query", "description": "The number of items in the response", "required": true, "schema": { "example": 100, "type": "integer", "exclusiveMinimum": true, "maximum": 2000, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "The number of items to offset", "required": true, "schema": { "example": 0, "type": "integer", "minimum": 0 } } ], "operationId": "getofficeErgonomicsReport", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Group office ergonomics report data", "type": "array", "items": { "$ref": "#/components/schemas/GroupOfficeErgonomicsReportData" } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [ { "userId": 1, "uniqueId": "jdory", "name": "John Dory", "email": "jdory@example.com", "assessments": [ { "type": "Discomfort", "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "expiryDate": "2027-01-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "expired": false, "hasEverCompleted": true }, { "type": "Discomfort", "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "expiryDate": "2027-01-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "expired": false, "hasEverCompleted": true } ], "training": { "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "hasEverCompleted": true } }, { "userId": 2, "uniqueId": "aputa", "name": "Anaru Puta", "email": "aputa@example.com", "assessments": [ { "type": "Discomfort", "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "expiryDate": "2027-01-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "expired": false, "hasEverCompleted": true }, { "type": "Discomfort", "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "expiryDate": "2027-01-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "expired": false, "hasEverCompleted": true } ], "training": { "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "hasEverCompleted": true } } ] } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "500": { "description": "Application Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } } }, "description": "**Deprecated.** This endpoint returns assessments and training together and cannot be filtered. Replace it with `GET /v1/echo/groups/{groupId}/ergonomics-assessments-reports` for assessments and `GET /v1/echo/groups/{groupId}/ergonomics-training-reports` for training. The replacements return the same fields, add `totalCount` for pagination, and accept filters so you can ask for only the records you need. It remains available for existing integrations; new work should not use it.", "x-codeSamples": [ { "lang": "PowerShell", "label": "PowerShell", "source": "# Windows PowerShell 5.1 and PowerShell 7+\n[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12\n\n$headers = @{\n Authorization = \"Bearer $env:WELLNOMICS_API_TOKEN\"\n tenant = \"acme.wellnomics.com\"\n}\n\n$response = Invoke-RestMethod -Method GET `\n -Uri 'https://api.your-region.wellnomics.com/v1/echo/groups/1/ergonomics-report?limit=100&offset=0' `\n -Headers $headers\n\n$response | ConvertTo-Json -Depth 8" }, { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.your-region.wellnomics.com/v1/echo/groups/1/ergonomics-report?limit=100&offset=0' \\\n -H \"Authorization: Bearer $WELLNOMICS_API_TOKEN\" \\\n -H 'tenant: acme.wellnomics.com'" } ] } }, "/v1/echo/groups/{groupId}/ergonomics-assessments-reports": { "get": { "summary": "Get a list of the office ergonomics assessments reporting data of each user of the given group", "tags": [ "Ergonomics" ], "parameters": [ { "name": "groupId", "in": "path", "description": "The group ID", "required": true, "schema": { "example": "1", "type": "string" } }, { "name": "tenant", "in": "header", "description": "Tenant URL identifier.", "required": true, "schema": { "example": "acme.wellnomics.com", "type": "string" } }, { "name": "limit", "in": "query", "description": "The number of items in the response", "required": true, "schema": { "example": 100, "type": "integer", "exclusiveMinimum": true, "maximum": 2000, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "The number of items to offset", "required": true, "schema": { "example": 0, "type": "integer", "minimum": 0 } }, { "name": "type", "in": "query", "description": "Filter by assessment type(s). If omitted, all types included.", "required": true, "schema": { "example": "PostureAndWorkstation", "type": "string" } }, { "name": "hasEverCompleted", "in": "query", "description": "Filter by assessment completion status.", "schema": { "example": true, "type": "boolean" } }, { "name": "overdue", "in": "query", "description": "Filter by assessment overdue status.", "schema": { "example": true, "type": "boolean" } }, { "name": "expired", "in": "query", "description": "Filter by assessment expiry status.", "schema": { "example": false, "type": "boolean" } }, { "name": "enabled", "in": "query", "description": "Filter by assessment enabled status.", "schema": { "example": true, "type": "boolean" } }, { "name": "includeOnDemandAssessments", "in": "query", "description": "Defaulting to false, filters whether onDemand assessments should be presented in the report. If onDemand assessments are not presented in the report it will be treated as if users have not done that onDemand assessment", "schema": { "example": true, "type": "boolean" } }, { "name": "lastCompletedDate.before", "in": "query", "description": "Optional ISO date to filter lastCompletedDate by. If provided, will limit results to all those with a last completed date prior to this.", "schema": { "type": "string", "format": "date", "example": "2026-01-28" } }, { "name": "lastCompletedDate.after", "in": "query", "description": "Optional ISO date to filter lastCompletedDate by. If provided, will limit results to all those with a last completed date after to this.", "schema": { "type": "string", "format": "date", "example": "2026-01-28" } }, { "name": "lastCompletedDate.isNull", "in": "query", "description": "Optional boolean to filter lastCompletedDate by. If provided, will limit results to all those with a null last completed date when true, and all those with a non-null last completed date when false.", "schema": { "type": "boolean", "example": true } } ], "operationId": "getErgonomicsAssessmentsReports", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Group office ergonomics assessments reports data ", "type": "array", "items": { "$ref": "#/components/schemas/GroupOfficeErgonomicsAssessmentsReportData" } }, "totalCount": { "type": "number", "description": "Pagination meta-data counting all records available before pagination filters are applied" } }, "required": [ "data", "totalCount" ], "additionalProperties": false }, "example": { "data": [ { "userId": 1, "uniqueId": "jdory", "name": "John Dory", "email": "jdory@example.com", "assessments": [ { "type": "Discomfort", "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "expiryDate": "2027-01-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "onDemand": false, "expired": false, "hasEverCompleted": true }, { "type": "Discomfort", "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "expiryDate": "2027-01-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "onDemand": false, "expired": false, "hasEverCompleted": true } ] }, { "userId": 2, "uniqueId": "aputa", "name": "Anaru Puta", "email": "aputa@example.com", "assessments": [ { "type": "Discomfort", "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "expiryDate": "2027-01-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "onDemand": false, "expired": false, "hasEverCompleted": true }, { "type": "Discomfort", "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "expiryDate": "2027-01-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "onDemand": false, "expired": false, "hasEverCompleted": true } ] } ], "totalCount": 47 } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "500": { "description": "Application Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } } }, "x-codeSamples": [ { "lang": "PowerShell", "label": "PowerShell", "source": "# Windows PowerShell 5.1 and PowerShell 7+\n[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12\n\n$headers = @{\n Authorization = \"Bearer $env:WELLNOMICS_API_TOKEN\"\n tenant = \"acme.wellnomics.com\"\n}\n\n$response = Invoke-RestMethod -Method GET `\n -Uri 'https://api.your-region.wellnomics.com/v1/echo/groups/1/ergonomics-assessments-reports?limit=100&offset=0&type=PostureAndWorkstation' `\n -Headers $headers\n\n$response | ConvertTo-Json -Depth 8" }, { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.your-region.wellnomics.com/v1/echo/groups/1/ergonomics-assessments-reports?limit=100&offset=0&type=PostureAndWorkstation' \\\n -H \"Authorization: Bearer $WELLNOMICS_API_TOKEN\" \\\n -H 'tenant: acme.wellnomics.com'" } ] } }, "/v1/echo/groups/{groupId}/ergonomics-training-reports": { "get": { "summary": "Get a list of the ergonomics training reporting data of each user of the given group", "tags": [ "Ergonomics" ], "parameters": [ { "name": "groupId", "in": "path", "description": "The group ID", "required": true, "schema": { "example": "1", "type": "string" } }, { "name": "tenant", "in": "header", "description": "Tenant URL identifier.", "required": true, "schema": { "example": "acme.wellnomics.com", "type": "string" } }, { "name": "limit", "in": "query", "description": "The number of items in the response", "required": true, "schema": { "example": 100, "type": "integer", "exclusiveMinimum": true, "maximum": 2000, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "The number of items to offset", "required": true, "schema": { "example": 0, "type": "integer", "minimum": 0 } }, { "name": "hasEverCompleted", "in": "query", "description": "If provided, will filter reports to users who have completed training at least once when true and users who have never completed training when false.", "schema": { "type": "boolean" } }, { "name": "overdue", "in": "query", "description": "If provided, will filter reports to those with a matching true/false overdue status.", "schema": { "type": "boolean", "example": true } }, { "name": "enabled", "in": "query", "description": "If provided, will filter reports to those with a matching true/false enabled status.", "schema": { "type": "boolean", "example": true } }, { "name": "lastCompletedDate.before", "in": "query", "description": "Optional ISO date to filter lastCompletedDate by. If provided, will filter reports to all those with a last completed date prior.", "schema": { "type": "string", "format": "date", "example": "2026-01-28" } }, { "name": "lastCompletedDate.after", "in": "query", "description": "Optional ISO date to filter lastCompletedDate by. If provided, will filter reports to all those with a last completed date after.", "schema": { "type": "string", "format": "date", "example": "2026-01-28" } }, { "name": "lastCompletedDate.isNull", "in": "query", "description": "Optional boolean to filter lastCompletedDate by. If provided, will filter reports to all those with a null last completed date when true, and all those with a non-null last completed date when false.", "schema": { "type": "boolean", "example": true } } ], "operationId": "getErgonomicsTrainingReports", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Group ergonomics training report data", "type": "array", "items": { "$ref": "#/components/schemas/GroupErgonomicsTrainingReportData" } }, "totalCount": { "type": "number", "description": "Pagination meta-data counting all records available before pagination filters are applied" } }, "required": [ "data", "totalCount" ], "additionalProperties": false }, "example": { "data": [ { "userId": 1, "uniqueId": "jdory", "name": "John Dory", "email": "jdory@example.com", "training": { "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "hasEverCompleted": true } }, { "userId": 2, "uniqueId": "aputa", "name": "Anaru Puta", "email": "aputa@example.com", "training": { "enabled": true, "dueDate": "2026-09-15T00:00:00.000Z", "scheduledDate": "2026-07-14T09:00:00.000Z", "lastCompletedDate": "2026-07-14T09:32:11.000Z", "overdue": false, "hasEverCompleted": true } } ], "totalCount": 47 } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "500": { "description": "Application Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } } }, "x-codeSamples": [ { "lang": "PowerShell", "label": "PowerShell", "source": "# Windows PowerShell 5.1 and PowerShell 7+\n[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12\n\n$headers = @{\n Authorization = \"Bearer $env:WELLNOMICS_API_TOKEN\"\n tenant = \"acme.wellnomics.com\"\n}\n\n$response = Invoke-RestMethod -Method GET `\n -Uri 'https://api.your-region.wellnomics.com/v1/echo/groups/1/ergonomics-training-reports?limit=100&offset=0' `\n -Headers $headers\n\n$response | ConvertTo-Json -Depth 8" }, { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.your-region.wellnomics.com/v1/echo/groups/1/ergonomics-training-reports?limit=100&offset=0' \\\n -H \"Authorization: Bearer $WELLNOMICS_API_TOKEN\" \\\n -H 'tenant: acme.wellnomics.com'" } ] } } }, "info": { "title": "Customer Reporting API", "version": "5.5.0", "contact": { "name": "Wellnomics Support", "email": "support@wellnomics.com" }, "description": "Read-only reporting API for wellbeing and office-ergonomics data, organised by group.\n\n## Boolean query parameters — write resilient code\n\nFilters such as `overdue`, `enabled`, `expired` and `hasEverCompleted` travel as query string values.\n\n**Send lowercase `true` or `false`.** That is what this specification declares and what every client library produces correctly.\n\nThe server is more forgiving than that, and will stay so: values are matched case-insensitively, and `1`/`0`, `yes`/`no`, `on`/`off`, `y`/`n` and `enabled`/`disabled` are all accepted. You do not need to normalise case before sending. This matters because .NET and Python capitalise by default — `bool.ToString()` and `str(True)` both give `True` — so the natural idiom in those languages works as-is. Anything outside those sets is rejected with a `400`.\n\nOne thing to build for:\n\n**Omitting a filter is not the same as sending it empty.** `?overdue=` is a `400`, not \"no filter\". Leave the parameter out of the query string entirely when you do not want to filter on it. Watch for this when you build URLs by string concatenation from optional values — an unset variable easily becomes an empty parameter rather than an absent one.\n\n## Base URL\n\nThe API is served from the regional server that hosts your site, not from the address you sign in at, so the two are different hostnames. Ask Wellnomics Support for your base URL; it is fixed for your site and does not change.\n\nThe `tenant` header is a separate value: the hostname you sign in at, for example `acme.wellnomics.com`.\n\n## Authentication\n\nEvery request needs two headers:\n\n| Header | Value |\n| --- | --- |\n| `Authorization` | `Bearer ` |\n| `tenant` | Your site hostname, e.g. `acme.wellnomics.com` |\n\nThe `tenant` header selects which customer database the request runs against. It is resolved before authentication, so a missing or unknown `tenant` fails the request even when the token is perfectly valid.\n\nCreate tokens in your Wellbeing site under **Admin -> API access tokens**, choosing the **Customer Reporting** token type. The token is shown once, at creation. Tokens can be given a lifetime of 1, 7, 30, 90 or 180 days, or no expiry at all; they can be revoked at any time from the same screen.\n\nTreat the token as a credential with organisation-wide read access to your reporting data. Store it in a secret manager or an environment variable, never in source control, and rotate it on a schedule.\n\n## Pagination\n\n`limit` and `offset` are **required** on every reporting endpoint. `limit` accepts 1 to 2000. Responses that paginate also return `totalCount`, which is the number of records before pagination is applied - use it to decide whether to fetch another page.\n\n`GET /v1/echo/groups` is not paginated and returns every group in one response.\n\n## Dates and times\n\nAll dates are ISO 8601 UTC timestamps, for example `2026-07-14T09:00:00.000Z`. Convert to local time in your own system. Date filters such as `lastCompletedDate.before` take a plain `YYYY-MM-DD` date.\n\n## Errors\n\nErrors use a problem-detail body: `status`, `title`, `details` and `type`.\n\n| Status | Means | What to do |\n| --- | --- | --- |\n| 400 | The query is invalid, or the `tenant` header is missing or unrecognised | Fix the query, or check the `tenant` header. `limit` must be 1-2000 |\n| 401 | Missing, malformed, expired or revoked token | If the token expired, create a new one |\n| 403 | The site licence is not active, or the token lacks the required right | Contact Wellnomics Support |\n| 404 | The group does not exist on this site | Re-read `GET /v1/echo/groups` |\n| 500 | Server-side failure | Retry with backoff, then contact Wellnomics Support |\n\nAn unrecognised `tenant` fails as a 400 before authentication runs, so a token problem and a tenant problem give different status codes.\n\n## The \"Me\" group\n\nEvery user has a personal \"Me\" group. These are excluded from `GET /v1/echo/groups`, and asking for a report on one returns 400. Report on real teams and groups only.", "license": { "name": "Wellnomics customer licence agreement", "url": "https://www.wellnomics.com/terms/" } }, "servers": [ { "url": "https://{apiHost}", "description": "The regional server that hosts your site. Wellnomics Support will give you the hostname.", "variables": { "apiHost": { "default": "api.your-region.wellnomics.com", "description": "The API hostname for the regional server that hosts your site. Wellnomics Support will give you this; it cannot be worked out from the address you sign in at." } } } ], "components": { "schemas": { "GroupData": { "title": "Group Data", "description": "Information about the group", "type": "object", "properties": { "id": { "description": "The ID of the group", "example": 1, "type": "number" }, "groupType": { "description": "The type of the group", "example": 1, "type": "number" }, "groupCategory": { "description": "The category of the group", "example": 1, "type": "number" }, "groupAccess": { "description": "The access type of the group", "example": 1, "type": "number" }, "name": { "description": "The name of the group", "example": "John Dory", "type": "string" }, "userGroupCategory": { "description": "The user category of the group", "example": "Organisation", "type": "string" } }, "required": [ "id", "groupType", "groupCategory", "groupAccess", "name", "userGroupCategory" ], "additionalProperties": false }, "Unauthorized": { "title": "Unauthorized", "description": "Unauthorized", "example": { "status": 401, "type": null, "title": "API Key Error", "details": "API key is invalid" }, "type": "object", "properties": { "status": { "type": "number", "enum": [ 401 ] }, "title": { "type": "string" }, "details": { "type": "string" }, "type": { "nullable": true, "type": "string" } }, "required": [ "status", "title", "details", "type" ], "additionalProperties": false }, "Forbidden": { "title": "Forbidden", "description": "Forbidden", "example": { "status": 403, "type": "tag:LicenseNotValid", "title": "License is not valid", "details": "The license is inactive" }, "type": "object", "properties": { "status": { "type": "number", "enum": [ 403 ] }, "title": { "type": "string" }, "details": { "type": "string" }, "type": { "nullable": true, "type": "string" } }, "required": [ "status", "title", "details", "type" ], "additionalProperties": false }, "ApplicationError": { "title": "Application Error", "description": "Application Error", "example": { "status": 500, "type": null, "title": "An error has occured", "details": "The server has failed, contact support to report the issue" }, "type": "object", "properties": { "status": { "type": "number", "enum": [ 500 ] }, "title": { "type": "string" }, "details": { "type": "string" }, "type": { "nullable": true, "type": "string" } }, "required": [ "status", "title", "details", "type" ], "additionalProperties": false }, "ReportData": { "title": "Report Data", "description": "Information about the report", "type": "object", "properties": { "id": { "description": "The ID of the user", "example": 1, "type": "number" }, "uniqueId": { "description": "The unique ID of the user", "example": "jdory", "type": "string" }, "firstName": { "description": "The first name of the user", "example": "John", "type": "string" }, "lastName": { "description": "The last name of the user", "example": "Doe", "type": "string" }, "accountCreated": { "description": "The date the account was created", "example": "2025-11-03T21:14:07.000Z", "type": "string", "format": "date-time" }, "firstSync": { "description": "The date the data was first synced", "example": "2025-11-04T08:02:55.000Z", "nullable": true, "type": "string", "format": "date-time" }, "lastSync": { "description": "The date the data was last synced", "example": "2026-08-21T18:41:09.000Z", "nullable": true, "type": "string", "format": "date-time" }, "clientVersion": { "description": "The client version", "example": "5.4.0.219", "nullable": true, "type": "string" }, "dataDate": { "description": "The date the data was recorded", "example": "2026-08-21T00:00:00.000Z", "type": "string", "format": "date-time" }, "reportData": { "description": "The report data", "type": "object", "properties": { "overallWellbeing": { "type": "object", "properties": { "rating": { "description": "The category rating", "example": "Good", "type": "string" }, "score": { "description": "The category score", "example": 1, "type": "number" } }, "required": [ "rating", "score" ], "additionalProperties": false }, "computerUse": { "type": "object", "properties": { "rating": { "description": "The category rating", "example": "Good", "type": "string" }, "score": { "description": "The category score", "example": 1, "type": "number" } }, "required": [ "rating", "score" ], "additionalProperties": false }, "breaks": { "type": "object", "properties": { "rating": { "description": "The category rating", "example": "Good", "type": "string" }, "score": { "description": "The category score", "example": 1, "type": "number" } }, "required": [ "rating", "score" ], "additionalProperties": false }, "sitStand": { "type": "object", "properties": { "rating": { "description": "The category rating", "example": "Good", "type": "string" }, "score": { "description": "The category score", "example": 1, "type": "number" } }, "required": [ "rating", "score" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "id", "uniqueId", "firstName", "lastName", "accountCreated", "firstSync", "lastSync", "clientVersion", "dataDate", "reportData" ], "additionalProperties": false }, "BadRequest": { "title": "Bad Request", "description": "Invalid query", "example": { "status": 400, "type": null, "title": "Request query invalid", "details": "Limit and offset must be a valid number" }, "type": "object", "properties": { "status": { "type": "number", "enum": [ 400 ] }, "title": { "type": "string" }, "details": { "type": "string" }, "type": { "nullable": true, "type": "string" } }, "required": [ "status", "title", "details", "type" ], "additionalProperties": false }, "NotFound": { "title": "Not Found", "description": "Not Found", "example": { "status": 404, "type": null, "title": "Resource not found", "details": "Requested resource could not be found" }, "type": "object", "properties": { "status": { "type": "number", "enum": [ 404 ] }, "title": { "type": "string" }, "details": { "type": "string" }, "type": { "nullable": true, "type": "string" } }, "required": [ "status", "title", "details", "type" ], "additionalProperties": false }, "GroupOfficeErgonomicsReportData": { "title": "Group office ergonomics report data", "description": "Information about the group office ergonomics reporting data", "type": "object", "properties": { "userId": { "description": "The ID of the user", "example": 1, "type": "number" }, "uniqueId": { "description": "The unique ID of the user", "example": "jdory", "type": "string" }, "name": { "description": "The user's first and last names", "example": "John Dory", "type": "string" }, "email": { "description": "The user's email address", "example": "jdory@example.com", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "assessments": { "description": "Array of user assessments reporting data, there will be one for each type of assessment the user has", "type": "array", "items": { "description": "User assessment reporting data", "type": "object", "properties": { "type": { "description": "The type of assessment", "example": "Discomfort", "type": "string", "enum": [ "PostureAndWorkstation", "Individual", "Discomfort", "WorkEnvironment" ] }, "enabled": { "description": "Whether or not the assessment is enabled for the user", "example": true, "type": "boolean" }, "dueDate": { "description": "The date the assessment is due to be completed by", "example": "2026-09-15T00:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "scheduledDate": { "description": "The date the assessment was scheduled", "example": "2026-07-14T09:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "expiryDate": { "description": "The date the assessment expires", "example": "2027-01-14T09:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "lastCompletedDate": { "description": "The date the assessment was last completed", "example": "2026-07-14T09:32:11.000Z", "nullable": true, "type": "string", "format": "date-time" }, "overdue": { "description": "Whether or not the assessment is overdue for the user", "example": false, "type": "boolean" }, "expired": { "description": "Whether or not the assessment has expired", "example": false, "type": "boolean" }, "hasEverCompleted": { "description": "Whether or not the user has ever completed an assessment of this type", "example": true, "type": "boolean" } }, "required": [ "type", "enabled", "dueDate", "scheduledDate", "expiryDate", "lastCompletedDate", "overdue", "expired", "hasEverCompleted" ], "additionalProperties": false } }, "training": { "description": "User training reporting data", "type": "object", "properties": { "enabled": { "description": "Whether or not the training is enabled for the user", "example": true, "type": "boolean" }, "dueDate": { "description": "The date the training is due to be completed by", "example": "2026-09-15T00:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "scheduledDate": { "description": "The date the training was scheduled", "example": "2026-07-14T09:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "lastCompletedDate": { "description": "The date the training was last completed", "example": "2026-07-14T09:32:11.000Z", "nullable": true, "type": "string", "format": "date-time" }, "overdue": { "description": "Whether or not the training is overdue for the user", "example": false, "type": "boolean" }, "hasEverCompleted": { "description": "Whether or not the user has ever completed a training", "example": true, "type": "boolean" } }, "required": [ "enabled", "dueDate", "scheduledDate", "lastCompletedDate", "overdue", "hasEverCompleted" ], "additionalProperties": false } }, "required": [ "userId", "uniqueId", "name", "email", "assessments" ], "additionalProperties": false }, "GroupOfficeErgonomicsAssessmentsReportData": { "title": "Group office ergonomics assessments report data", "description": "Information about the group office ergonomics assessments reporting data", "type": "object", "properties": { "userId": { "description": "The ID of the user", "example": 1, "type": "number" }, "uniqueId": { "description": "The unique ID of the user", "example": "jdory", "type": "string" }, "name": { "description": "The user's first and last names", "example": "John Dory", "type": "string" }, "email": { "description": "The user's email address", "example": "jdory@example.com", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "assessments": { "description": "Array containing the user's assessments reporting data. There will be a report for each type of assessment the user has completed", "type": "array", "items": { "description": "User assessment reporting data", "type": "object", "properties": { "type": { "description": "The type of assessment", "example": "Discomfort", "type": "string", "enum": [ "PostureAndWorkstation", "Individual", "Discomfort", "WorkEnvironment" ] }, "enabled": { "description": "Whether or not the assessment is enabled for the user", "example": true, "type": "boolean" }, "dueDate": { "description": "The date the assessment is due to be completed by", "example": "2026-09-15T00:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "scheduledDate": { "description": "The date the assessment was scheduled for the user by their manager", "example": "2026-07-14T09:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "expiryDate": { "description": "The date the assessment expires, i.e. the date it should be completed by", "example": "2027-01-14T09:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "lastCompletedDate": { "description": "The date the assessment was last completed", "example": "2026-07-14T09:32:11.000Z", "nullable": true, "type": "string", "format": "date-time" }, "overdue": { "description": "Whether or not the assessment is overdue for the user", "example": false, "type": "boolean" }, "onDemand": { "description": "Whether or not the assessment was scheduled for the user, or the user self-initiated the assessment", "example": false, "nullable": true, "type": "boolean" }, "expired": { "description": "Whether or not the assessment has expired", "example": false, "type": "boolean" }, "hasEverCompleted": { "description": "Whether or not the user has ever completed an assessment of this type", "example": true, "type": "boolean" } }, "required": [ "type", "enabled", "dueDate", "scheduledDate", "expiryDate", "lastCompletedDate", "overdue", "onDemand", "expired", "hasEverCompleted" ], "additionalProperties": false } } }, "required": [ "userId", "uniqueId", "name", "email", "assessments" ], "additionalProperties": false }, "GroupErgonomicsTrainingReportData": { "title": "Group ergonomics training report data", "description": "Information about the group office ergonomics reporting data", "type": "object", "properties": { "userId": { "description": "The ID of the user", "example": 1, "type": "number" }, "uniqueId": { "description": "The unique ID of the user", "example": "jdory", "type": "string" }, "name": { "description": "The user's first and last name", "example": "John Dory", "type": "string" }, "email": { "description": "The user's email address", "example": "jdory@example.com", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "training": { "description": "User training reporting data", "type": "object", "properties": { "enabled": { "description": "Whether or not the training is enabled for the user", "example": true, "type": "boolean" }, "dueDate": { "description": "The date the training is due to be completed by", "example": "2026-09-15T00:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "scheduledDate": { "description": "The date the training was scheduled", "example": "2026-07-14T09:00:00.000Z", "nullable": true, "type": "string", "format": "date-time" }, "lastCompletedDate": { "description": "The date the training was last completed", "example": "2026-07-14T09:32:11.000Z", "nullable": true, "type": "string", "format": "date-time" }, "overdue": { "description": "Whether or not the training is overdue for the user", "example": false, "type": "boolean" }, "hasEverCompleted": { "description": "Whether or not the user has ever completed a training", "example": true, "type": "boolean" } }, "required": [ "enabled", "dueDate", "scheduledDate", "lastCompletedDate", "overdue", "hasEverCompleted" ], "additionalProperties": false } }, "required": [ "userId", "uniqueId", "name", "email", "training" ], "additionalProperties": false } }, "securitySchemes": { "BearerAuth": { "description": "Bearer authentication to access any endpoint on this API", "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Ergonomics", "description": "Assessment and training status per person: what is scheduled, completed, overdue or expired. Filterable, so you can ask for just the exceptions." }, { "name": "Groups", "description": "Look up the teams and groups in your organisation. Start here to find the group ID the reporting calls need." }, { "name": "Reports", "description": "Wellbeing reporting: a per-person rating and score across overall wellbeing, computer use, breaks and sit-stand behaviour." } ], "security": [ { "BearerAuth": [] } ] }