{ "openapi": "3.1.0", "paths": { "/health": { "get": { "description": "Returns the health status of the API and its dependencies", "operationId": "healthCheck", "parameters": [], "responses": { "200": { "description": "The Health Check is successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "info": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "error": { "type": "object", "example": {}, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "details": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true } } } } } } }, "503": { "description": "The Health Check is not successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "info": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "error": { "type": "object", "example": { "redis": { "status": "down", "message": "Could not connect" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "details": { "type": "object", "example": { "database": { "status": "up" }, "redis": { "status": "down", "message": "Could not connect" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true } } } } } } } }, "summary": "Health check", "tags": [ "Health" ], "security": [] } }, "/platform-settings/feature-flags/{key}": { "get": { "operationId": "getFeatureFlag", "parameters": [ { "name": "key", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolved feature flag value for the tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureFlagResponseDto" } } } }, "400": { "description": "The key is not one of the accepted feature-flag keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Unknown feature flag key", "error": "PLATFORM_SETTING_UNKNOWN_FLAG_KEY" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Get tenant feature flag value", "tags": [ "Feature Flags" ] } }, "/individuals/resolve": { "post": { "description": "Find or create an individual by email or HRIS ID within the tenant context", "operationId": "resolveIdentity", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIndividualDto" } } } }, "responses": { "200": { "description": "Individual resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIndividualResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "409": { "description": "Email and HRIS ID resolve to different individuals (IDENTITY_RESOLUTION_CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "summary": "Resolve individual", "tags": [ "Colleagues & Profiles" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/company-individuals": { "post": { "description": "Link an individual to the current company with a role and relationship type", "operationId": "createCompanyIndividual", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompanyIndividualDto" } } } }, "responses": { "201": { "description": "Company-individual relationship created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIndividualResponseDto" } } } }, "400": { "description": "Validation error in request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "409": { "description": "Duplicate relationship (IDENTITY_COMPANY_INDIVIDUAL_DUPLICATE) or duplicate HRIS id (IDENTITY_HRIS_ID_DUPLICATE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "A company-individual relationship already exists", "error": "IDENTITY_COMPANY_INDIVIDUAL_DUPLICATE" } } } } }, "summary": "Create company-individual", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] }, "get": { "description": "Return all individuals linked to the current company", "operationId": "listCompanyIndividuals", "parameters": [], "responses": { "200": { "description": "List of company-individual relationships", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyIndividualResponseDto" } } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "List company-individuals", "tags": [ "People Administration" ] } }, "/company-individuals/{id}": { "get": { "description": "Return a single company-individual relationship by ID", "operationId": "getCompanyIndividual", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company-individual relationship found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIndividualResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Company-individual not found (or hidden from the caller — no existence leak)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Company-individual not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } } }, "summary": "Get company-individual", "tags": [ "People Administration" ] }, "patch": { "description": "Update the relationship type or HRIS ID of a company-individual", "operationId": "updateCompanyIndividual", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyIndividualDto" } } } }, "responses": { "200": { "description": "Company-individual updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIndividualResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Company-individual not found (or hidden from the caller — no existence leak)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Company-individual not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "409": { "description": "Duplicate relationship (IDENTITY_COMPANY_INDIVIDUAL_DUPLICATE) or duplicate HRIS id (IDENTITY_HRIS_ID_DUPLICATE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "A company-individual relationship already exists", "error": "IDENTITY_COMPANY_INDIVIDUAL_DUPLICATE" } } } } }, "summary": "Update company-individual", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] }, "delete": { "description": "Remove an individual from the current company", "operationId": "deleteCompanyIndividual", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Company-individual deleted" }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "404": { "description": "Company-individual not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "summary": "Delete company-individual", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/filter-options": { "get": { "operationId": "listColleagueFilterOptions", "parameters": [], "responses": { "200": { "description": "Distinct departments and locations from active memberships", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColleagueFilterOptionsDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — viewer, admin, or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Get distinct active departments and locations", "tags": [ "Colleagues & Profiles" ], "x-badges": [ { "name": "Viewer" }, { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues": { "get": { "description": "Search, filter, sort and paginate colleagues. Viewers only see active profiles; status/segment filters are silently ignored for Viewers.", "operationId": "listColleagues", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 9007199254740991, "default": 1, "type": "integer" } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "integer" } }, { "name": "search", "required": false, "in": "query", "schema": { "minLength": 2, "type": "string" } }, { "name": "department", "required": true, "in": "query", "schema": { "default": [], "type": "array", "items": { "type": "string" } } }, { "name": "connectionPower", "required": true, "in": "query", "schema": { "default": [], "type": "array", "items": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ] } } }, { "name": "location", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "jobTitle", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ] } }, { "name": "managerId", "required": false, "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "me" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] } }, { "name": "segment", "required": false, "in": "query", "schema": { "default": "active", "type": "string", "enum": [ "active", "archived" ] } }, { "name": "archivedType", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "colleague", "candidate" ] } }, { "name": "sortBy", "required": false, "in": "query", "schema": { "default": "name", "type": "string", "enum": [ "name", "createdAt", "department" ] } }, { "name": "sortOrder", "required": false, "in": "query", "schema": { "default": "asc", "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "view", "required": false, "in": "query", "schema": { "default": "card", "type": "string", "enum": [ "card", "table" ] } } ], "responses": { "200": { "description": "Paginated list of colleagues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCompanyIndividualsResponseDto" } } } }, "400": { "description": "Validation error (e.g., search term < 2 characters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "List colleagues in the people directory", "tags": [ "Colleagues & Profiles" ], "x-badges": [ { "name": "Viewer" }, { "name": "Admin" }, { "name": "Owner" } ] }, "post": { "description": "Create a single colleague profile by email. Returns 201 on creation, 200 with reactivation offer for archived profiles, 409 for duplicates. A Partner API client that is the tenant's active `users` source of record calls the same operation, supplying `partnerReference`, `sourceVersion` and an optional `hrisId` instead of the human-entered `firstName`, `lastName`, `personalEmail`, `department`, `jobTitle` and `location` — each caller kind is rejected with a 400 if it sends the other kind's fields, and the role may never be supplied by either. For that Partner caller only, an `email` or `hrisId` resolving to an employee the tenant ALREADY has returns 200 with `classification: \"reconciled\"`: the reference is linked to that existing colleague, whose role, membership and creator provenance are all preserved, and nothing new is created. A human caller never receives that classification — a human create resolving to an existing active employee is still a 409 duplicate.", "operationId": "createColleague", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateColleagueDto" } } } }, "responses": { "200": { "description": "Archived profile found — reactivation offer returned (classification: \"reactivate\"); or, for a Partner API client, the existing colleague its reference was linked to (classification: \"reconciled\")", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReactivateColleagueOfferDto" }, { "$ref": "#/components/schemas/ReconciledColleagueResponseDto" } ] } } } }, "201": { "description": "Colleague profile created successfully (classification: \"created\")", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedColleagueResponseDto" } } } }, "400": { "description": "Validation error in request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required (AUTH_INSUFFICIENT_ROLE); for an API client, no active Grant carrying `users:w` on this tenant (AUTH_TENANT_NOT_GRANTED) or not the tenant's active `users` source of record (AUTH_SOURCE_OF_RECORD_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "409": { "description": "Already an employee of this tenant (DUPLICATE_EMAIL); the supplied reference, email and `hrisId` do not all name the same person (IDENTITY_RESOLUTION_CONFLICT); or this API client already holds a different reference for that employee (PARTNER_EMPLOYEE_REFERENCE_CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "A colleague with this email already exists", "error": "DUPLICATE_EMAIL" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Create a colleague profile", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/{id}/audit-log": { "get": { "description": "Returns paginated audit log entries for a colleague, sorted newest first. Each entry includes actor name, action verb, and field-level before/after changes.", "operationId": "getColleagueAuditLog", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 9007199254740991, "default": 1, "type": "integer" } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } } ], "responses": { "200": { "description": "Paginated audit log entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "404": { "description": "Colleague not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "summary": "Get audit log for a colleague", "tags": [ "Colleagues & Profiles" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/{id}": { "get": { "description": "Returns a full profile with identity, membership history, manager links, audit summary, and enrichment placeholders. personalEmail is included for Admin/Owner roles or when the caller reads their own record; a non-self Viewer gets null. **`{id}` is interpreted by CALLER KIND, never by the value's shape.** For a human caller it is the Thomas colleague id (a UUID) and the response is the profile detail above. For a Partner API client that is the tenant's active `users` source of record it is that client's OWN opaque `partnerReference`, resolved only within its own tenant/API-client namespace, and the response is the partner employee projection. The same opaque value under another API client or another tenant is a different colleague and is never returned. Partner references are opaque and may legitimately be UUID-shaped; that is why the caller kind, and not the value, selects the interpretation.", "operationId": "getColleague", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full colleague profile detail for a human caller; the partner employee projection for a Partner API client reading by its own reference", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CompanyIndividualDetailResponseDto" }, { "$ref": "#/components/schemas/PartnerEmployeeResponseDto" } ] } } } }, "400": { "description": "Invalid UUID format for id parameter, or malformed partner reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "For an API client: not the tenant's active `users` source of record (AUTH_SOURCE_OF_RECORD_REQUIRED), no active Grant carrying `users:r` on this tenant (AUTH_TENANT_NOT_GRANTED), or a caller whose kind this operation could not resolve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "API client is not the source of record for this data domain in this tenant", "error": "AUTH_SOURCE_OF_RECORD_REQUIRED" } } } }, "404": { "description": "Colleague not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND), or no colleague in this tenant/API-client namespace (PARTNER_EMPLOYEE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get colleague profile detail", "tags": [ "Colleagues & Profiles" ], "x-badges": [ { "name": "Viewer" }, { "name": "Admin" }, { "name": "Owner" } ] }, "patch": { "description": "Update organisational attributes (department, jobTitle, location) with an optional future effective date. Immediate edits close the current membership; future-dated edits create a pending row.", "operationId": "updateColleague", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditColleagueDto" } } } }, "responses": { "200": { "description": "Profile updated successfully with full detail response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIndividualDetailResponseDto" } } } }, "400": { "description": "Invalid UUID format or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Company-individual not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "422": { "description": "Invalid effective date (INVALID_EFFECTIVE_DATE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Invalid effective date", "error": "INVALID_EFFECTIVE_DATE" } } } } }, "summary": "Edit a colleague profile with optional effective dating", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/bulk/validate": { "post": { "description": "Classifies each row as ready, reactivate, or rejected. Read-only — no data is persisted.", "operationId": "bulkValidateColleagues", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkValidateRequestDto" } } } }, "responses": { "200": { "description": "Validation results with per-row classification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkValidateResponseDto" } } } }, "400": { "description": "Validation error (e.g., >100 rows, empty array)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Validate bulk colleague creation", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/bulk": { "post": { "description": "Atomically creates/reactivates confirmed rows. Re-validates inside transaction for race condition safety.", "operationId": "bulkCreateColleagues", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateRequestDto" } } } }, "responses": { "201": { "description": "Bulk creation results with per-row details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateResponseDto" } } } }, "400": { "description": "Validation error in request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Bulk create colleague profiles", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/{id}/reactivate": { "post": { "description": "Confirm reactivation of an archived colleague profile. Status determined by Account existence.", "operationId": "reactivateColleague", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactivateColleagueDto" } } } }, "responses": { "200": { "description": "Colleague reactivated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactivateColleagueResultDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required (AUTH_INSUFFICIENT_ROLE), or the organisation is seat-blocked (SEATS_BLOCKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Company-individual not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "409": { "description": "Company-individual is not archived (COLLEAGUE_NOT_ARCHIVED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Colleague is not archived", "error": "COLLEAGUE_NOT_ARCHIVED" } } } } }, "summary": "Reactivate an archived colleague", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/bulk/invite": { "post": { "description": "Invite up to 100 pending colleagues in a single operation. Returns 202 immediately — email delivery is async. Non-pending colleagues are skipped.", "operationId": "bulkInviteColleagues", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInviteDto" } } } }, "responses": { "202": { "description": "Bulk invite results with per-item status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInviteResponseDto" } } } }, "400": { "description": "Validation error (e.g., >100 IDs, empty array)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required (AUTH_INSUFFICIENT_ROLE), or the organisation is seat-blocked (SEATS_BLOCKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Bulk invite colleagues", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/{id}/invite": { "post": { "description": "Send an invitation email to a pending colleague. Returns 202 immediately — email delivery is async. Resending is allowed without cooldown.", "operationId": "inviteColleague", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Invitation queued for delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteColleagueResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required (AUTH_INSUFFICIENT_ROLE), or the organisation is seat-blocked (SEATS_BLOCKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Company-individual not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "422": { "description": "Colleague is active (ALREADY_ACTIVE) or archived (COLLEAGUE_ARCHIVED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Colleague is already active", "error": "ALREADY_ACTIVE" } } } } }, "summary": "Invite a colleague to activate their account", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/{id}/pending-change": { "delete": { "description": "Delete the pending (future-dated) membership row for the specified colleague.", "operationId": "cancelColleaguePendingChange", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pending change cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPendingChangeResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Company-individual not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "422": { "description": "No pending change exists (NO_PENDING_CHANGE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "No pending change exists", "error": "NO_PENDING_CHANGE" } } } } }, "summary": "Cancel a pending change for a colleague", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/bulk/assign-manager": { "post": { "description": "Assign a single manager to up to 100 colleagues atomically. For each subordinate, closes the existing active manager link and creates a new one. Returns per-item status.", "operationId": "bulkAssignColleagueManager", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssignManagerDto" } } } }, "responses": { "200": { "description": "Bulk assign results with per-item status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssignManagerResponseDto" } } } }, "400": { "description": "Validation error (e.g., >100 IDs, empty array)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Manager not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Manager not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "422": { "description": "Manager is archived (IDENTITY_MANAGER_ARCHIVED) or self-assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Manager is archived", "error": "IDENTITY_MANAGER_ARCHIVED" } } } } }, "summary": "Bulk assign manager to colleagues", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/bulk/set-department": { "post": { "description": "Update the department on up to 100 colleagues atomically. Closes the active membership row and inserts a new one with the new department, carrying forward the existing jobTitle and location. Effective immediately — future-dated bulk edits are not supported.", "operationId": "bulkSetColleagueDepartment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSetDepartmentDto" } } } }, "responses": { "200": { "description": "Bulk set department results with per-item status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAttributeUpdateResponseDto" } } } }, "400": { "description": "Validation error (e.g., >100 IDs, empty array)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Bulk set department for colleagues", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/bulk/set-location": { "post": { "description": "Update the location on up to 100 colleagues atomically. Closes the active membership row and inserts a new one with the new location, carrying forward the existing jobTitle and department. Effective immediately — future-dated bulk edits are not supported.", "operationId": "bulkSetColleagueLocation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSetLocationDto" } } } }, "responses": { "200": { "description": "Bulk set location results with per-item status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAttributeUpdateResponseDto" } } } }, "400": { "description": "Validation error (e.g., >100 IDs, empty array)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Bulk set location for colleagues", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/bulk/archive": { "post": { "description": "Archive up to 100 colleagues atomically. Owner IDs excluded with OWNER_PROTECTED status.", "operationId": "bulkArchiveColleagues", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkArchiveDto" } } } }, "responses": { "200": { "description": "Bulk archive results with per-item status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkArchiveResponseDto" } } } }, "400": { "description": "Validation error in request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Bulk archive colleagues", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/{id}/archive": { "post": { "description": "Set colleague status to archived, revoke Keycloak session if active, close all manager links.", "operationId": "archiveColleague", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveColleagueDto" } } } }, "responses": { "200": { "description": "Colleague archived successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIndividualDetailResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Company-individual not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "409": { "description": "Colleague already archived (COLLEAGUE_ALREADY_ARCHIVED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Colleague already archived", "error": "COLLEAGUE_ALREADY_ARCHIVED" } } } }, "422": { "description": "Cannot archive owner (OWNER_PROTECTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Cannot archive an owner", "error": "OWNER_PROTECTED" } } } } }, "summary": "Archive a colleague", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/{id}/restore": { "post": { "description": "Restore a colleague from archived status. New status determined by Account existence.", "operationId": "restoreColleague", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Colleague restored successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIndividualDetailResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required (AUTH_INSUFFICIENT_ROLE), or the organisation is seat-blocked (SEATS_BLOCKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Company-individual not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "409": { "description": "Colleague is not archived (COLLEAGUE_NOT_ARCHIVED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Colleague is not archived", "error": "COLLEAGUE_NOT_ARCHIVED" } } } } }, "summary": "Restore an archived colleague", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/{id}/request-deletion": { "post": { "description": "Set an archived colleague to deletion_requested status. Irreversible.", "operationId": "requestColleagueDeletion", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deletion requested successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIndividualDetailResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Company-individual not found (IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "409": { "description": "Colleague is not archived (COLLEAGUE_NOT_ARCHIVED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Colleague is not archived", "error": "COLLEAGUE_NOT_ARCHIVED" } } } } }, "summary": "Request deletion of an archived colleague", "tags": [ "People Administration" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/memberships": { "post": { "description": "Create a new membership record for a company-individual", "operationId": "createMembership", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMembershipDto" } } } }, "responses": { "201": { "description": "Membership created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipResponseDto" } } } }, "400": { "description": "Validation error in request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Create membership", "tags": [ "Memberships" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] }, "get": { "description": "Return all memberships for a given company-individual", "operationId": "listMembershipsByIndividual", "parameters": [ { "name": "companyIndividualId", "required": true, "in": "query", "description": "UUID of the company-individual to filter by", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of memberships", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MembershipResponseDto" } } } } }, "400": { "description": "Invalid UUID format for companyIndividualId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "List memberships by company-individual", "tags": [ "Memberships" ] } }, "/memberships/{id}": { "get": { "description": "Return a single membership by ID", "operationId": "getMembership", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Membership found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Membership not found (IDENTITY_MEMBERSHIP_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Membership not found", "error": "IDENTITY_MEMBERSHIP_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get membership", "tags": [ "Memberships" ] }, "patch": { "description": "Update department, job title, location, or end date of a membership", "operationId": "updateMembership", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMembershipDto" } } } }, "responses": { "200": { "description": "Membership updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipResponseDto" } } } }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Membership not found (IDENTITY_MEMBERSHIP_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Membership not found", "error": "IDENTITY_MEMBERSHIP_NOT_FOUND" } } } } }, "summary": "Update membership", "tags": [ "Memberships" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/accounts/me/session": { "get": { "description": "Return the authenticated user session status and account details", "operationId": "getMySession", "parameters": [], "responses": { "200": { "description": "Session status returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatusResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Account not found (IDENTITY_ACCOUNT_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Account not found", "error": "IDENTITY_ACCOUNT_NOT_FOUND" } } } } }, "summary": "Get current session", "tags": [ "Accounts" ], "x-badges": [ { "name": "Self Access" } ] } }, "/accounts/me/organisations": { "get": { "description": "Return all organisations the authenticated user belongs to", "operationId": "listMyOrganisations", "parameters": [], "responses": { "200": { "description": "List of organisations the user belongs to", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserOrganisationResponseDto" } } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Global access denied (IDENTITY_GLOBAL_ACCESS_DENIED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Global access denied", "error": "IDENTITY_GLOBAL_ACCESS_DENIED" } } } } }, "summary": "List user organisations", "tags": [ "Accounts" ], "x-badges": [ { "name": "Self Access" } ] } }, "/company-individuals/{id}/role": { "patch": { "description": "Change the role of a colleague — admin or owner. Admin cannot promote to owner; use ownership transfer instead.", "operationId": "changePersonRole", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Company-individual ID of the colleague to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRoleDto" } } } }, "responses": { "200": { "description": "Role updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRoleResponseDto" } } } }, "400": { "description": "Invalid UUID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role or admin attempting to set owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Company-individual not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Company-individual not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "422": { "description": "Cannot change own role or owner's role via this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Cannot change your own role or an owner's role via this endpoint", "error": "IDENTITY_ROLE_CANNOT_CHANGE_OWN" } } } }, "500": { "description": "Keycloak sync failed — role update rolled back" } }, "summary": "Change colleague role", "tags": [ "Roles & Permissions" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/companies/{tenantId}/roles": { "get": { "description": "Paginated, searchable, sortable list of colleagues with their roles — admin/owner only", "operationId": "listCompanyRoles", "parameters": [ { "name": "tenantId", "required": true, "in": "path", "description": "Tenant ID of the company", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 1000, "default": 1, "type": "integer" } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "integer" } }, { "name": "search", "required": false, "in": "query", "description": "search term to filter by name or email", "schema": { "minLength": 2, "maxLength": 200, "type": "string" } }, { "name": "role", "required": false, "in": "query", "description": "Filter by one or more roles; omit for all roles (FR7)", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "viewer" ] } } }, { "name": "sortBy", "required": false, "in": "query", "description": "field to sort by", "schema": { "enum": [ "name", "role" ], "type": "string" } }, { "name": "sortOrder", "required": false, "in": "query", "description": "sort direction", "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "Paginated list of colleague roles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolesListResponseDto" } } } }, "400": { "description": "Invalid tenantId or search term too short", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role (admin/owner) or tenant mismatch (IDENTITY_TENANT_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "List colleague roles", "tags": [ "Roles & Permissions" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/companies/{tenantId}/roles/distribution": { "get": { "description": "Org-wide count of colleagues per role (owner/admin/viewer) via a groupBy aggregation — pagination-, filter- and search-independent. Admin/owner only.", "operationId": "getCompanyRoleDistribution", "parameters": [ { "name": "tenantId", "required": true, "in": "path", "description": "Tenant ID of the company", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Org-wide role distribution counts { owner, admin, viewer }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDistributionResponseDto" } } } }, "400": { "description": "Invalid tenantId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role (admin/owner) or tenant mismatch (IDENTITY_TENANT_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Role distribution summary", "tags": [ "Roles & Permissions" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/companies/{tenantId}/transfer-ownership": { "post": { "description": "Transfer company ownership to another colleague — owner only", "operationId": "transferCompanyOwnership", "parameters": [ { "name": "tenantId", "required": true, "in": "path", "description": "Tenant ID of the company", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOwnershipDto" } } } }, "responses": { "200": { "description": "Ownership transferred successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOwnershipResponseDto" } } } }, "400": { "description": "Invalid UUID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role (admin/owner) or tenant mismatch (IDENTITY_TENANT_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Target company-individual not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Target company-individual not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "422": { "description": "Target is archived, already owner, or self-transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Target is archived, already owner, or self-transfer", "error": "IDENTITY_TRANSFER_TARGET_ALREADY_OWNER" } } } } }, "summary": "Transfer ownership", "tags": [ "Roles & Permissions" ], "x-badges": [ { "name": "Owner" } ] } }, "/companies/{tenantId}/profile": { "get": { "description": "Read-only organisation profile (name, billing address, norm group — each null until populated) projected from the tenant companies row — owner only", "operationId": "getOrganisationProfile", "parameters": [ { "name": "tenantId", "required": true, "in": "path", "description": "Tenant ID of the company", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organisation profile projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationProfileResponseDto" } } } }, "400": { "description": "Malformed tenantId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role (owner required) or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "No companies row for the authenticated tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No organisation profile for the authenticated tenant", "error": "ORGANISATION_PROFILE_NOT_FOUND" } } } } }, "summary": "Read organisation profile", "tags": [ "Organization Profile" ], "x-badges": [ { "name": "Owner" } ] } }, "/companies/{tenantId}/logo": { "post": { "description": "Reuses the photo pipeline (magic-byte validation, EXIF strip, resize). Stores a tenant/company-keyed logo and hand-wires a Profile/org-logo-updated audit row.", "operationId": "uploadOrganisationLogo", "parameters": [ { "name": "tenantId", "required": true, "in": "path", "description": "Tenant ID of the company", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Logo uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationLogoResponseDto" } } } }, "400": { "description": "Malformed tenantId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role (owner required) or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "No logo exists for this organisation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No logo exists for this organisation", "error": "ORGANISATION_LOGO_NOT_FOUND" } } } }, "422": { "description": "Validation error (format or size)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Logo processing failed (invalid format or size)", "error": "ORGANISATION_LOGO_PROCESSING_FAILED" } } } } }, "summary": "Upload organisation logo (owner only)", "tags": [ "Branding" ], "x-badges": [ { "name": "Owner" } ] }, "get": { "operationId": "getOrganisationLogo", "parameters": [ { "name": "tenantId", "required": true, "in": "path", "description": "Tenant/company ID of the organisation", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Logo binary stream (image/jpeg)", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No logo exists for this organisation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No logo exists for this organisation", "error": "ORGANISATION_LOGO_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get organisation logo (public)", "tags": [ "Branding" ], "security": [] }, "delete": { "operationId": "deleteOrganisationLogo", "parameters": [ { "name": "tenantId", "required": true, "in": "path", "description": "Tenant/company ID of the organisation", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Logo removed; organisation reverts to the default Thomas mark", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationLogoResponseDto" } } } }, "400": { "description": "Malformed tenantId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role (owner required) or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "No logo exists for this organisation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No logo exists for this organisation", "error": "ORGANISATION_LOGO_NOT_FOUND" } } } } }, "summary": "Remove organisation logo (owner only)", "tags": [ "Branding" ], "x-badges": [ { "name": "Owner" } ] } }, "/companies/{tenantId}/managers/{individualId}/reports": { "get": { "description": "Return all direct reports for a manager within a company", "operationId": "listDirectReports", "parameters": [ { "name": "tenantId", "required": true, "in": "path", "description": "Tenant ID of the company", "schema": { "type": "string" } }, { "name": "individualId", "required": true, "in": "path", "description": "Individual ID of the manager", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of direct reports", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DirectReportResponseDto" } } } } }, "400": { "description": "Invalid UUID format for tenantId or individualId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "URL tenant does not match authenticated tenant (IDENTITY_TENANT_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "URL tenant does not match the authenticated tenant", "error": "IDENTITY_TENANT_MISMATCH" } } } } }, "summary": "Get direct reports", "tags": [ "Manager Links" ] } }, "/manager-links": { "post": { "description": "Establish a manager-report relationship between two individuals", "operationId": "createManagerLink", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagerLinkDto" } } } }, "responses": { "201": { "description": "Manager link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagerLinkResponseDto" } } } }, "400": { "description": "Manager cannot link to themselves (IDENTITY_MANAGER_SELF_LINK) or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "A manager cannot link to themselves", "error": "IDENTITY_MANAGER_SELF_LINK" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Manager or report individual not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Manager or report individual not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "409": { "description": "Manager link already exists (IDENTITY_MANAGER_LINK_DUPLICATE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Manager link already exists", "error": "IDENTITY_MANAGER_LINK_DUPLICATE" } } } } }, "summary": "Create manager link", "tags": [ "Manager Links" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] }, "get": { "description": "Return all manager-report links within the current tenant", "operationId": "listManagerLinks", "parameters": [], "responses": { "200": { "description": "List of manager links", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManagerLinkResponseDto" } } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "List manager links", "tags": [ "Manager Links" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/manager-links/{id}": { "delete": { "description": "Remove a manager-report relationship", "operationId": "deleteManagerLink", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Manager link deleted" }, "400": { "description": "Invalid UUID format for id parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "404": { "description": "Manager link not found (IDENTITY_MANAGER_LINK_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "summary": "Delete manager link", "tags": [ "Manager Links" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/colleagues/{id}/photo": { "post": { "operationId": "uploadProfilePhoto", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Photo uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoUploadResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Cannot upload photo to another user's profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Cannot upload a photo to another user's profile", "error": "PHOTO_FORBIDDEN" } } } }, "404": { "description": "Company-individual not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague not found", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "422": { "description": "Validation error (format, size, or dimensions)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Please upload a JPEG, PNG, or WebP image", "error": "PHOTO_FORMAT_INVALID" } } } } }, "summary": "Upload profile photo (own profile only)", "tags": [ "Colleagues & Profiles" ], "x-badges": [ { "name": "Viewer" }, { "name": "Admin" }, { "name": "Owner" } ] }, "get": { "operationId": "getProfilePhoto", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Photo binary stream (image/jpeg)", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No photo exists for this colleague", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Photo not found", "error": "PHOTO_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get colleague profile photo (public)", "tags": [ "Colleagues & Profiles" ], "security": [] }, "delete": { "operationId": "deleteProfilePhoto", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Photo removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoDeleteResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Admin role required (unless own profile)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Admin role required unless deleting your own photo", "error": "PHOTO_FORBIDDEN" } } } }, "404": { "description": "No photo exists for this colleague", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Photo not found", "error": "PHOTO_NOT_FOUND" } } } } }, "summary": "Remove colleague profile photo (self or admin)", "tags": [ "Colleagues & Profiles" ], "x-badges": [ { "name": "Viewer" }, { "name": "Admin" }, { "name": "Owner" } ] } }, "/profile/demographics": { "patch": { "operationId": "updateMyDemographics", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDemographicsDto" } } } }, "responses": { "204": { "description": "Demographics updated" }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Candidate demographics require a fresh consent-gated survey save", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Candidate demographics must be saved through the consent-gated survey", "error": "IDENTITY_DEMOGRAPHICS_CONSENT_REQUIRED" } } } } }, "summary": "Update own demographics (self-edit)", "tags": [ "My Profile" ] } }, "/profile/demographics-survey": { "put": { "operationId": "updateMyDemographicsSurvey", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDemographicsSurveyDto" } } } }, "responses": { "204": { "description": "Survey outcome recorded" }, "400": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Record own demographics-survey outcome (consent or skip)", "tags": [ "My Profile" ] } }, "/profile/details": { "patch": { "operationId": "updateMyProfile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMyDetailsDto" } } } }, "responses": { "204": { "description": "Details updated" }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Update own name details (self-edit)", "tags": [ "My Profile" ] } }, "/profile/email": { "post": { "operationId": "initiateMyEmailChange", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateEmailVerificationDto" } } } }, "responses": { "202": { "description": "Verification email queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateEmailVerificationResponseDto" } } } }, "400": { "description": "Invalid email payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "409": { "description": "Email already in use by another user (EMAIL_ALREADY_IN_USE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Email already in use by another user", "error": "EMAIL_ALREADY_IN_USE" } } } }, "422": { "description": "Email is the same as the current personal email (EMAIL_UNCHANGED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Email is unchanged", "error": "EMAIL_UNCHANGED" } } } } }, "summary": "Initiate personal email change (sends verification email)", "tags": [ "My Profile" ] } }, "/profile/email/verify": { "post": { "operationId": "verifyMyEmailChange", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailDto" } } } }, "responses": { "204": { "description": "Email verified and updated" }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Verification token not found or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "410": { "description": "Verification token expired" } }, "summary": "Verify personal email change with token", "tags": [ "My Profile" ] } }, "/audit-events": { "get": { "operationId": "listAuditEvents", "parameters": [ { "name": "cursor", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } }, { "name": "category", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "type": "string", "enum": [ "Profile", "Consent", "Sharing", "Compliance", "Assessment" ] } }, { "name": "search", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minLength": 1, "type": "string" } }, { "name": "subjectCompanyIndividualId", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "description": "Paginated tenant audit events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditEventsResponseDto" } } } }, "400": { "description": "Invalid category, limit, or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Admin or owner role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "security": [ { "bearer": [] } ], "summary": "List the tenant audit events (paginated)", "tags": [ "Audit Log" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/audit-events/export": { "get": { "operationId": "exportAuditLog", "parameters": [ { "name": "category", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "Profile", "Consent", "Sharing", "Compliance", "Assessment" ] }, { "type": "string", "enum": [ "All" ] } ] } }, { "name": "search", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minLength": 1, "maxLength": 200, "type": "string" } }, { "name": "subjectCompanyIndividualId", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "description": "CSV export of the tenant audit log (text/csv)", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid category query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Admin or owner role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "security": [ { "bearer": [] } ], "summary": "Stream the tenant audit log as a CSV file", "tags": [ "Audit Log" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/dsr-requests": { "post": { "operationId": "submitDataSubjectRequest", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitDsrRequestDto" } } } }, "responses": { "201": { "description": "The submitted DSR request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DsrRequestResponseDto" } } } }, "400": { "description": "Invalid payload or target id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Admin or owner role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "409": { "description": "The erasure target is not archived/tombstoned (DSR_TARGET_NOT_ARCHIVED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "The target is not archived", "error": "DSR_TARGET_NOT_ARCHIVED" } } } } }, "security": [ { "bearer": [] } ], "summary": "Submit a data subject (erasure) request", "tags": [ "Data Subject Requests" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] }, "get": { "operationId": "listMyDataSubjectRequests", "parameters": [ { "name": "subjectCompanyIndividualId", "required": true, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "description": "The subject's DSR requests (newest first)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DsrRequestResponseDto" } } } } }, "400": { "description": "Malformed subjectCompanyIndividualId query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Admin or owner role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "security": [ { "bearer": [] } ], "summary": "List a subject's data subject requests (newest first)", "tags": [ "Data Subject Requests" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/dsr-requests/{id}": { "get": { "operationId": "getDataSubjectRequest", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The DSR request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DsrRequestResponseDto" } } } }, "400": { "description": "Malformed id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "The request exists in another tenant (DSR_FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "The DSR request belongs to another tenant", "error": "DSR_FORBIDDEN" } } } }, "404": { "description": "No DSR request with this id (DSR_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "DSR request not found", "error": "DSR_NOT_FOUND" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read a data subject request by id", "tags": [ "Data Subject Requests" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/terms-documents/{version}": { "get": { "operationId": "getTermsDocument", "parameters": [ { "name": "version", "required": true, "in": "path", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "200": { "description": "Archived document envelope `{ data, meta }` (camelCase)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsDocumentEnvelopeResponseDto" } } } }, "304": { "description": "ETag matched If-None-Match" }, "404": { "description": "No terms document exists for the given version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Terms document not found", "error": "TERMS_DOCUMENT_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get an archived terms/privacy document by version (public)", "tags": [ "Legal Documents" ], "security": [] } }, "/consent-records": { "get": { "operationId": "listConsentRecords", "parameters": [], "responses": { "200": { "description": "Consent-history envelope `{ data, meta: { count } }` (camelCase), newest-first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRecordsListResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "security": [ { "bearer": [] } ], "summary": "List the authenticated user's consent history (self-only)", "tags": [ "Consent" ] } }, "/share-grants": { "post": { "operationId": "createShareGrant", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareGrantBodyDto" } } } }, "responses": { "201": { "description": "Share grant created (single ShareGrant, or ShareGrant[] for team-bulk)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ShareGrantResponseDto" }, { "type": "array", "items": { "$ref": "#/components/schemas/ShareGrantResponseDto" } } ] } } } }, "400": { "description": "Invalid payload or self-share attempt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Recipient (single mode) or team (team-bulk mode) not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Recipient company-individual not found in tenant", "error": "SHARE_RECIPIENT_NOT_FOUND" } } } }, "409": { "description": "An active grant for this (sharer, recipient, dataType) already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "A conflicting share grant already exists", "error": "SHARE_GRANT_CONFLICT" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a share grant (single recipient or team-bulk)", "tags": [ "Sharing" ] }, "get": { "operationId": "listShareGrants", "parameters": [ { "name": "cursor", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } }, { "name": "dataType", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] } }, { "name": "direction", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "type": "string", "enum": [ "shared_by_me", "shared_with_me" ] } } ], "responses": { "200": { "description": "Paginated list of the caller share grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListShareGrantsResponseDto" } } } }, "400": { "description": "Malformed cursor or invalid query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "security": [ { "bearer": [] } ], "summary": "List the caller's own share grants (paginated)", "tags": [ "Sharing" ] } }, "/share-grants/manage-view": { "get": { "operationId": "getShareGrantManageView", "parameters": [ { "name": "dataType", "required": true, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] } } ], "responses": { "200": { "description": "Manage Sharing view for the data type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageSharingDataTypeViewDto" } } } }, "400": { "description": "Invalid or missing dataType query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "security": [ { "bearer": [] } ], "summary": "The caller's Manage Sharing view for a data type", "tags": [ "Sharing" ] } }, "/share-grants/team-coverage": { "get": { "operationId": "getTeamShareCoverage", "parameters": [ { "name": "teamId", "required": true, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "name": "dataType", "required": true, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] } } ], "responses": { "200": { "description": "Per-viewer team share coverage for the data type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamShareCoverageDto" } } } }, "400": { "description": "Invalid or missing teamId/dataType", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "security": [ { "bearer": [] } ], "summary": "Whether the caller still has team members to share a data type with", "tags": [ "Sharing" ] } }, "/share-grants/{id}": { "delete": { "operationId": "revokeShareGrant", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The revoked share grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareGrantResponseDto" } } } }, "400": { "description": "Malformed share-grant id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Share grant not found or not owned by the caller (no existence leak)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Share grant not found", "error": "SHARE_GRANT_NOT_FOUND" } } } }, "409": { "description": "The grant is org-configured and not individually revocable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "This grant is org-configured and cannot be revoked", "error": "PRIVACY_ORG_CONFIGURED_NOT_REVOCABLE" } } } } }, "security": [ { "bearer": [] } ], "summary": "Revoke a share grant the caller owns", "tags": [ "Sharing" ] } }, "/share-invitations/{id}/accept": { "post": { "operationId": "acceptShareInvitation", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The accepted invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareInvitationResponseDto" } } } }, "400": { "description": "Malformed invitation id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Invitation not found or not addressed to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Share invitation not found", "error": "SHARE_INVITATION_NOT_FOUND" } } } }, "409": { "description": "The invitation has already been accepted or dismissed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Share invitation is not pending", "error": "SHARE_INVITATION_NOT_PENDING" } } } } }, "security": [ { "bearer": [] } ], "summary": "Accept a reciprocal share invitation", "tags": [ "Sharing" ] } }, "/share-invitations/{id}/dismiss": { "post": { "operationId": "dismissShareInvitation", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The dismissed invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareInvitationResponseDto" } } } }, "400": { "description": "Malformed invitation id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Invitation not found or not addressed to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Share invitation not found", "error": "SHARE_INVITATION_NOT_FOUND" } } } }, "409": { "description": "The invitation has already been accepted or dismissed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Share invitation is not pending", "error": "SHARE_INVITATION_NOT_PENDING" } } } } }, "security": [ { "bearer": [] } ], "summary": "Dismiss a reciprocal share invitation", "tags": [ "Sharing" ] } }, "/sharing/organisations": { "get": { "operationId": "getOrgSharingView", "parameters": [], "responses": { "200": { "description": "Organisations the caller shares results with, with per-assessment on/off + status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSharingViewResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "security": [ { "bearer": [] } ], "summary": "The caller's per-organisation result-sharing view", "tags": [ "Sharing" ] } }, "/sharing/organisations/{organisationId}/request-removal": { "post": { "operationId": "requestOrgSharingRemoval", "parameters": [ { "name": "organisationId", "required": true, "in": "path", "description": "The organisation to stop sharing with (a tenant id)", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "201": { "description": "The organisation's updated sharing row. Deliberately carries no DSR id — a candidate surface has no use for the engine's internal identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOrgSharingRemovalResponseDto" } } } }, "400": { "description": "organisationId is not a valid UUID (ParseUUIDPipe)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "The caller does not share results with that organisation. Deliberately 404 rather than 403, so the response cannot confirm whether the organisation exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "You are not sharing results with that organisation.", "error": "ORG_SHARING_ORGANISATION_NOT_FOUND" } } } }, "409": { "description": "A removal request for that organisation is already under review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "You already have a removal request under review for that organisation.", "error": "ORG_SHARING_REMOVAL_ALREADY_REQUESTED" } } } } }, "security": [ { "bearer": [] } ], "summary": "Request removal of the results one organisation holds", "tags": [ "Sharing" ] } }, "/sharing/reuse-requests": { "get": { "operationId": "listOrgSharingReuseRequests", "parameters": [], "responses": { "200": { "description": "Pending reuse requests grouped by assessment, with freshness once per group and one row per requesting organisation. Provenance-free (AD-9) — no shared result id under any key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingReuseRequestsResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "security": [ { "bearer": [] } ], "summary": "Organisations waiting on the caller to choose about an existing result", "tags": [ "Sharing" ] } }, "/sharing/reuse-requests/{organisationId}/{assessmentType}/share": { "post": { "operationId": "shareOrgSharingExistingResult", "parameters": [ { "name": "organisationId", "required": true, "in": "path", "description": "The organisation to share with (a tenant id)", "schema": { "format": "uuid", "type": "string" } }, { "name": "assessmentType", "required": true, "in": "path", "description": "The assessment whose existing result is being shared", "schema": { "enum": [ "behaviour", "aptitude", "personality", "emotional_intelligence" ], "type": "string" } } ], "responses": { "201": { "description": "The organisation's sharing row, reusing the E8.3 row shape verbatim so a reuse-created grant is indistinguishable from any other.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareExistingResultResponseDto" } } } }, "400": { "description": "organisationId is not a valid UUID, or assessmentType is not one of the four in-scope instruments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "No actionable reuse request. Deliberately ONE code and ONE status for every cause — the organisation does not exist, the caller is not a member of it, the request was already resolved, or there is no completed result. Splitting these would make the route an organisation-existence and relationship oracle (AD-4; D39 kept the FR-41 limb).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "That request is no longer waiting on you.", "error": "ORG_SHARING_REUSE_REQUEST_NOT_FOUND" } } } } }, "security": [ { "bearer": [] } ], "summary": "Share an existing result with one requesting organisation", "tags": [ "Sharing" ] } }, "/sharing/reuse-requests/{organisationId}/{assessmentType}/decline": { "post": { "operationId": "declineOrgSharingReuseRequest", "parameters": [ { "name": "organisationId", "required": true, "in": "path", "description": "The organisation whose request is being declined (a tenant id)", "schema": { "format": "uuid", "type": "string" } }, { "name": "assessmentType", "required": true, "in": "path", "description": "The assessment whose request is being declined", "schema": { "enum": [ "behaviour", "aptitude", "personality", "emotional_intelligence" ], "type": "string" } } ], "responses": { "204": { "description": "The request is resolved. No grant was created and no body is returned." }, "400": { "description": "organisationId is not a valid UUID, or assessmentType is not one of the four in-scope instruments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "No actionable reuse request. Deliberately ONE code and ONE status for every cause — the organisation does not exist, the caller is not a member of it, the request was already resolved, or there is no completed result. Splitting these would make the route an organisation-existence and relationship oracle (AD-4; D39 kept the FR-41 limb).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "That request is no longer waiting on you.", "error": "ORG_SHARING_REUSE_REQUEST_NOT_FOUND" } } } } }, "security": [ { "bearer": [] } ], "summary": "Decline one organisation's request to reuse an existing result", "tags": [ "Sharing" ] } }, "/profile-visibility": { "put": { "operationId": "setProfileVisibility", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileVisibilityBodyDto" } } } }, "responses": { "200": { "description": "The updated profile visibility row", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileVisibilityResponseDto" } } } }, "400": { "description": "Invalid or missing visibility value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "security": [ { "bearer": [] } ], "summary": "Set the caller's profile visibility", "tags": [ "Profile Visibility" ] } }, "/org-offboarding/{companyIndividualId}/erase": { "post": { "operationId": "scheduleOrganisationOffboarding", "parameters": [ { "name": "companyIndividualId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgOffboardingRequestDto" } } } }, "responses": { "202": { "description": "The scheduled erasure timer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgOffboardingResponseDto" } } } }, "400": { "description": "Malformed companyIndividualId or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Admin or owner role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Missing / cross-tenant / tombstoned target (ORG_OFFBOARDING_TARGET_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Offboarding target not found", "error": "ORG_OFFBOARDING_TARGET_NOT_FOUND" } } } }, "409": { "description": "A concurrent timer-deletion race (ORG_OFFBOARDING_CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Offboarding timer conflict", "error": "ORG_OFFBOARDING_CONFLICT" } } } } }, "security": [ { "bearer": [] } ], "summary": "Schedule erasure (org offboarding) for a member", "tags": [ "Offboarding" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/privacy/tombstones/{companyIndividualId}": { "get": { "operationId": "resolveProfileTombstone", "parameters": [ { "name": "companyIndividualId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The resolved tombstone identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TombstoneLookupResponseDto" } } } }, "400": { "description": "Malformed companyIndividualId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Admin or owner role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "No tombstone for this company-individual (or it is live / cross-tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Tombstone not found", "error": "TOMBSTONE_NOT_FOUND" } } } } }, "security": [ { "bearer": [] } ], "summary": "DPO direct-lookup of a tombstoned identity by company-individual id", "tags": [ "Legal Documents" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/manager-visibility/config": { "get": { "operationId": "getManagerVisibilityConfig", "parameters": [], "responses": { "200": { "description": "Guardrail catalog rows", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgInsightVisibilityRowDto" } } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Owner role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read the org manager-visibility config catalog (Owner only)", "tags": [ "Manager Visibility" ], "x-badges": [ { "name": "Owner" } ] }, "put": { "operationId": "updateManagerVisibilityConfig", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgInsightVisibilityBodyDto" } } } }, "responses": { "200": { "description": "The updated visibility row", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgInsightVisibilityRowDto" } } } }, "400": { "description": "Ineligible/unknown insight (PRIVACY_INELIGIBLE_INSIGHT) or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Insight is not eligible for manager auto-visibility", "error": "PRIVACY_INELIGIBLE_INSIGHT" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Owner role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "security": [ { "bearer": [] } ], "summary": "Set an insight auto-visibility flag (Owner only)", "tags": [ "Manager Visibility" ], "x-badges": [ { "name": "Owner" } ] } }, "/manager-visibility/auto-visible-insights": { "get": { "operationId": "listManagerAutoVisibleInsights", "parameters": [], "responses": { "200": { "description": "Auto-visible insight ids for the tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoVisibleInsightsResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "security": [ { "bearer": [] } ], "summary": "List the org-auto-visible insight ids for the caller (any employee)", "tags": [ "Manager Visibility" ] } }, "/colleagues/{id}/about-me": { "get": { "operationId": "getMyAboutMe", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "About Me content, or null when none exists", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AboutMeResponseDto" }, { "type": "null" } ] } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Cannot read or edit another colleague's About Me", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "You can only view or edit your own About Me", "error": "ABOUT_ME_FORBIDDEN" } } } } }, "summary": "Get own About Me (self-only; pre-fills the editor)", "tags": [ "Colleagues & Profiles" ], "x-badges": [ { "name": "Viewer" }, { "name": "Admin" }, { "name": "Owner" } ] }, "put": { "operationId": "upsertMyAboutMe", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The persisted About Me content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AboutMeResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Cannot read or edit another colleague's About Me", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "You can only view or edit your own About Me", "error": "ABOUT_ME_FORBIDDEN" } } } }, "404": { "description": "The company-individual membership could not be resolved (ABOUT_ME_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague membership not found", "error": "ABOUT_ME_NOT_FOUND" } } } }, "422": { "description": "Too many tags (ABOUT_ME_TOO_MANY_TAGS) or text over the field limit (ABOUT_ME_TEXT_TOO_LONG)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Too many interests", "error": "ABOUT_ME_TOO_MANY_TAGS" } } } } }, "summary": "Upsert own About Me (self-only; atomic explicit save)", "tags": [ "Colleagues & Profiles" ], "x-badges": [ { "name": "Viewer" }, { "name": "Admin" }, { "name": "Owner" } ] } }, "/partner-access-requests/{grantId}": { "get": { "description": "Returns the complete canonical Scope, immutable request version and Scope fingerprint an eligible Customer Owner must review before submitting the approval command. Owner eligibility is re-read live, and the Grant id is constrained to the authenticated Owner's Tenant.", "operationId": "getPartnerAccessRequest", "parameters": [ { "name": "grantId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The exact pending reviewed artefact and only the durable identifiers needed to submit its approval command. Carries no Partner secret or unrelated Customer data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAccessRequestReviewDto" } } } }, "400": { "description": "Invalid UUID format for grantId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "The caller is not a live eligible owner of the authenticated tenant, or is not a person at all (PARTNER_APPROVER_NOT_ELIGIBLE, AUTH_PRINCIPAL_NOT_HUMAN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "404": { "description": "No pending access request exists at this id for the authenticated tenant (PARTNER_ACCESS_REQUEST_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "summary": "Read the exact pending Partner access request for your tenant", "tags": [ "Partner access governance" ] } }, "/partner-access-requests/{grantId}/approve": { "post": { "description": "Settles the EXACT reviewed version named in the body. One transaction re-asserts every Owner and request predicate from live locked rows, transitions the Grant to active, retains and reactivates the stable Service Membership, acquires every system-of-record authority claim the approved Scope requires, and records the decision against the approving Owner. Any failure rolls the whole bundle back and leaves the request pending.", "operationId": "approvePartnerAccessRequest", "parameters": [ { "name": "grantId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAccessApprovalDto" } } } }, "responses": { "200": { "description": "The settled Grant, the reviewed version and fingerprint it settled, the now-active Service Membership, and the Owner who approved. Carries no secret and no unrelated tenant data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAccessApprovalResultDto" } } } }, "400": { "description": "Invalid UUID format for grantId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "The caller is not an eligible owner of the tenant this request names, or is not a person at all (PARTNER_APPROVER_NOT_ELIGIBLE, AUTH_PRINCIPAL_NOT_HUMAN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "404": { "description": "No pending access request exists at this id (PARTNER_ACCESS_REQUEST_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "409": { "description": "The request is no longer the exact version reviewed, or the activation bundle conflicted and rolled back (PARTNER_ACCESS_APPROVAL_CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "summary": "Approve a pending Partner access request for your tenant", "tags": [ "Partner access governance" ] } }, "/partner-access-requests/{grantId}/reject": { "post": { "description": "Refuses the EXACT reviewed version named in the body, permanently. One transaction re-asserts every Owner and request predicate from live locked rows, transitions the Grant from pending to rejected, records the refusing Owner on the row, and writes the decision to the audit ledger. Nothing is activated: no Service Membership, no system-of-record authority claim, and the approval attribution stays empty. The rejected version can never be approved afterwards — a changed request must be submitted afresh and reviewed on its own merits. This route settles PENDING requests only; withdrawing access that is already live is a separate operation.", "operationId": "rejectPartnerAccessRequest", "parameters": [ { "name": "grantId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAccessRejectionDto" } } } }, "responses": { "200": { "description": "The settled Grant, the reviewed version and fingerprint it refused, and the Owner who refused it. Narrower than the approval receipt by construction: no Service Membership, because a refusal settles none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAccessRejectionResultDto" } } } }, "400": { "description": "Invalid UUID format for grantId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "The caller is not an eligible owner of the tenant this request names, or is not a person at all (PARTNER_APPROVER_NOT_ELIGIBLE, AUTH_PRINCIPAL_NOT_HUMAN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "404": { "description": "No refusable access request exists at this id — it never existed, it belongs to another tenant, or it has already been approved (PARTNER_ACCESS_REQUEST_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "409": { "description": "The request is no longer the exact version reviewed, or the refusal conflicted with a concurrent decision and rolled back (PARTNER_ACCESS_REJECTION_CONFLICT, PARTNER_ACCESS_REQUEST_VERSION_MISMATCH, PARTNER_ACCESS_REQUEST_FINGERPRINT_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "summary": "Reject a pending Partner access request for your tenant", "tags": [ "Partner access governance" ] } }, "/oauth/token": { "post": { "description": "The OAuth 2.0 `client_credentials` facade (RFC 6749 §4.4). Accepts the client identifier and secret as HTTP Basic authentication or in the request body, authenticates the confidential client against Keycloak, resolves the active Thomas Credential mapping, and returns a Thomas-signed Platform token valid for 10 minutes with no refresh token. The token carries identity only — authority is resolved against live state on every request. Errors answer the standard OAuth envelope; a rate-limited request answers `slow_down` at 429.", "operationId": "issuePartnerToken", "parameters": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string", "description": "Alternative to HTTP Basic authentication." }, "client_secret": { "type": "string", "description": "Alternative to HTTP Basic authentication." } } } }, "application/json": { "schema": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string", "description": "Alternative to HTTP Basic authentication." }, "client_secret": { "type": "string", "description": "Alternative to HTTP Basic authentication." } } } } } }, "responses": { "200": { "description": "The RFC 6749 §5.1 envelope: `access_token`, `token_type: Bearer`, `expires_in: 600`. No refresh token. Served under `Cache-Control: no-store`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string", "description": "The signed bearer token. Opaque to the partner — never parsed." }, "token_type": { "type": "string", "enum": [ "Bearer" ], "description": "Always `Bearer` (RFC 6749 §7.1)." }, "expires_in": { "type": "integer", "description": "Token lifetime in seconds from issuance." } } } } } }, "400": { "description": "`invalid_request` (missing or malformed parameters) or `unsupported_grant_type`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_request", "unsupported_grant_type" ] } } } } } }, "401": { "description": "`invalid_client` — wrong identifier, wrong secret, unknown client, or a credential that is revoked or past its effective expiry. Byte-identical across all of them by design.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_client" ] } } } } } }, "429": { "description": "`slow_down` — the pre-Keycloak abuse boundary refused this attempt. Applies to failed attempts as well as successful ones, and is counted against both the per-client and per-source ceilings.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "slow_down" ] } } }, "example": { "error": "slow_down" } } } }, "503": { "description": "`temporarily_unavailable` — the credential provider could not be reached. Fails closed; never falls back to a cached or local credential check." } }, "summary": "Exchange partner client credentials for a Platform token", "tags": [ "Partner Auth" ], "x-badge": [ { "name": "Partner" } ], "x-version-neutral": true, "security": [] } }, "/tenants": { "post": { "description": "Create one new Customer Tenant and the provisional access bundle that lets the calling Partner serve it immediately.", "operationId": "createPartnerTenant", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "An opaque client-generated key, 1-255 visible ASCII characters excluding comma. Repeating a request with the same key and the same body is safe.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerTenantCreateRequestDto" } } } }, "responses": { "200": { "description": "The supplied customer identity matched existing evidence. The opaque outcome either requests the existing Customer access flow or requires platform-admin resolution.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PartnerTenantRequestAccessOutcomeDto" }, { "$ref": "#/components/schemas/PartnerTenantAdminResolutionRequiredOutcomeDto" } ] } } } }, "201": { "description": "The Tenant was created and the calling Partner already has access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerTenantCreatedOutcomeDto" } } } }, "400": { "description": "Request validation, idempotency-header, or customer-identity validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "examples": { "HTTP_BAD_REQUEST": { "summary": "Validation error in request body", "value": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } }, "IDEMPOTENCY_KEY_INVALID": { "summary": "Missing, repeated or malformed Idempotency-Key", "value": { "statusCode": 400, "message": "Exactly one valid Idempotency-Key header is required", "error": "IDEMPOTENCY_KEY_INVALID" } }, "PARTNER_TENANT_IDENTITY_INVALID": { "summary": "The Owner email or domain is not a valid customer alias", "value": { "statusCode": 400, "message": "Customer identity could not be normalized", "error": "PARTNER_TENANT_IDENTITY_INVALID" } } } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Only a provisioned Partner-owned API client may call this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "API client is not permitted to call this operation", "error": "PRINCIPAL_TYPE_NOT_ALLOWED" } } } }, "409": { "description": "Customer identity, idempotency state, or Partner tenant cap prevented creation", "headers": { "Retry-After": { "description": "Present as `1` only when an equivalent idempotent request is in progress", "schema": { "type": "string", "example": "1" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "examples": { "IDEMPOTENCY_KEY_REUSED": { "summary": "The key is bound to a different canonical request fingerprint", "value": { "statusCode": 409, "message": "This Idempotency-Key was already used for a different request", "error": "IDEMPOTENCY_KEY_REUSED" } }, "IDEMPOTENCY_REQUEST_IN_PROGRESS": { "summary": "Retry the equivalent request after one second", "value": { "statusCode": 409, "message": "An equivalent request is already in progress", "error": "IDEMPOTENCY_REQUEST_IN_PROGRESS" } }, "PARTNER_TENANT_CAP_REACHED": { "summary": "The partner is at its active partner-created tenant cap", "value": { "statusCode": 409, "message": "This partner has reached its limit of partner-created tenants", "error": "PARTNER_TENANT_CAP_REACHED" } } } } } }, "429": { "description": "The per-Credential business rate limit was exceeded (60 requests per minute).", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Create a customer tenant", "tags": [ "Partner Tenants" ] } }, "/integration-diagnostics": { "get": { "description": "Returns the calling API client's own integration activity, newest first, with each record's current integration status and last-run time. Rows are re-authorized against the live Grant on every request, so a revoked or narrowed Grant omits them.", "operationId": "listIntegrationDiagnostics", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25 }, "description": "Narrow the page. Defaults to 25, which is also the maximum." }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" }, "description": "The `nextCursor` from a previous page. Omit for the newest page." } ], "responses": { "200": { "description": "One bounded page of integration diagnostics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationDiagnosticListResponseDto" } } } }, "400": { "description": "The `cursor` was not issued by this operation, or `limit` is not a positive integer no greater than 25.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "The diagnostics cursor is not a cursor this operation issued", "error": "INTEGRATION_DIAGNOSTIC_CURSOR_INVALID" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Only a provisioned, active Partner-owned API client may call this operation. A suspended or deactivated Partner collapses into this same refusal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "API client is not permitted to call this operation", "error": "PRINCIPAL_TYPE_NOT_ALLOWED" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } }, "503": { "description": "The durable diagnostic projection could not be read. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 503, "message": "Integration diagnostics are temporarily unavailable", "error": "INTEGRATION_DIAGNOSTICS_UNAVAILABLE" } } } } }, "summary": "List this API client's integration diagnostics", "tags": [ "Partner Diagnostics" ] } }, "/integration-diagnostics/{diagnosticId}": { "get": { "description": "Returns the same canonical safe reason and operation context the list carries, for one diagnostic this API client owns and its live Grant still permits.", "operationId": "getIntegrationDiagnostic", "parameters": [ { "name": "diagnosticId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The canonical diagnostic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationDiagnosticReadResponseDto" } } } }, "400": { "description": "The `diagnosticId` path parameter is not a UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Only a provisioned, active Partner-owned API client may call this operation. A suspended or deactivated Partner collapses into this same refusal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "API client is not permitted to call this operation", "error": "PRINCIPAL_TYPE_NOT_ALLOWED" } } } }, "404": { "description": "No diagnostic with this id belongs to the calling API client and remains within its active Grant. A diagnostic owned by a different client, and one whose originating Grant has been revoked or narrowed, are concealed behind this same response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Integration diagnostic was not found", "error": "INTEGRATION_DIAGNOSTIC_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } }, "503": { "description": "The durable diagnostic projection could not be read. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 503, "message": "Integration diagnostics are temporarily unavailable", "error": "INTEGRATION_DIAGNOSTICS_UNAVAILABLE" } } } } }, "summary": "Retrieve one integration diagnostic", "tags": [ "Partner Diagnostics" ] } }, "/webhook-subscriptions": { "post": { "description": "Register the public HTTPS endpoint Thomas will deliver this API client’s events to, and receive the signing secret that proves those deliveries came from Thomas. The secret is returned exactly once and cannot be read back afterwards. Registration configures delivery; it does not switch it on.", "operationId": "registerWebhookSubscription", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "An opaque client-generated key, 1-255 visible ASCII characters excluding comma. Repeating a request with the same key and the same body returns the ORIGINAL response — including the secret it minted — instead of minting a second one.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateRequestDto" } } } }, "responses": { "201": { "description": "The subscription was configured. `signingSecret` is shown here and nowhere else.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateResponseDto" } } } }, "400": { "description": "The request could not be accepted as sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "examples": { "HTTP_BAD_REQUEST": { "summary": "Request body or path parameter validation failed", "value": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } }, "IDEMPOTENCY_KEY_INVALID": { "summary": "Missing, repeated or malformed Idempotency-Key", "value": { "statusCode": 400, "message": "Exactly one valid Idempotency-Key header is required", "error": "IDEMPOTENCY_KEY_INVALID" } } } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Only a provisioned Partner-owned API client may call this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "API client is not permitted to call this operation", "error": "PRINCIPAL_TYPE_NOT_ALLOWED" } } } }, "409": { "description": "The request conflicts with the current state of this API client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "examples": { "WEBHOOK_SUBSCRIPTION_ALREADY_EXISTS": { "summary": "One webhook subscription per API client; update the existing one instead", "value": { "statusCode": 409, "message": "This API client already has a webhook subscription", "error": "WEBHOOK_SUBSCRIPTION_ALREADY_EXISTS" } }, "IDEMPOTENCY_KEY_REUSED": { "summary": "The key is bound to a different canonical request body", "value": { "statusCode": 409, "message": "This Idempotency-Key was already used for a different request", "error": "IDEMPOTENCY_KEY_REUSED" } }, "IDEMPOTENCY_REQUEST_IN_PROGRESS": { "summary": "The same key and body are being processed; retry shortly", "value": { "statusCode": 409, "message": "An equivalent request is already in progress", "error": "IDEMPOTENCY_REQUEST_IN_PROGRESS" } } } } } }, "422": { "description": "The webhook endpoint is not a safe public HTTPS destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "examples": { "WEBHOOK_ENDPOINT_INVALID": { "summary": "The endpoint is not a parsable absolute URL", "value": { "statusCode": 422, "message": "Webhook endpoint must be a valid URL", "error": "WEBHOOK_ENDPOINT_INVALID" } }, "WEBHOOK_ENDPOINT_HTTPS_REQUIRED": { "summary": "The endpoint URL is not HTTPS", "value": { "statusCode": 422, "message": "Webhook endpoint must use HTTPS", "error": "WEBHOOK_ENDPOINT_HTTPS_REQUIRED" } }, "WEBHOOK_ENDPOINT_PORT_FORBIDDEN": { "summary": "The endpoint URL names an explicit port. Only the default HTTPS port is accepted.", "value": { "statusCode": 422, "message": "Webhook endpoint must use the default HTTPS port", "error": "WEBHOOK_ENDPOINT_PORT_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_TOO_LONG": { "summary": "The endpoint URL exceeds the stored length once normalized", "value": { "statusCode": 422, "message": "Webhook endpoint must be at most 2048 characters", "error": "WEBHOOK_ENDPOINT_TOO_LONG" } }, "WEBHOOK_ENDPOINT_CREDENTIALS_FORBIDDEN": { "summary": "The endpoint URL carries a userinfo component", "value": { "statusCode": 422, "message": "Webhook endpoint must not contain credentials", "error": "WEBHOOK_ENDPOINT_CREDENTIALS_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_FRAGMENT_FORBIDDEN": { "summary": "The endpoint URL carries a fragment", "value": { "statusCode": 422, "message": "Webhook endpoint must not contain a fragment", "error": "WEBHOOK_ENDPOINT_FRAGMENT_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_DNS_EMPTY": { "summary": "The endpoint hostname resolved to nothing", "value": { "statusCode": 422, "message": "Webhook endpoint hostname returned no addresses", "error": "WEBHOOK_ENDPOINT_DNS_EMPTY" } }, "WEBHOOK_ENDPOINT_PRIVATE_ADDRESS_FORBIDDEN": { "summary": "The endpoint hostname resolves into private address space", "value": { "statusCode": 422, "message": "Webhook endpoint must not resolve to a private address", "error": "WEBHOOK_ENDPOINT_PRIVATE_ADDRESS_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_METADATA_ADDRESS_FORBIDDEN": { "summary": "The endpoint hostname resolves to a cloud instance metadata service", "value": { "statusCode": 422, "message": "Webhook endpoint must not resolve to a cloud metadata address", "error": "WEBHOOK_ENDPOINT_METADATA_ADDRESS_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_IPV4_EMBEDDED_IPV6_FORBIDDEN": { "summary": "The endpoint hostname resolves to a NAT64 or 6to4 address, which carries an IPv4 destination that has not itself been checked", "value": { "statusCode": 422, "message": "Webhook endpoint must not resolve to an IPv4-embedded IPv6 address", "error": "WEBHOOK_ENDPOINT_IPV4_EMBEDDED_IPV6_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_REDIRECT_FORBIDDEN": { "summary": "The endpoint answered with a redirect, which is never followed", "value": { "statusCode": 422, "message": "Webhook endpoint reachability redirects are not followed", "error": "WEBHOOK_ENDPOINT_REDIRECT_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_REACHABILITY_FAILED": { "summary": "The endpoint did not answer a TLS request at its resolved address", "value": { "statusCode": 422, "message": "Webhook endpoint could not be reached over TLS", "error": "WEBHOOK_ENDPOINT_REACHABILITY_FAILED" } } } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } }, "503": { "description": "This deployment has no webhook signing key provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 503, "message": "Webhook signing is not configured on this deployment", "error": "WEBHOOK_SIGNING_NOT_CONFIGURED" } } } } }, "summary": "Register a webhook endpoint", "tags": [ "Partner Events & Webhooks" ] } }, "/webhook-subscriptions/{subscriptionId}": { "get": { "description": "Read the current endpoint and signing-secret version of a webhook subscription this API client owns. The signing secret itself is never returned.", "operationId": "getWebhookSubscription", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionReadResponseDto" } } } }, "400": { "description": "Request body or path parameter validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Only a provisioned Partner-owned API client may call this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "API client is not permitted to call this operation", "error": "PRINCIPAL_TYPE_NOT_ALLOWED" } } } }, "404": { "description": "No webhook subscription with this id belongs to the calling API client. A subscription owned by a different client is concealed behind this same response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Webhook subscription was not found", "error": "WEBHOOK_SUBSCRIPTION_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } }, "503": { "description": "This deployment has no webhook signing key provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 503, "message": "Webhook signing is not configured on this deployment", "error": "WEBHOOK_SIGNING_NOT_CONFIGURED" } } } } }, "summary": "Read a webhook subscription", "tags": [ "Partner Events & Webhooks" ] }, "patch": { "description": "Point an existing webhook subscription at a different public HTTPS endpoint. The new endpoint is validated exactly as it was at registration. The signing secret is unaffected — rotate it separately if it needs to change.", "operationId": "updateWebhookSubscription", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdateRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionReadResponseDto" } } } }, "400": { "description": "Request body or path parameter validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Only a provisioned Partner-owned API client may call this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "API client is not permitted to call this operation", "error": "PRINCIPAL_TYPE_NOT_ALLOWED" } } } }, "404": { "description": "No webhook subscription with this id belongs to the calling API client. A subscription owned by a different client is concealed behind this same response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Webhook subscription was not found", "error": "WEBHOOK_SUBSCRIPTION_NOT_FOUND" } } } }, "409": { "description": "Another change advanced this subscription first; re-read and retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "A concurrent change moved this webhook subscription", "error": "WEBHOOK_SUBSCRIPTION_UPDATE_CONFLICT" } } } }, "422": { "description": "The webhook endpoint is not a safe public HTTPS destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "examples": { "WEBHOOK_ENDPOINT_INVALID": { "summary": "The endpoint is not a parsable absolute URL", "value": { "statusCode": 422, "message": "Webhook endpoint must be a valid URL", "error": "WEBHOOK_ENDPOINT_INVALID" } }, "WEBHOOK_ENDPOINT_HTTPS_REQUIRED": { "summary": "The endpoint URL is not HTTPS", "value": { "statusCode": 422, "message": "Webhook endpoint must use HTTPS", "error": "WEBHOOK_ENDPOINT_HTTPS_REQUIRED" } }, "WEBHOOK_ENDPOINT_PORT_FORBIDDEN": { "summary": "The endpoint URL names an explicit port. Only the default HTTPS port is accepted.", "value": { "statusCode": 422, "message": "Webhook endpoint must use the default HTTPS port", "error": "WEBHOOK_ENDPOINT_PORT_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_TOO_LONG": { "summary": "The endpoint URL exceeds the stored length once normalized", "value": { "statusCode": 422, "message": "Webhook endpoint must be at most 2048 characters", "error": "WEBHOOK_ENDPOINT_TOO_LONG" } }, "WEBHOOK_ENDPOINT_CREDENTIALS_FORBIDDEN": { "summary": "The endpoint URL carries a userinfo component", "value": { "statusCode": 422, "message": "Webhook endpoint must not contain credentials", "error": "WEBHOOK_ENDPOINT_CREDENTIALS_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_FRAGMENT_FORBIDDEN": { "summary": "The endpoint URL carries a fragment", "value": { "statusCode": 422, "message": "Webhook endpoint must not contain a fragment", "error": "WEBHOOK_ENDPOINT_FRAGMENT_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_DNS_EMPTY": { "summary": "The endpoint hostname resolved to nothing", "value": { "statusCode": 422, "message": "Webhook endpoint hostname returned no addresses", "error": "WEBHOOK_ENDPOINT_DNS_EMPTY" } }, "WEBHOOK_ENDPOINT_PRIVATE_ADDRESS_FORBIDDEN": { "summary": "The endpoint hostname resolves into private address space", "value": { "statusCode": 422, "message": "Webhook endpoint must not resolve to a private address", "error": "WEBHOOK_ENDPOINT_PRIVATE_ADDRESS_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_METADATA_ADDRESS_FORBIDDEN": { "summary": "The endpoint hostname resolves to a cloud instance metadata service", "value": { "statusCode": 422, "message": "Webhook endpoint must not resolve to a cloud metadata address", "error": "WEBHOOK_ENDPOINT_METADATA_ADDRESS_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_IPV4_EMBEDDED_IPV6_FORBIDDEN": { "summary": "The endpoint hostname resolves to a NAT64 or 6to4 address, which carries an IPv4 destination that has not itself been checked", "value": { "statusCode": 422, "message": "Webhook endpoint must not resolve to an IPv4-embedded IPv6 address", "error": "WEBHOOK_ENDPOINT_IPV4_EMBEDDED_IPV6_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_REDIRECT_FORBIDDEN": { "summary": "The endpoint answered with a redirect, which is never followed", "value": { "statusCode": 422, "message": "Webhook endpoint reachability redirects are not followed", "error": "WEBHOOK_ENDPOINT_REDIRECT_FORBIDDEN" } }, "WEBHOOK_ENDPOINT_REACHABILITY_FAILED": { "summary": "The endpoint did not answer a TLS request at its resolved address", "value": { "statusCode": 422, "message": "Webhook endpoint could not be reached over TLS", "error": "WEBHOOK_ENDPOINT_REACHABILITY_FAILED" } } } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } }, "503": { "description": "This deployment has no webhook signing key provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 503, "message": "Webhook signing is not configured on this deployment", "error": "WEBHOOK_SIGNING_NOT_CONFIGURED" } } } } }, "summary": "Change a webhook endpoint", "tags": [ "Partner Events & Webhooks" ] } }, "/webhook-subscriptions/{subscriptionId}/signing-secrets/rotate": { "post": { "description": "Issue the next signing secret for this subscription and return it exactly once. A routine rotation leaves the previous secret able to verify signatures for 24 hours so in-flight deliveries keep validating; `reason: \"compromise\"` retires it immediately instead.", "operationId": "rotateWebhookSigningSecret", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "An opaque client-generated key, 1-255 visible ASCII characters excluding comma. Repeating a request with the same key and the same body returns the ORIGINAL response — including the secret it minted — instead of minting a second one.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningSecretRotateRequestDto" } } } }, "responses": { "201": { "description": "The new secret was activated. It is shown here and nowhere else.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSigningSecretRotateResponseDto" } } } }, "400": { "description": "The request could not be accepted as sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "examples": { "HTTP_BAD_REQUEST": { "summary": "Request body or path parameter validation failed", "value": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } }, "IDEMPOTENCY_KEY_INVALID": { "summary": "Missing, repeated or malformed Idempotency-Key", "value": { "statusCode": 400, "message": "Exactly one valid Idempotency-Key header is required", "error": "IDEMPOTENCY_KEY_INVALID" } } } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Only a provisioned Partner-owned API client may call this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "API client is not permitted to call this operation", "error": "PRINCIPAL_TYPE_NOT_ALLOWED" } } } }, "404": { "description": "No webhook subscription with this id belongs to the calling API client. A subscription owned by a different client is concealed behind this same response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Webhook subscription was not found", "error": "WEBHOOK_SUBSCRIPTION_NOT_FOUND" } } } }, "409": { "description": "The request conflicts with the current state of this signing-secret lineage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "examples": { "WEBHOOK_SIGNING_SECRET_ROTATION_CONFLICT": { "summary": "Another rotation advanced this lineage first; re-read and retry", "value": { "statusCode": 409, "message": "A concurrent rotation changed this signing secret lineage", "error": "WEBHOOK_SIGNING_SECRET_ROTATION_CONFLICT" } }, "IDEMPOTENCY_KEY_REUSED": { "summary": "The key is bound to a different canonical request body", "value": { "statusCode": 409, "message": "This Idempotency-Key was already used for a different request", "error": "IDEMPOTENCY_KEY_REUSED" } }, "IDEMPOTENCY_REQUEST_IN_PROGRESS": { "summary": "The same key and body are being processed; retry shortly", "value": { "statusCode": 409, "message": "An equivalent request is already in progress", "error": "IDEMPOTENCY_REQUEST_IN_PROGRESS" } } } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } }, "503": { "description": "This deployment has no webhook signing key provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 503, "message": "Webhook signing is not configured on this deployment", "error": "WEBHOOK_SIGNING_NOT_CONFIGURED" } } } } }, "summary": "Rotate a webhook signing secret", "tags": [ "Partner Events & Webhooks" ] } }, "/ai-coaching/conversations": { "post": { "operationId": "createCoachingConversation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationBodyDto" } } } }, "responses": { "201": { "description": "AI coaching conversation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Create AI coaching conversation", "tags": [ "AI Coaching" ] }, "get": { "operationId": "listCoachingConversations", "parameters": [ { "name": "cursor", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } } ], "responses": { "200": { "description": "List of AI coaching conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsListResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "List AI coaching conversations", "tags": [ "AI Coaching" ] } }, "/ai-coaching/conversations/{conversationId}": { "get": { "operationId": "getCoachingConversation", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "messagesCursor", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minLength": 1, "type": "string" } }, { "name": "messagesLimit", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minimum": 1, "maximum": 200, "default": 100, "type": "integer" } } ], "responses": { "200": { "description": "AI coaching conversation detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDetailResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Get AI coaching conversation", "tags": [ "AI Coaching" ] }, "delete": { "operationId": "deleteCoachingConversation", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "AI coaching conversation deleted" }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Delete AI coaching conversation", "tags": [ "AI Coaching" ] }, "patch": { "operationId": "renameCoachingConversation", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationBodyDto" } } } }, "responses": { "200": { "description": "Renamed AI coaching conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Rename AI coaching conversation", "tags": [ "AI Coaching" ] } }, "/ai-coaching/conversations/{conversationId}/messages": { "post": { "operationId": "sendCoachingMessage", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageBodyDto" } } } }, "responses": { "200": { "description": "SSE stream of coaching events (text/event-stream)", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid message payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Conversation not found (pre-stream)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Conversation not found", "error": "CONVERSATION_NOT_FOUND" } } } }, "429": { "description": "Per-individual AI-coaching rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "Too many coaching requests", "error": "THOMAI_OPS_RATE_LIMIT_EXCEEDED" } } } } }, "summary": "Stream an AI coaching message response", "tags": [ "AI Coaching" ] } }, "/ai-coaching/conversations/{conversationId}/messages/{messageId}/actions": { "post": { "operationId": "pushCoachingMessageAction", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "messageId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushMessageActionBodyDto" } } } }, "responses": { "201": { "description": "The pushed message action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCoachingMessageActionResponseDto" } } } }, "400": { "description": "Malformed ids or non-actionable message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Message not found (AI_COACHING_MESSAGE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Message not found", "error": "AI_COACHING_MESSAGE_NOT_FOUND" } } } }, "429": { "description": "Per-individual AI-coaching rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "Too many coaching requests", "error": "THOMAI_OPS_RATE_LIMIT_EXCEEDED" } } } } }, "summary": "Push an AI coaching message action to the activity feed", "tags": [ "AI Coaching" ] } }, "/ai-coaching/cards": { "get": { "operationId": "listCoachingCards", "parameters": [ { "name": "pageId", "required": true, "in": "query", "schema": { "type": "string", "enum": [ "individual", "team", "org_analyst", "manager", "home", "unprompted", "connection_template1_results" ] } } ], "responses": { "200": { "description": "Contextual coaching cards for the page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CxiCardsResponseDto" } } } }, "400": { "description": "Invalid pageId or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Gate-1 re-authorization denial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "AI coaching authorization denied", "error": "THOMAI_AUTHORIZATION_DENIED" } } } }, "429": { "description": "Per-individual AI-coaching rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "Too many coaching requests", "error": "THOMAI_OPS_RATE_LIMIT_EXCEEDED" } } } } }, "summary": "Get contextual coaching cards", "tags": [ "Coaching Cards" ] } }, "/ai-coaching/team-sessions/{teamId}/questions": { "post": { "operationId": "generateTeamSessionQuestions", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamSessionsQuestionsBodyDto" } } } }, "responses": { "200": { "description": "SSE stream of generated team-session questions (text/event-stream)", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Malformed teamId or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Gate-1 authorization denial (pre-stream)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "AI coaching authorization denied", "error": "THOMAI_AUTHORIZATION_DENIED" } } } } }, "summary": "Generate team-session coaching questions", "tags": [ "Team Sessions" ] } }, "/assessments/submit": { "post": { "operationId": "submitAssessmentResponses", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitAssessmentRequestDto" } } } }, "responses": { "201": { "description": "Assessment submitted, scoring enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitAssessmentResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Submit assessment responses for scoring", "tags": [ "Behaviour" ] } }, "/assessments/connection-power": { "get": { "operationId": "getMyConnectionPower", "parameters": [], "responses": { "200": { "description": "Connection Power type + completion timestamp (both null if never assessed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPowerResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Get the authenticated user's own Connection Power", "tags": [ "Behaviour" ] } }, "/assessments/status/{token}": { "get": { "operationId": "getAssessmentStatusByToken", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Assessment status for the given token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessmentStatusPublicResponseDto" } } } }, "401": { "description": "Invalid or expired access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get assessment status by access token (public, unauthenticated)", "tags": [ "Behaviour" ], "security": [] } }, "/assessments/context/{token}": { "post": { "description": "Validates the assess token and mints the shared thomas_invitation_context cookie for the token's assignment individual, returning the individualId + invited email so the unauthenticated /assess/:token new-user branch can prefill Keycloak registration and reach the invitation-aware session-creation path. The assess-flow analogue of /invitations/redeem.", "operationId": "getAssessmentContextByToken", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Assess registration context (cookie set via Set-Cookie)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessmentContextResponseDto" } } } }, "401": { "description": "Invalid or expired access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Resolve assess-link registration context by access token (public, unauthenticated)", "tags": [ "Behaviour" ], "security": [] } }, "/assessments/{token}/questions": { "get": { "operationId": "getAssessmentQuestionsBundle", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Encrypted question bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncryptedQuestionBundleResponseDto" } } } }, "401": { "description": "Invalid, expired, or completed access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "410": { "description": "The subject suppressed this personality purpose", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 410, "message": "This assessment draft is no longer available", "error": "ASSESSMENT_DRAFT_INVALIDATED" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get encrypted question bundle by access token (public, unauthenticated)", "tags": [ "Behaviour" ], "security": [] } }, "/assessments/{id}/status": { "get": { "operationId": "getAssessmentScoringStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current assessment status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessmentStatusResponseDto" } } } }, "400": { "description": "Malformed assessment id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Cannot access another user's assessment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Cannot access another user's assessment", "error": "ASSESSMENT_FORBIDDEN" } } } }, "404": { "description": "Assessment result not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Assessment result not found", "error": "ASSESSMENT_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get assessment scoring status", "tags": [ "Behaviour" ] } }, "/assessments/history": { "get": { "operationId": "listMyAssessmentHistory", "parameters": [ { "name": "assessmentType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "behaviour", "personality" ] } } ], "responses": { "200": { "description": "Assessment history for the current user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessmentHistoryResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Get assessment history for the authenticated user", "tags": [ "Behaviour" ] } }, "/assessments/compare/{individualId1}/{individualId2}": { "get": { "operationId": "getAssessmentComparisonProfile", "parameters": [ { "name": "individualId1", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "individualId2", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comparison profile with dual trait spectrums and comparison insights", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComparisonProfileResponseDto" } } } }, "400": { "description": "Malformed individualId path parameter or self-compare", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Caller must be one of the compared individuals, or admin/owner/manager", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Not permitted to compare these individuals", "error": "ASSESSMENT_FORBIDDEN" } } } }, "404": { "description": "No scored assessment found for one or both individuals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No scored assessment found", "error": "ASSESSMENT_PROFILE_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get comparison profile for two individuals", "tags": [ "Behaviour" ] } }, "/assessments/profile/{individualId}": { "get": { "operationId": "getAssessmentBehaviourProfile", "parameters": [ { "name": "individualId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Behaviour profile with trait spectrums and solo insights", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BehaviourProfileResponseDto" } } } }, "400": { "description": "Malformed individualId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Cannot access another user's assessment profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Cannot access another user's assessment profile", "error": "ASSESSMENT_FORBIDDEN" } } } }, "404": { "description": "No scored assessment found for this individual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No scored assessment found for this individual", "error": "ASSESSMENT_PROFILE_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get behaviour profile for an individual", "tags": [ "Behaviour" ] } }, "/assessments/assignments": { "post": { "operationId": "createAssessmentAssignment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssignmentRequestDto" } } } }, "responses": { "201": { "description": "Assignment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Refused for one of two reasons: the tenant’s effective plan tier does not include the capability the requested instrument belongs to (envelope `INSUFFICIENT_TIER`, decided first, and applying to any caller) — or insufficient role, owner or admin required for cross-user assignment (envelope `AUTH_INSUFFICIENT_ROLE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Only owners and admins can assign assessments to other users", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Create assessment assignment", "tags": [ "Assignments" ] }, "get": { "operationId": "listAssessmentAssignments", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "COMPLETED", "EXPIRED" ] } }, { "name": "individualId", "required": false, "in": "query", "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "description": "List of assignments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentListResponseDto" } } } }, "400": { "description": "Malformed individualId query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — owner or admin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "List assessment assignments", "tags": [ "Assignments" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/assessments/assignments/bulk": { "post": { "operationId": "bulkCreateAssessmentAssignments", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateAssignmentRequestDto" } } } }, "responses": { "201": { "description": "Bulk assignments created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssignmentResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Refused for one of two reasons: insufficient role, owner or admin required (envelope `AUTH_INSUFFICIENT_ROLE`, decided first because the role guard is global); or the tenant’s effective plan tier does not include the capability the requested instrument belongs to (envelope `INSUFFICIENT_TIER`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "One or more individuals not found in organisation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "One or more individuals not found in organisation", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } } }, "summary": "Bulk create assessment assignments", "tags": [ "Assignments" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/assessments/assignments/{id}": { "get": { "operationId": "getAssessmentAssignment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Assignment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — owner or admin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Assignment not found", "error": "ASSESSMENT_ASSIGNMENT_NOT_FOUND" } } } } }, "summary": "Get assignment by ID", "tags": [ "Assignments" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/assessments/assignments/{id}/resume": { "post": { "operationId": "resumeAssessmentAssignment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fresh access token minted for the assignee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeAssignmentResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Caller is not the assignee of this assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Caller is not the assignee of this assignment", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Assignment not found", "error": "ASSESSMENT_ASSIGNMENT_NOT_FOUND" } } } } }, "summary": "Resume an assigned assessment (assignee only)", "tags": [ "Assignments" ] } }, "/assessments/assignments/{id}/status": { "patch": { "operationId": "updateAssessmentAssignmentStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssignmentStatusDto" } } } }, "responses": { "200": { "description": "Assignment status updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentResponseDto" } } } }, "400": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Invalid status transition", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — owner or admin required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Assignment not found", "error": "ASSESSMENT_ASSIGNMENT_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Transition assignment status", "tags": [ "Assignments" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/candidates/assessments/bulk-assign": { "post": { "operationId": "bulkAssignCandidateAssessments", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateAssignmentRequestDto" } } } }, "responses": { "200": { "description": "Best-effort per-item results with a summary tally", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandidateBulkAssignResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Refused for one of three reasons: insufficient role (owner or admin required), envelope `AUTH_INSUFFICIENT_ROLE`; the tenant’s effective plan tier does not include the Candidates capability, envelope `INSUFFICIENT_TIER`; or that tier does not include the capability the requested instrument belongs to, also envelope `INSUFFICIENT_TIER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "One or more targets are missing, tombstoned, or confidential and out of the caller circle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Individuals not found in this organisation", "error": "ASSIGNMENT_INDIVIDUAL_NOT_FOUND" } } } } }, "summary": "Bulk-assign an assessment to many candidates (two-tier, fail-closed)", "tags": [ "Assignments" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/assessments/assignments/reminders": { "post": { "operationId": "sendAssessmentReminder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAssessmentReminderRequestDto" } } } }, "responses": { "200": { "description": "Reminder dispatched (or a no-op replay within the window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAssessmentReminderResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "No outstanding PENDING assignment for the subject in the caller’s tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No outstanding assessment to remind about", "error": "ASSESSMENT_REMINDER_NOT_FOUND" } } } } }, "summary": "Remind a colleague to complete their pending assessment", "tags": [ "Assignments" ] } }, "/assessments/reuse-check": { "get": { "operationId": "checkAssessmentConsentReuse", "parameters": [], "responses": { "200": { "description": "Reuse eligibility check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReuseCheckResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Check if the caller has existing results to reuse for current tenant", "tags": [ "Behaviour" ] } }, "/assessments/{resultId}/consent": { "post": { "operationId": "grantAssessmentConsent", "parameters": [ { "name": "resultId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentBodyDto" } } } }, "responses": { "200": { "description": "Consent already exists (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentResponseDto" } } } }, "201": { "description": "Consent granted, result shared with tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentResponseDto" } } } }, "400": { "description": "Malformed resultId or result not scored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Cannot consent to share another user's result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Cannot consent to share another user's result", "error": "CONSENT_FORBIDDEN" } } } }, "404": { "description": "Assessment result not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Assessment result not found", "error": "CONSENT_RESULT_NOT_FOUND" } } } } }, "summary": "Grant consent to share an assessment result with a tenant", "tags": [ "Behaviour" ] } }, "/claims": { "post": { "operationId": "initiateAssessmentClaim", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateClaimDto" } } } }, "responses": { "201": { "description": "Claim initiated, verification email sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateClaimResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "No claimable assessment history found for this email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No claimable assessment history found", "error": "CLAIM_NO_HISTORY" } } } }, "409": { "description": "A claim is already pending for this orphan individual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "A claim is already pending", "error": "CLAIM_ALREADY_PENDING" } } } } }, "summary": "Initiate a claim for historical assessment results", "tags": [ "Claims" ] } }, "/claims/resend": { "post": { "operationId": "resendAssessmentClaimEmail", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendClaimDto" } } } }, "responses": { "202": { "description": "Verification email resend accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendClaimResponseDto" } } } }, "400": { "description": "No pending claim to resend (CLAIM_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "No pending claim found", "error": "CLAIM_TOKEN_INVALID" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "429": { "description": "Resend cooldown (CLAIM_RESEND_COOLDOWN) or limit (CLAIM_RESEND_LIMIT) reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "Resend cooldown or limit reached", "error": "CLAIM_RESEND_COOLDOWN" } } } } }, "summary": "Resend claim verification email", "tags": [ "Claims" ] } }, "/claims/verify": { "post": { "operationId": "verifyAssessmentClaim", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyClaimDto" } } } }, "responses": { "200": { "description": "Claim verified, merge completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyClaimResponseDto" } } } }, "400": { "description": "Invalid or already-used token (CLAIM_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Invalid or already-used token", "error": "CLAIM_TOKEN_INVALID" } } } }, "410": { "description": "Token has expired (CLAIM_TOKEN_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 410, "message": "Token has expired", "error": "CLAIM_TOKEN_EXPIRED" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Verify claim token and trigger merge (unauthenticated — email link)", "tags": [ "Claims" ], "security": [] } }, "/assessments/profile/{individualId}/pdf": { "post": { "operationId": "requestAssessmentPdf", "parameters": [ { "name": "individualId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfDownloadRequestDto" } } } }, "responses": { "202": { "description": "PDF generation job enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfDownloadResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Cannot generate PDF for another user's profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Cannot generate PDF for another user's profile", "error": "ASSESSMENT_FORBIDDEN" } } } }, "404": { "description": "No behaviour profile found (neutral 404)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No behaviour profile found", "error": "ASSESSMENT_PROFILE_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Request PDF generation for a behaviour profile", "tags": [ "Reports" ] } }, "/assessments/pdf/{jobId}": { "get": { "operationId": "getAssessmentPdfStatus", "parameters": [ { "name": "jobId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF binary when job is complete", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "202": { "description": "Job still processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfStatusResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Job not found or expired ({ status: \"failed\" })", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfStatusResponseDto" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Get PDF generation status or download PDF", "tags": [ "Reports" ] } }, "/auth/session": { "post": { "description": "Exchange a Keycloak token for a platform JWT session", "operationId": "login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequestDto" } } } }, "responses": { "200": { "description": "Session created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "400": { "description": "Invalid Keycloak token format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Invalid or unverifiable Keycloak token", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "No organisation (IDENTITY_NO_ORGANISATION), account not found (IDENTITY_ACCOUNT_NOT_FOUND), or account disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "User does not belong to any organisation", "error": "IDENTITY_NO_ORGANISATION" } } } }, "429": { "description": "Rate limit exceeded (per-IP public-route throttle)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Create session", "tags": [ "Authentication" ], "security": [] } }, "/auth/session/refresh": { "post": { "description": "Refresh an existing session using the httpOnly refresh token cookie", "operationId": "refreshAuthToken", "parameters": [], "responses": { "200": { "description": "Session refreshed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "401": { "description": "No refresh token, invalid/expired token, account not found, or account disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Refresh session", "tags": [ "Authentication" ], "security": [] } }, "/auth/logout": { "post": { "description": "Terminate the current session and clear refresh token cookie", "operationId": "logout", "parameters": [], "responses": { "204": { "description": "Session terminated successfully" }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Logout", "tags": [ "Authentication" ] } }, "/auth/session/switch-org": { "post": { "description": "Switch the active organisation and issue a new JWT with the target tenant context", "operationId": "switchOrganisation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchOrgRequestDto" } } } }, "responses": { "200": { "description": "Organisation switched, new session issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "400": { "description": "Already in this organisation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Not a member of the target organisation (AUTH_ORG_NOT_MEMBER), the invitation to it has not been accepted (AUTH_ORG_MEMBERSHIP_PENDING), or the requester is only a candidate there (AUTH_ORG_CANDIDATE_ONLY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "summary": "Switch organisation", "tags": [ "Authentication" ] } }, "/invitations": { "post": { "description": "Send an invitation to join the current organisation", "operationId": "createInvitation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationRequestDto" } } } }, "responses": { "201": { "description": "Invitation created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role — admin or owner required (AUTH_INSUFFICIENT_ROLE), or the organisation is seat-blocked (SEATS_BLOCKED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Create invitation", "tags": [ "Invitations" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/invitations/validate": { "post": { "description": "Read-only resolution of an invitation token: returns its lifecycle state (pending / accepted / revoked / expired), the invited email and org name, role, and resolved identity. NEVER mutates the token — safe for email scanners and re-clicks (THO-652).", "operationId": "validateInvitationToken", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemInvitationRequestDto" } } } }, "responses": { "200": { "description": "Token resolved (state may be pending/accepted/revoked/expired)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateInvitationResponseDto" } } } }, "400": { "description": "Invalid invitation token (IDENTITY_INVITATION_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Invalid invitation token", "error": "IDENTITY_INVITATION_INVALID" } } } }, "404": { "description": "Invitation not found (IDENTITY_INVITATION_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Invitation not found", "error": "IDENTITY_INVITATION_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Resolve invitation token state", "tags": [ "Invitations" ], "security": [] } }, "/invitations/redeem": { "post": { "description": "Redeem an invitation token to complete the onboarding process", "operationId": "redeemInvitation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemInvitationRequestDto" } } } }, "responses": { "200": { "description": "Invitation redeemed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemInvitationResponseDto" } } } }, "400": { "description": "Invalid invitation token (IDENTITY_INVITATION_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Invalid invitation token", "error": "IDENTITY_INVITATION_INVALID" } } } }, "404": { "description": "Invitation not found (IDENTITY_INVITATION_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Invitation not found", "error": "IDENTITY_INVITATION_NOT_FOUND" } } } }, "410": { "description": "Invitation has expired (IDENTITY_INVITATION_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 410, "message": "Invitation has expired", "error": "IDENTITY_INVITATION_EXPIRED" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "summary": "Redeem invitation", "tags": [ "Invitations" ], "security": [] } }, "/content/profile-insights/{individualId}": { "get": { "description": "Returns the resolved Dynamic Card set (heading + token-substituted body) for the caller's own 4-band self-view behaviour profile, plus the never-blank page floor. Self-view only — another individual's cards are served by a separate endpoint.", "operationId": "getProfileInsights", "parameters": [ { "name": "individualId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "slots", "required": false, "in": "query", "description": "comma-separated bespoke-surface content slots to resolve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolved cards (app-default order) + nullable floor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileInsightCardsResponseDto" } } } }, "400": { "description": "Malformed individualId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Requested another individual (this endpoint is self-view only) — CONTENT_PROFILE_INSIGHTS_FORBIDDEN (403)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Cannot access another individual's profile insights", "error": "CONTENT_PROFILE_INSIGHTS_FORBIDDEN" } } } }, "422": { "description": "The behaviour result has no frozen bands — CONTENT_BANDING_NOT_FROZEN (422)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "The behaviour result has no frozen bands", "error": "CONTENT_BANDING_NOT_FROZEN" } } } } }, "summary": "Resolved self-view profile insight cards", "tags": [ "Behaviour" ] } }, "/content/colleague-profile-insights/{companyIndividualId}": { "get": { "description": "Returns the permission-filtered Dynamic Card set (other perspective, the colleague's name substituted) the viewer may see about the colleague. Backend enforces the manager/Admin-Owner relationship gate AND the per-card org auto-visibility gate; an unpermitted viewer receives an empty card set.", "operationId": "getColleagueProfileInsights", "parameters": [ { "name": "companyIndividualId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "slots", "required": false, "in": "query", "description": "comma-separated bespoke-surface content slots to resolve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Permitted other-perspective cards (app-default order) + null floor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileInsightCardsResponseDto" } } } }, "400": { "description": "Malformed companyIndividualId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "The colleague does not exist in the viewer’s tenant — IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND (404)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Colleague not found in the viewer tenant", "error": "IDENTITY_COMPANY_INDIVIDUAL_NOT_FOUND" } } } }, "422": { "description": "The behaviour result has no frozen bands — CONTENT_BANDING_NOT_FROZEN (422)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "The behaviour result has no frozen bands", "error": "CONTENT_BANDING_NOT_FROZEN" } } } } }, "summary": "Resolved other-perspective (manager) profile insight cards for a colleague", "tags": [ "Behaviour" ] } }, "/feedback": { "post": { "operationId": "captureFeedback", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "202": { "description": "Feedback capture accepted (empty body)" }, "400": { "description": "Invalid feedback capture payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "A self-perspective rating targets someone other than the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "A self-perspective feedback rating may only target the caller's own content", "error": "FEEDBACK_NOT_SUBJECT" } } } }, "404": { "description": "Feedback subject is not a live member of the current tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Feedback subject does not exist", "error": "FEEDBACK_SUBJECT_NOT_FOUND" } } } } }, "security": [ { "bearer": [] } ], "summary": "Capture one content-feedback event — a rating OR a rating-less engagement event (one action = one row). No read path exists.", "tags": [ "Feedback" ], "x-badges": [ { "name": "Viewer" }, { "name": "Admin" }, { "name": "Owner" } ] } }, "/onboarding/complete": { "post": { "description": "Record consent and profile details for first-time platform onboarding", "operationId": "completeOnboarding", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteOnboardingRequestDto" } } } }, "responses": { "200": { "description": "Onboarding completed (or already completed — idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteOnboardingResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Global access denied (IDENTITY_GLOBAL_ACCESS_DENIED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Global access denied", "error": "IDENTITY_GLOBAL_ACCESS_DENIED" } } } }, "404": { "description": "Account not found (IDENTITY_ACCOUNT_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Account not found", "error": "IDENTITY_ACCOUNT_NOT_FOUND" } } } } }, "summary": "Complete platform onboarding", "tags": [ "Onboarding" ], "x-badges": [ { "name": "Self Access" } ] } }, "/onboarding/status": { "get": { "description": "Check whether the user has completed platform onboarding. Returns profile fields for pre-population when not completed.", "operationId": "getOnboardingStatus", "parameters": [], "responses": { "200": { "description": "Onboarding status returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingStatusResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Global access denied (IDENTITY_GLOBAL_ACCESS_DENIED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Global access denied", "error": "IDENTITY_GLOBAL_ACCESS_DENIED" } } } }, "404": { "description": "Account not found (IDENTITY_ACCOUNT_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Account not found", "error": "IDENTITY_ACCOUNT_NOT_FOUND" } } } } }, "summary": "Get onboarding status", "tags": [ "Onboarding" ], "x-badges": [ { "name": "Self Access" } ] } }, "/personality/transparency-acceptances": { "post": { "operationId": "recordTransparencyAcceptance", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordTransparencyAcceptanceRequestDto" } } } }, "responses": { "201": { "description": "The recorded (or idempotently-existing) transparency acceptance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransparencyAcceptanceResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Caller is not the subject of the assignment (TRANSPARENCY_NOT_SUBJECT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Caller is not the assignment subject", "error": "TRANSPARENCY_NOT_SUBJECT" } } } }, "404": { "description": "Assignment missing/cross-tenant (TRANSPARENCY_ASSIGNMENT_NOT_FOUND) or no effective terms (TRANSPARENCY_TERMS_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Assignment or effective terms not found", "error": "TRANSPARENCY_ASSIGNMENT_NOT_FOUND" } } } }, "409": { "description": "A concurrent acceptance race left no committed row (TRANSPARENCY_ACCEPTANCE_CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Concurrent acceptance conflict", "error": "TRANSPARENCY_ACCEPTANCE_CONFLICT" } } } } }, "security": [ { "bearer": [] } ], "summary": "Record an immutable transparency/acceptance register entry (FR10/FR36).", "tags": [ "Behaviour" ] } }, "/personality/reader/{individualId}": { "get": { "operationId": "getPersonalityReaderResult", "parameters": [ { "name": "individualId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The reader result — `ready` with the gradient, or neutral `pending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalityReaderResultDto" } } } }, "400": { "description": "Malformed individualId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Owner or admin role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "security": [ { "bearer": [] } ], "summary": "Project a colleague's Personality result at the reader (Admin gradient) tier.", "tags": [ "Personality" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/personality/reader/{individualId}/self-view": { "get": { "operationId": "getPersonalityReaderSelfView", "parameters": [ { "name": "individualId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The reader self-view — `ready` with the framed self-content, or neutral `pending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalityReaderSelfViewResultDto" } } } }, "400": { "description": "Malformed individualId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Owner or admin role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "security": [ { "bearer": [] } ], "summary": "Project a colleague's self-view content for the reader-into-self candidate report.", "tags": [ "Personality" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/personality/{individualId}/pdf": { "post": { "operationId": "requestPersonalityPdfExport", "parameters": [ { "name": "individualId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalityPdfRequestDto" } } } }, "responses": { "202": { "description": "PDF generation job enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalityPdfResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Cannot export another user's result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Cannot export another user's result", "error": "ASSESSMENT_FORBIDDEN" } } } }, "404": { "description": "No personality result / withheld / suppressed (neutral 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "No personality result found for this individual", "error": "ASSESSMENT_PROFILE_NOT_FOUND" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "security": [ { "bearer": [] } ], "summary": "Request a projection-respecting Personality PDF export for an individual", "tags": [ "Personality" ] } }, "/personality/pdf/{jobId}": { "get": { "operationId": "getPersonalityPdfExportStatus", "parameters": [ { "name": "jobId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF binary when the job is complete", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "202": { "description": "Job still processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfStatusResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Job not found / expired / not yours / not a personality export ({ status: \"failed\" }).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfStatusResponseDto" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit block expires before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Configured request limit for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the active rate-limit window; zero when blocked.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit block expires.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", "error": "HTTP_TOO_MANY_REQUESTS" } } } } }, "security": [ { "bearer": [] } ], "summary": "Poll a Personality PDF job or download the PDF", "tags": [ "Personality" ] } }, "/teams": { "post": { "operationId": "createConnectionTeam", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExplicitTeamDto" } } } }, "responses": { "201": { "description": "Connection team created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWithMembersResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Creator has not completed a scored behaviour assessment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "You must complete your behaviour assessment before creating a team", "error": "ASSESSMENT_REQUIRED" } } } } }, "summary": "Create a connection team", "tags": [ "Teams" ] }, "get": { "operationId": "listConnectionTeams", "parameters": [], "responses": { "200": { "description": "List of connection teams for the current user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectionTeamsResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "List connection teams for the current user", "tags": [ "Teams" ] } }, "/teams/{teamId}/dynamics": { "get": { "operationId": "getConnectionTeamDynamics", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team connection dynamics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDynamicsResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Get team connection dynamics", "tags": [ "Teams" ] } }, "/teams/{teamId}/dynamics/profile/{power}": { "get": { "operationId": "getConnectionPowerProfile", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "power", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection power profile for the selected team power", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPowerProfileResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Get a connection power profile for a team", "tags": [ "Teams" ] } }, "/teams/{teamId}/sessions/summary": { "get": { "operationId": "getConnectionTeamSessionSummary", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team session summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSessionsSummaryResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Team not found or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Get a team session summary", "tags": [ "Teams" ] } }, "/teams/{teamId}/sessions": { "get": { "operationId": "listConnectionTeamSessions", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 9007199254740991, "default": 1, "type": "integer" } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 50, "default": 10, "type": "integer" } } ], "responses": { "200": { "description": "Team sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSessionListResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Team not found or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "List sessions for a connection team", "tags": [ "Teams" ] } }, "/teams/{teamId}": { "get": { "operationId": "getConnectionTeam", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWithMembersResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Team not found or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Get a connection team", "tags": [ "Teams" ] }, "patch": { "operationId": "updateConnectionTeam", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExplicitTeamDto" } } } }, "responses": { "200": { "description": "Connection team updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWithMembersResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Team not found or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Update a connection team", "tags": [ "Teams" ] }, "delete": { "operationId": "deleteConnectionTeam", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Connection team deleted" }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Delete a connection team", "tags": [ "Teams" ] } }, "/teams/{teamId}/transfer-ownership": { "put": { "operationId": "transferConnectionTeamOwnership", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamTransferOwnershipDto" } } } }, "responses": { "200": { "description": "Connection team ownership transferred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWithMembersResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Team not found or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Transfer connection team ownership", "tags": [ "Teams" ] } }, "/teams/{teamId}/reassign-owner": { "put": { "operationId": "reassignConnectionTeamOwner", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReassignTeamOwnerDto" } } } }, "responses": { "200": { "description": "Connection team owner reassigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReassignTeamOwnerResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Reassign a connection team owner", "tags": [ "Teams" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/individuals/{id}/connection-reflections": { "get": { "operationId": "getMyConnectionReflections", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The individual connection reflections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileConnectionReflectionsResponseDto" } } } }, "400": { "description": "Malformed individual id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role, or reflections are private to the subject", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Individual not found in the caller tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Individual not found", "error": "INDIVIDUAL_NOT_FOUND" } } } } }, "summary": "Get individual connection reflections", "tags": [ "My Connection" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/individuals/{id}/connection-score": { "get": { "operationId": "getMyConnectionScore", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The individual connection score (all-null when unscored)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndividualConnectionScoreResponseDto" } } } }, "400": { "description": "Malformed individual id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Individual not found in the caller tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Individual not found", "error": "INDIVIDUAL_NOT_FOUND" } } } } }, "summary": "Get an individual connection score", "tags": [ "My Connection" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/individuals/{id}/connection-team-results": { "get": { "operationId": "getMyConnectionTeamResults", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The individual connection team results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileConnectionTeamResultsResponseDto" } } } }, "400": { "description": "Malformed individual id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE), or a non-self, non-service caller whose token carries no individual_id, so the colleague viewer-intersection cannot be scoped (VIEWER_IDENTITY_MISSING, THO-1788)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Individual not found in the caller tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Individual not found", "error": "INDIVIDUAL_NOT_FOUND" } } } } }, "summary": "Get individual connection team results", "tags": [ "My Connection" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/organisation/heatmap": { "get": { "operationId": "getConnectionHeatmap", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 9007199254740991, "default": 1, "type": "integer" } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "viewMode", "required": true, "in": "query", "description": "FR53 Score/Trends mode (no default — endpoint chooses)", "examples": [ "score" ], "schema": { "type": "string", "enum": [ "score", "trends" ] } }, { "name": "period", "required": true, "in": "query", "description": "ISO month for heatmap context; mirrors ConnectionMeasureRunResponseSchema.period", "examples": [ "2026-04" ], "schema": { "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "type": "string" } }, { "name": "teamTypeFilter", "required": false, "in": "query", "description": "DEPRECATED (replaced by departmentFilter/statusFilter/hostFilter): legacy team type filter, still honoured for one release while clients migrate. Omit for both types.", "examples": [ "implicit" ], "schema": { "type": "string", "enum": [ "implicit", "explicit" ] } }, { "name": "departmentFilter", "required": false, "in": "query", "description": "filter to teams whose member departments intersect this selection (OR within filter). Omit for no department filter.", "schema": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 } } }, { "name": "statusFilter", "required": false, "in": "query", "description": "filter rows by overall cell state. Mapping: active→scored, inProgress→in-progress, insufficient→insufficient, noData→no-run. OR within filter. Omit for no status filter.", "schema": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "active", "inProgress", "insufficient", "noData" ] } } }, { "name": "hostFilter", "required": false, "in": "query", "description": "filter to teams whose host (team owner for explicit, manager link target for implicit) matches one of the supplied companyIndividual ids. Teams with host=null are excluded when this filter is set.", "schema": { "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, { "name": "nameSearch", "required": false, "in": "query", "description": "case-insensitive substring filter on team name; applied server-side so pagination operates on the filtered set", "examples": [ "eng" ], "schema": { "minLength": 1, "maxLength": 200, "type": "string" } } ], "responses": { "200": { "description": "Organization connection heatmap data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationHeatmapResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Get organization connection heatmap data", "tags": [ "Organization Connection" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/organisation/check-in-requests": { "post": { "operationId": "bulkDeployConnectionCheckIns", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeployRequestDto" } } } }, "responses": { "207": { "description": "Bulk deployment results with per-team status rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeployResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Request connection check-ins for multiple teams", "tags": [ "Organization Connection" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/organisation/teams/{teamId}/recurrence": { "put": { "operationId": "configureConnectionRecurrence", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurrenceConfigDto" } } } }, "responses": { "200": { "description": "Recurring connection check-in configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurrenceConfigResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Configure recurring connection check-ins", "tags": [ "Organization Connection" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/teams/{teamId}/check-in-requests": { "post": { "operationId": "requestConnectionCheckIn", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestCheckInDto" } } } }, "responses": { "201": { "description": "Check-in run requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestCheckInResponseDto" } } } }, "400": { "description": "Malformed teamId or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Request a connection check-in", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/teams/{teamId}/reflections": { "post": { "operationId": "startConnectionReflection", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Personal reflection run started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestCheckInResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Start a personal connection reflection", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/teams/{teamId}/runs/{runId}/participation": { "get": { "operationId": "getConnectionCheckInParticipation", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "runId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run participation counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipationResponseDto" } } } }, "400": { "description": "Malformed teamId or runId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Get connection check-in participation counts", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/teams/{teamId}/runs/historical": { "get": { "operationId": "listConnectionCheckIns", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Historical scored runs for the team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalRunListDto" } } } }, "400": { "description": "Malformed teamId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "List historical connection check-ins", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/teams/{teamId}/runs/{runId}/dimensions/{dimension}/content": { "get": { "operationId": "getConnectionDimensionContent", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "runId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "dimension", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "perspective", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "accept-language", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dimension narrative + habits content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionDimensionContentDto" } } } }, "400": { "description": "Malformed path parameter or unknown dimension", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Get connection dimension content", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/teams/{teamId}/runs/{runId}": { "get": { "operationId": "getConnectionCheckInRun", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "runId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Check-in run detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionMeasureRunResponseDto" } } } }, "400": { "description": "Malformed teamId or runId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Get a connection check-in run", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/teams/{teamId}/runs/{runId}/team-results-page": { "get": { "operationId": "getConnectionTeamResults", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "runId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team results page (scored run)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResultsPageResponseDto" } } } }, "400": { "description": "Malformed teamId or runId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team is not readable (TEAM_NOT_FOUND), or the run is missing or not scored (CONNECTION_RUN_NOT_SCORED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Get connection team results", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/teams/{teamId}/connection-summary": { "get": { "operationId": "getConnectionTeamSummary", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team connection summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamConnectionSummaryResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Get a team connection summary", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/teams/{teamId}/runs/{runId}/reminder": { "post": { "operationId": "sendConnectionCheckInReminder", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "runId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reminder dispatch result (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReminderResponseDto" } } } }, "400": { "description": "Malformed teamId or runId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Send a connection check-in reminder", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" } ] } }, "/teams/{teamId}/runs/{runId}/cancel": { "post": { "operationId": "cancelConnectionCheckInRun", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "runId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run cancellation result (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRunResponseDto" } } } }, "400": { "description": "Malformed teamId or runId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Cancel a connection check-in run", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" } ] } }, "/teams/{teamId}/measure": { "get": { "operationId": "getConnectionTeamMeasure", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team measure with current/last runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionMeasureResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Get the current connection measure for a team", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/teams/{teamId}/getting-started": { "get": { "operationId": "getConnectionGettingStartedProgress", "parameters": [ { "name": "teamId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Getting-started progress tracker", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GettingStartedTrackerResponseDto" } } } }, "400": { "description": "Malformed teamId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Team not found or not readable by the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Team not found", "error": "TEAM_NOT_FOUND" } } } } }, "summary": "Get connection getting-started progress", "tags": [ "Check-ins & Runs" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/runs/{runId}/questionnaire": { "get": { "operationId": "getConnectionQuestionnaire", "parameters": [ { "name": "runId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The shuffled questionnaire for the participant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetQuestionnaireResponseDto" } } } }, "400": { "description": "Malformed runId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Run not found or the caller is not a participant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Run not found", "error": "RUN_NOT_FOUND" } } } } }, "summary": "Get a connection questionnaire", "tags": [ "Questionnaires" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/runs/{runId}/submissions": { "post": { "operationId": "submitConnectionQuestionnaire", "parameters": [ { "name": "runId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitQuestionnaireDto" } } } }, "responses": { "201": { "description": "The submitted individual result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitQuestionnaireResponseDto" } } } }, "400": { "description": "Malformed runId path parameter or invalid submission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Run not found or the caller is not a participant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Run not found", "error": "RUN_NOT_FOUND" } } } }, "409": { "description": "The participant has already submitted this run (ALREADY_SUBMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Questionnaire already submitted for this run", "error": "ALREADY_SUBMITTED" } } } }, "422": { "description": "Not all questions were answered (INCOMPLETE_SUBMISSION)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 422, "message": "Submission is incomplete", "error": "INCOMPLETE_SUBMISSION" } } } } }, "summary": "Submit a connection questionnaire", "tags": [ "Questionnaires" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/runs/{runId}/individual-result": { "get": { "operationId": "getConnectionIndividualResult", "parameters": [ { "name": "runId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The individual results page for the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndividualResultsPageResponseDto" } } } }, "400": { "description": "Malformed runId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Insufficient role privileges (AUTH_INSUFFICIENT_ROLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } }, "404": { "description": "Run not found or the caller is not a participant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Run not found", "error": "RUN_NOT_FOUND" } } } } }, "summary": "Get an individual connection result", "tags": [ "Questionnaires" ], "x-badges": [ { "name": "Owner" }, { "name": "Admin" }, { "name": "Viewer" } ] } }, "/session-intents": { "get": { "operationId": "listConnectionSessionIntents", "parameters": [], "responses": { "200": { "description": "Available session intents", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionIntentResponseDto" } } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "List connection session intents", "tags": [ "Session Content" ] } }, "/discussion-items": { "get": { "operationId": "listConnectionDiscussionItems", "parameters": [ { "name": "intent", "required": true, "in": "query", "description": "selected session intent", "examples": [ "improve_communication" ], "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "Discussion items for the intent", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DiscussionItemResponseDto" } } } } }, "400": { "description": "Missing or invalid intent query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "List connection discussion items", "tags": [ "Session Content" ] } }, "/dive-in-content": { "get": { "operationId": "getConnectionSessionDiveInContent", "parameters": [ { "name": "intent", "required": true, "in": "query", "description": "selected session intent", "examples": [ "improve_communication" ], "schema": { "minLength": 1, "type": "string" } }, { "name": "phaseStep", "required": true, "in": "query", "description": "specific phase step to retrieve content for", "examples": [ 1 ], "schema": { "minimum": 1, "maximum": 50, "type": "integer" } }, { "name": "sessionId", "required": false, "in": "query", "description": "session id to apply curated discussion items (phaseStep=2)", "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "description": "Dive-in content blocks for the phase step", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiveInContentResponseDto" } } } }, "400": { "description": "Missing or invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Session not found or the caller is not a member (sessionId path only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Session not found", "error": "SESSION_NOT_FOUND" } } } } }, "summary": "Get connection session dive-in content", "tags": [ "Session Content" ] } }, "/sessions": { "post": { "operationId": "createConnectionSession", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionDto" } } } }, "responses": { "201": { "description": "Connection session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSessionResponseDto" } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Create a 1:1 connection session", "tags": [ "1:1 Sessions" ] } }, "/sessions/{id}": { "get": { "operationId": "getConnectionSession", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSessionResponseDto" } } } }, "400": { "description": "Malformed session id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Session not found or the caller is not a member of its team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Session not found", "error": "SESSION_NOT_FOUND" } } } } }, "summary": "Get a 1:1 connection session", "tags": [ "1:1 Sessions" ] }, "patch": { "operationId": "updateConnectionSession", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionDto" } } } }, "responses": { "200": { "description": "Connection session updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSessionResponseDto" } } } }, "400": { "description": "Malformed session id path parameter or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Session not found or the caller is not a member of its team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Session not found", "error": "SESSION_NOT_FOUND" } } } } }, "summary": "Update a 1:1 connection session", "tags": [ "1:1 Sessions" ] } }, "/sessions/{id}/complete": { "post": { "operationId": "completeConnectionSession", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteSessionDto" } } } }, "responses": { "201": { "description": "Connection session completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSessionResponseDto" } } } }, "400": { "description": "Malformed session id path parameter or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Session not found or the caller is not a member of its team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Session not found", "error": "SESSION_NOT_FOUND" } } } } }, "summary": "Complete a 1:1 connection session", "tags": [ "1:1 Sessions" ] } }, "/sessions/{id}/reflect-draft": { "put": { "operationId": "saveConnectionSessionReflectDraft", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveReflectDraftDto" } } } }, "responses": { "200": { "description": "Connection session reflection draft saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSessionResponseDto" } } } }, "400": { "description": "Malformed session id path parameter or invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Session not found or the caller is not a member of its team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Session not found", "error": "SESSION_NOT_FOUND" } } } } }, "summary": "Save a connection session reflection draft", "tags": [ "1:1 Sessions" ] } }, "/sessions/{sessionId}/action-items/{actionItemId}": { "patch": { "operationId": "completeConnectionSessionActionItem", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "actionItemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session action item completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionActionItemResponseDto" } } } }, "400": { "description": "Malformed sessionId or actionItemId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Session not found or the caller is not a member of its team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Session not found", "error": "SESSION_NOT_FOUND" } } } } }, "summary": "Complete a connection session action item", "tags": [ "1:1 Sessions" ] } }, "/sessions/{id}/suggested-actions": { "get": { "operationId": "listConnectionSessionSuggestedActions", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Suggested actions for the session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestedActionsResponseDto" } } } }, "400": { "description": "Malformed session id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed (uuid is expected)", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Session not found or the caller is not a member of its team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Session not found", "error": "SESSION_NOT_FOUND" } } } } }, "summary": "Get suggested actions for a connection session", "tags": [ "1:1 Sessions" ] } }, "/activity-feed": { "get": { "operationId": "listActivityFeed", "parameters": [ { "name": "type", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "default": "all", "type": "string", "enum": [ "all", "invitations", "action_items", "team_updates" ] } }, { "name": "cursor", "required": false, "in": "query", "x-nestjs_zod-parent-additional-properties": false, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "Cursor-paginated activity feed entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedListResponseDto" } } } }, "400": { "description": "Invalid cursor or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "List activity feed entries", "tags": [ "Activity Feed" ] } }, "/activity-feed/{entryId}/dismiss": { "post": { "operationId": "dismissActivityFeedEntry", "parameters": [ { "name": "entryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Activity feed entry dismissed" }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Dismiss an activity feed entry", "tags": [ "Activity Feed" ] } }, "/activity-feed/{entryId}/complete": { "post": { "operationId": "completeActivityFeedActionItem", "parameters": [ { "name": "entryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Completion accepted (empty body)" }, "400": { "description": "Non-actionable entry or invalid state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "404": { "description": "Feed entry not found (HOME_FEED_ENTRY_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 404, "message": "Feed entry not found", "error": "HOME_FEED_ENTRY_NOT_FOUND" } } } } }, "summary": "Complete an activity feed action item", "tags": [ "Activity Feed" ] } }, "/habit-streaks/today": { "get": { "operationId": "getHabitStreak", "parameters": [], "responses": { "200": { "description": "Today's habit streak item and streak state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HabitTodayResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Get today's habit streak item", "tags": [ "Habits" ] } }, "/habit-streaks/complete": { "post": { "operationId": "completeHabitStreak", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HabitStreakCompleteRequestDto" } } } }, "responses": { "200": { "description": "Updated habit streak state after completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HabitTodayResponseDto" } } } }, "400": { "description": "Invalid reflection body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Complete today's habit streak item", "tags": [ "Habits" ] } }, "/habit-streaks/dismiss": { "post": { "operationId": "dismissHabitStreak", "parameters": [], "responses": { "200": { "description": "Habit streak state after dismissal (streak untouched)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HabitTodayResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } } }, "summary": "Dismiss today's habit streak item", "tags": [ "Habits" ] } }, "/appreciations": { "post": { "operationId": "sendAppreciation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppreciationSendRequestDto" } } } }, "responses": { "201": { "description": "Appreciation sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppreciationSendResponseDto" } } } }, "400": { "description": "Self-send, invalid recipient, or invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "The per-tenant appreciation feature flag is off (HOME_APPRECIATION_FEATURE_DISABLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Appreciation is disabled for this tenant", "error": "HOME_APPRECIATION_FEATURE_DISABLED" } } } }, "409": { "description": "One appreciation per day per recipient pair (APPRECIATION_RATE_LIMIT_EXCEEDED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 409, "message": "Appreciation rate limit exceeded", "error": "APPRECIATION_RATE_LIMIT_EXCEEDED" } } } } }, "summary": "Send appreciation to a colleague", "tags": [ "Recognition" ] } }, "/appreciations/received/{eventId}": { "get": { "operationId": "getReceivedAppreciation", "parameters": [ { "name": "eventId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Received appreciation detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppreciationReceivedDetailDto" } } } }, "400": { "description": "Malformed eventId path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 400, "message": "Validation failed", "error": "HTTP_BAD_REQUEST" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Caller is not the recipient / row missing (APPRECIATION_FORBIDDEN — no existence leak)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Not the recipient of this appreciation", "error": "APPRECIATION_FORBIDDEN" } } } } }, "summary": "Get received appreciation detail", "tags": [ "Recognition" ] } }, "/organisation/kpis": { "get": { "operationId": "getOrganisationKpis", "parameters": [], "responses": { "200": { "description": "Latest org KPI snapshot (or cold-start nulls)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgKpisResponseDto" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "403": { "description": "Admin or owner role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" }, "example": { "statusCode": 403, "message": "Insufficient role privileges", "error": "AUTH_INSUFFICIENT_ROLE" } } } } }, "summary": "Get organization KPI snapshot", "tags": [ "Organization Analytics" ], "x-badges": [ { "name": "Admin" }, { "name": "Owner" } ] } }, "/assist": { "post": { "operationId": "assist", "summary": "Streaming assist (SSE)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_AssistRequest" } } } }, "responses": { "200": { "description": "text/event-stream of SseEvent values", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/ThomAI_SseEvent" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "message", "error" ], "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "default": { "description": "Error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_ThomaiErrorEnvelope" } } } } }, "tags": [ "AI Coaching" ] } }, "/team-sessions/questions": { "post": { "operationId": "teamSessionsQuestions", "summary": "Generate session discussion questions (SSE)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_TeamSessionsQuestionsRequest" } } } }, "responses": { "200": { "description": "text/event-stream of SseEvent values", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/ThomAI_SseEvent" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "message", "error" ], "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "default": { "description": "Error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_ThomaiErrorEnvelope" } } } } }, "tags": [ "Team Sessions" ] } }, "/compact": { "post": { "operationId": "compact", "summary": "Compact a conversation history into an opaque blob", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_CompactRequest" } } } }, "responses": { "200": { "description": "Compaction result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_CompactResponse" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "message", "error" ], "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "default": { "description": "Error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_ThomaiErrorEnvelope" } } } } }, "tags": [ "AI Coaching" ] } }, "/cards": { "post": { "operationId": "cards", "summary": "Fetch cards for a page", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_CardsRequest" } } } }, "responses": { "200": { "description": "Card list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_CardsResponse" } } } }, "401": { "description": "Invalid or missing authentication token (AUTH_TOKEN_INVALID)", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "message", "error" ], "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "example": { "statusCode": 401, "message": "Invalid or missing authentication token", "error": "AUTH_TOKEN_INVALID" } } } }, "default": { "description": "Error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThomAI_ThomaiErrorEnvelope" } } } } }, "tags": [ "Coaching Cards" ] } } }, "info": { "title": "Thomas Platform API", "description": "CXI platform API — auto-generated from Zod contracts", "version": "1.0", "contact": { "name": "Thomas International", "url": "https://thomas.co", "email": "support@thomas.co" } }, "tags": [ { "name": "Authentication", "description": "Authentication, account sessions, first-login onboarding, personal profile and invitations — the access plumbing for every individual.\n\nSign-in, token exchange and session lifecycle for an individual." }, { "name": "Accounts", "description": "The authenticated individual's account record and session state." }, { "name": "Onboarding", "description": "First-login self-service that completes an individual's initial setup." }, { "name": "My Profile", "description": "The signed-in individual's own profile — read and update personal details." }, { "name": "Invitations", "description": "Invitations to join an organization — issue, accept and track." }, { "name": "Colleagues & Profiles", "description": "The employee population — directory, profiles, administration, roles and the manager/org-structure graph. One population; tags split by what you are doing, not who.\n\nBrowse the employee directory and view colleague profiles, photos and about-me content." }, { "name": "People Administration", "description": "Administer the employee population — bulk operations and company-individual records." }, { "name": "Roles & Permissions", "description": "Assign and read the roles and permissions that govern what a person can do." }, { "name": "Manager Links", "description": "The reporting graph — link individuals to their managers and read the structure." }, { "name": "Memberships", "description": "An individual's organization memberships." }, { "name": "Organization Profile", "description": "Company-level profile, branding and analytics. Analytics anticipates the Growth 'Analyse Space'.\n\nThe company's own profile record — read and maintain organization details." }, { "name": "Branding", "description": "Organization branding assets such as the company logo." }, { "name": "Organization Analytics", "description": "Aggregate organization-level metrics and key performance indicators." }, { "name": "Teams", "description": "The core product — teams, connection measures, runs, questionnaires, 1:1 sessions and the org-level rollup.\n\nCreate and manage the teams that connection measures run against." }, { "name": "Check-ins & Runs", "description": "Schedule and manage connection check-in runs across a team." }, { "name": "Questionnaires", "description": "The connection questionnaires a run administers." }, { "name": "1:1 Sessions", "description": "One-to-one connection sessions between an individual and their manager." }, { "name": "Session Content", "description": "The prompts and discussion content that populate a connection session." }, { "name": "My Connection", "description": "The signed-in individual's own connection reflections, score and team results." }, { "name": "Organization Connection", "description": "The organization-wide rollup of connection measures." }, { "name": "Behaviour", "description": "Instrument delivery and results. A master group with one tag per instrument — Behaviour today; Personality, EI and Aptitude in a later release.\n\nBehaviour instrument delivery, consent and results." }, { "name": "Assignments", "description": "Assign assessment instruments to individuals and track completion." }, { "name": "Reports", "description": "Generated assessment reports and PDF outputs." }, { "name": "Claims", "description": "Claim an assessment result against an individual's profile." }, { "name": "Personality", "description": "Personality instrument delivery and results. Reserved for a later release." }, { "name": "AI Coaching", "description": "The persistent AI coach — conversations, suggestion cards and team-session question generation.\n\nPersistent AI coaching conversations for an individual." }, { "name": "Coaching Cards", "description": "AI-generated suggestion cards that surface coaching prompts." }, { "name": "Team Sessions", "description": "AI-generated question sets that prepare a team connection session." }, { "name": "Recognition", "description": "The engagement layer — peer recognition plus content-ontology-driven prompts, fed by assessment, connection and ThomAI.\n\nPeer recognition and appreciation between colleagues." }, { "name": "Habits", "description": "Habit streaks that reinforce recurring engagement behaviours." }, { "name": "Feedback", "description": "Capture ratings and engagement feedback for content and prompts." }, { "name": "Activity Feed", "description": "The in-app activity feed — carries recognition, habit prompts, action items, share invitations and DSAR notices.\n\nThe in-app activity feed carrying recognition, prompts, action items and notices." }, { "name": "Consent", "description": "Consent lifecycle, data-subject requests, sharing, visibility, audit and legal documents.\n\nThe organization-wide consent register — record and read consent decisions." }, { "name": "Data Subject Requests", "description": "Data-subject access, export and erasure requests." }, { "name": "Sharing", "description": "Share grants and share invitations that control cross-profile visibility." }, { "name": "Profile Visibility", "description": "An individual's profile visibility settings." }, { "name": "Manager Visibility", "description": "What a manager is permitted to see about their reports." }, { "name": "Audit Log", "description": "Query the immutable audit trail of privacy-flagged actions." }, { "name": "Offboarding", "description": "Organization offboarding — retire an individual's access and data." }, { "name": "Legal Documents", "description": "Terms documents and tombstone lookups for legal and compliance records." }, { "name": "Partner Auth", "description": "The partner-facing surface — OAuth client-credentials auth, webhooks and API-triggered assessment delivery. Token issuance ships now; the webhook and delivery surfaces are reserved for a later release.\n\nOAuth 2.0 client-credentials authentication for integration partners. A partner exchanges its credential for a short-lived access token." }, { "name": "Partner Tenants", "description": "Customer tenant provisioning by an integration partner. A partner creates a new customer tenant and receives the identity it then operates against." }, { "name": "Partner Diagnostics", "description": "Safe, bounded integration activity diagnostics visible only to the API client that produced them while its live Grant still permits the originating operation." }, { "name": "Partner Events & Webhooks", "description": "Webhook subscriptions and partner event delivery. Register an endpoint and hold its signing secret today; event delivery itself is reserved for a later release." }, { "name": "Partner access governance", "description": "Approval of a partner's access to a customer tenant. Thomas requests the access; only an eligible owner of that tenant can grant it, by approving the exact reviewed request." }, { "name": "Health", "description": "Operational endpoints — health, feature flags and the platform portal probe.\n\nService health and readiness probes." }, { "name": "Feature Flags", "description": "Read the platform feature flags in effect." } ], "servers": [ { "url": "https://staging-api.thomas.co/v1" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "FeatureFlagResponseDto": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "home.feed.enabled", "home.habit-streak.enabled", "home.appreciation.enabled" ] }, "enabled": { "type": "boolean" } }, "required": [ "key", "enabled" ] }, "ApiErrorResponseDto": { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "HTTP status code of the error", "examples": [ 400 ] }, "message": { "type": "string", "description": "human-readable error message", "examples": [ "Account not found" ] }, "error": { "type": "string", "description": "machine-readable error code", "examples": [ "IDENTITY_ACCOUNT_NOT_FOUND" ] }, "details": { "description": "additional error details for debugging", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "statusCode", "message", "error" ] }, "ResolveIndividualDto": { "type": "object", "properties": { "email": { "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,}$" }, "hrisId": { "type": "string", "minLength": 1 } } }, "ResolveIndividualResponseDto": { "type": "object", "properties": { "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the resolved or created individual", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "created": { "type": "boolean", "description": "whether a new individual was created during resolution", "examples": [ false ] } }, "required": [ "individualId", "created" ] }, "CreateCompanyIndividualDto": { "type": "object", "properties": { "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the individual to link", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ], "description": "role to assign to the individual" }, "relationshipType": { "type": "string", "enum": [ "candidate", "employee", "former_employee" ], "description": "type of relationship to establish" }, "hrisId": { "description": "optional external HRIS identifier", "examples": [ "EMP-12345" ], "type": "string" } }, "required": [ "individualId", "role", "relationshipType" ] }, "CompanyIndividualResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "companyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hrisId": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "relationshipType": { "type": "string", "enum": [ "candidate", "employee", "former_employee" ], "description": "type of relationship between the individual and the company" }, "status": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ] }, "lifecycleStatus": { "type": "string", "enum": [ "active", "archived", "in_anonymisation", "tombstone" ] }, "membershipSuspendedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "sortFirstName": { "type": "string", "nullable": true }, "sortLastName": { "type": "string", "nullable": true }, "claimableIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "confidential": { "type": "boolean" }, "directoryHidden": { "type": "boolean" }, "confidentialAccessGroupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "accessKind": { "type": "string", "enum": [ "colleague", "service", "integrations_admin" ] }, "accredited": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "individualId", "companyId", "tenantId", "hrisId", "role", "relationshipType", "status", "lifecycleStatus", "membershipSuspendedAt", "sortFirstName", "sortLastName", "claimableIndividualId", "confidential", "directoryHidden", "confidentialAccessGroupId", "accessKind", "accredited", "createdAt", "updatedAt" ] }, "UpdateCompanyIndividualDto": { "type": "object", "properties": { "relationshipType": { "description": "updated relationship type", "type": "string", "enum": [ "candidate", "employee", "former_employee" ] }, "hrisId": { "description": "updated HRIS identifier", "examples": [ "EMP-12345" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "ColleagueFilterOptionsDto": { "type": "object", "properties": { "departments": { "type": "array", "items": { "type": "string" } }, "locations": { "type": "array", "items": { "type": "string" } } }, "required": [ "departments", "locations" ] }, "ListCompanyIndividualsResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "relationshipType": { "type": "string", "enum": [ "candidate", "employee", "former_employee" ], "description": "type of relationship between the individual and the company" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "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,}$" }, "status": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "department": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true }, "photoHash": { "type": "string", "nullable": true }, "managerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "managerName": { "type": "string", "nullable": true }, "directReportCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invitationStatus": { "type": "string", "enum": [ "not_invited", "invited", "expired" ], "nullable": true }, "assessmentStatus": { "type": "string", "enum": [ "not_assigned", "assigned", "completed" ], "nullable": true }, "personalityAssessmentStatus": { "type": "string", "enum": [ "not_assigned", "assigned", "completed" ], "nullable": true }, "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "individualId", "firstName", "lastName", "email", "status", "role", "department", "location", "jobTitle", "photoHash", "managerId", "managerName", "directReportCount", "invitationStatus", "connectionPowerType", "createdAt" ] } }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pageSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isManager": { "type": "boolean" }, "unfilteredTotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total", "page", "pageSize", "isManager" ] } }, "required": [ "data", "meta" ] }, "AuditLogResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "actorName": { "type": "string" }, "action": { "type": "string" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "before": { "nullable": true }, "after": { "nullable": true } }, "required": [ "field", "before", "after" ] } }, "effectiveDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "nullable": true } }, "required": [ "id", "timestamp", "actorName", "action", "changes", "effectiveDate" ] } }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pageSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" } }, "required": [ "total", "page", "pageSize", "hasMore" ] } }, "required": [ "data", "meta" ] }, "PartnerEmployeeResponseDto": { "type": "object", "properties": { "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the stable global Individual this reference resolves to" }, "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the tenant-scoped employee relationship row" }, "partnerReference": { "type": "string", "minLength": 1, "maxLength": 255, "description": "the Partner's own opaque stable reference for this person", "examples": [ "worker-uk-004271" ] }, "sourceVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "the Partner's own non-negative version of the asserted record", "examples": [ 0, 42 ] }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ], "description": "the employee's role as Thomas holds it — `viewer` on one this Partner created, and the existing Owner/Admin/Viewer on one it reconciled with. Never caller-supplied." }, "source": { "type": "string", "enum": [ "manual", "csv_import", "hris_sync", "partner_api" ], "description": "the membership's own source — `partner_api` on an employee this Partner created, and the original source on one it reconciled with" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the Tenant this employee belongs to" }, "membershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the membership row this Partner reference is bound to, whatever its source" }, "relationshipType": { "type": "string", "description": "always `employee` on this surface", "enum": [ "employee" ] } }, "required": [ "individualId", "companyIndividualId", "partnerReference", "sourceVersion", "role", "source", "tenantId", "membershipId", "relationshipType" ], "additionalProperties": false }, "ReactivateColleagueOfferDto": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "reactivate" ] }, "archivedProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "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,}$" }, "status": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ] } }, "required": [ "id", "individualId", "firstName", "lastName", "email", "status" ] } }, "required": [ "classification", "archivedProfile" ] }, "ReconciledColleagueResponseDto": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "reconciled" ] }, "companyIndividual": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "companyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hrisId": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "relationshipType": { "type": "string", "enum": [ "candidate", "employee", "former_employee" ], "description": "type of relationship between the individual and the company" }, "status": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ] }, "lifecycleStatus": { "type": "string", "enum": [ "active", "archived", "in_anonymisation", "tombstone" ] }, "membershipSuspendedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "sortFirstName": { "type": "string", "nullable": true }, "sortLastName": { "type": "string", "nullable": true }, "claimableIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "confidential": { "type": "boolean" }, "directoryHidden": { "type": "boolean" }, "confidentialAccessGroupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "accessKind": { "type": "string", "enum": [ "colleague", "service", "integrations_admin" ] }, "accredited": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "individualId", "companyId", "tenantId", "hrisId", "role", "relationshipType", "status", "lifecycleStatus", "membershipSuspendedAt", "sortFirstName", "sortLastName", "claimableIndividualId", "confidential", "directoryHidden", "confidentialAccessGroupId", "accessKind", "accredited", "createdAt", "updatedAt" ] } }, "required": [ "classification", "companyIndividual" ] }, "CreateColleagueDto": { "type": "object", "properties": { "email": { "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,}$" }, "personalEmail": { "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,}$" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "department": { "type": "string" }, "jobTitle": { "type": "string" }, "location": { "type": "string" }, "partnerReference": { "type": "string", "minLength": 1, "maxLength": 255, "description": "the Partner's own opaque stable reference for this person", "examples": [ "worker-uk-004271" ] }, "sourceVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "the Partner's own non-negative version of the asserted record", "examples": [ 0, 42 ] }, "hrisId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "the customer HR system's identifier for this person, scoped to the Tenant", "examples": [ "EMP-0099214" ] } }, "required": [ "email" ], "additionalProperties": false }, "CreatedColleagueResponseDto": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "created" ] }, "companyIndividual": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "companyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hrisId": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "relationshipType": { "type": "string", "enum": [ "candidate", "employee", "former_employee" ], "description": "type of relationship between the individual and the company" }, "status": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ] }, "lifecycleStatus": { "type": "string", "enum": [ "active", "archived", "in_anonymisation", "tombstone" ] }, "membershipSuspendedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "sortFirstName": { "type": "string", "nullable": true }, "sortLastName": { "type": "string", "nullable": true }, "claimableIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "confidential": { "type": "boolean" }, "directoryHidden": { "type": "boolean" }, "confidentialAccessGroupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "accessKind": { "type": "string", "enum": [ "colleague", "service", "integrations_admin" ] }, "accredited": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "individualId", "companyId", "tenantId", "hrisId", "role", "relationshipType", "status", "lifecycleStatus", "membershipSuspendedAt", "sortFirstName", "sortLastName", "claimableIndividualId", "confidential", "directoryHidden", "confidentialAccessGroupId", "accessKind", "accredited", "createdAt", "updatedAt" ] } }, "required": [ "classification", "companyIndividual" ] }, "BulkValidateRequestDto": { "type": "object", "properties": { "rows": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "email": { "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,}$" }, "personalEmail": { "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,}$" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "department": { "type": "string" }, "jobTitle": { "type": "string" }, "location": { "type": "string" } }, "required": [ "email" ] } } }, "required": [ "rows" ] }, "BulkValidateResponseDto": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "email": { "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,}$" }, "classification": { "type": "string", "enum": [ "ready", "reactivate", "rejected" ] }, "reason": { "type": "string" }, "archivedProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "id", "firstName", "lastName" ] } }, "required": [ "index", "email", "classification" ] } }, "summary": { "type": "object", "properties": { "ready": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reactivate": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "ready", "reactivate", "rejected" ] } }, "required": [ "results", "summary" ] }, "BulkCreateRequestDto": { "type": "object", "properties": { "rows": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "email": { "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,}$" }, "personalEmail": { "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,}$" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "department": { "type": "string" }, "jobTitle": { "type": "string" }, "location": { "type": "string" }, "classification": { "type": "string", "enum": [ "ready", "reactivate" ] }, "archivedProfileId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "email", "classification" ] } } }, "required": [ "rows" ] }, "BulkCreateResponseDto": { "type": "object", "properties": { "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reactivated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "details": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "email": { "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,}$" }, "status": { "type": "string", "enum": [ "created", "reactivated", "rejected" ] }, "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reason": { "type": "string" } }, "required": [ "index", "email", "status" ] } } }, "required": [ "created", "reactivated", "rejected", "details" ] }, "ReactivateColleagueDto": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "department": { "type": "string" }, "jobTitle": { "type": "string" }, "location": { "type": "string" } }, "additionalProperties": false }, "ReactivateColleagueResultDto": { "type": "object", "properties": { "companyIndividual": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "companyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hrisId": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "relationshipType": { "type": "string", "enum": [ "candidate", "employee", "former_employee" ], "description": "type of relationship between the individual and the company" }, "status": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ] }, "lifecycleStatus": { "type": "string", "enum": [ "active", "archived", "in_anonymisation", "tombstone" ] }, "membershipSuspendedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "sortFirstName": { "type": "string", "nullable": true }, "sortLastName": { "type": "string", "nullable": true }, "claimableIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "confidential": { "type": "boolean" }, "directoryHidden": { "type": "boolean" }, "confidentialAccessGroupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "accessKind": { "type": "string", "enum": [ "colleague", "service", "integrations_admin" ] }, "accredited": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "individualId", "companyId", "tenantId", "hrisId", "role", "relationshipType", "status", "lifecycleStatus", "membershipSuspendedAt", "sortFirstName", "sortLastName", "claimableIndividualId", "confidential", "directoryHidden", "confidentialAccessGroupId", "accessKind", "accredited", "createdAt", "updatedAt" ], "description": "the reactivated company-individual" }, "membership": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "unique identifier of the membership", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the company-individual relationship", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "department the individual belongs to", "examples": [ "Engineering" ] }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "job title of the individual", "examples": [ "Senior Developer" ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "work location of the individual", "examples": [ "Paris, France" ] }, "effectiveFrom": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "start date of the membership (ISO datetime, midnight UTC), null if unset", "examples": [ "2026-01-15T00:00:00.000Z", null ] }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "end date of the membership (ISO datetime, midnight UTC), null if ongoing", "examples": [ "2026-12-31T00:00:00.000Z", null ] }, "source": { "type": "string", "enum": [ "manual", "csv_import", "hris_sync", "partner_api" ], "description": "how this membership was created" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] } }, "required": [ "id", "companyIndividualId", "tenantId", "department", "jobTitle", "location", "effectiveFrom", "effectiveTo", "source", "createdAt", "updatedAt" ], "description": "the newly-created membership row" } }, "required": [ "companyIndividual", "membership" ] }, "BulkInviteDto": { "type": "object", "properties": { "companyIndividualIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "companyIndividualIds" ] }, "BulkInviteResponseDto": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "succeeded": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total", "succeeded", "failed", "skipped" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "queued", "skipped" ] }, "error": { "type": "string" } }, "required": [ "index", "id", "status" ] } } }, "required": [ "summary", "results" ] }, "InviteColleagueResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "status" ] }, "EditColleagueDto": { "type": "object", "properties": { "department": { "type": "string" }, "jobTitle": { "type": "string" }, "location": { "type": "string" }, "managerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "effectiveFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } }, "CompanyIndividualDetailResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "relationshipType": { "type": "string", "enum": [ "candidate", "employee", "former_employee" ], "description": "type of relationship between the individual and the company" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "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,}$" }, "status": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "department": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true }, "photoHash": { "type": "string", "nullable": true }, "managerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "managerName": { "type": "string", "nullable": true }, "directReportCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invitationStatus": { "type": "string", "enum": [ "not_invited", "invited", "expired" ], "nullable": true }, "assessmentStatus": { "type": "string", "enum": [ "not_assigned", "assigned", "completed" ], "nullable": true }, "personalityAssessmentStatus": { "type": "string", "enum": [ "not_assigned", "assigned", "completed" ], "nullable": true }, "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "aggregateStatus": { "type": "string", "enum": [ "not_started", "invited", "in_progress", "completed" ], "description": "Candidate Aggregate status (FR-2): a single rolled-up status derived across in-scope per-assessment statuses. This same value set is also the per-assessment status vocabulary.", "nullable": true }, "connectionPowerRevealed": { "type": "boolean" }, "assessmentStatuses": { "type": "array", "items": { "type": "object", "properties": { "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] }, "status": { "type": "string", "enum": [ "not_started", "invited", "in_progress", "completed" ], "description": "Candidate Aggregate status (FR-2): a single rolled-up status derived across in-scope per-assessment statuses. This same value set is also the per-assessment status vocabulary." }, "hasResult": { "type": "boolean" } }, "required": [ "assessmentType", "status", "hasResult" ] } }, "confidential": { "type": "boolean" }, "confidentialCircle": { "type": "object", "properties": { "memberCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "viewerInCircle": { "type": "boolean" } }, "required": [ "memberCount", "viewerInCircle" ], "nullable": true }, "directoryHidden": { "type": "boolean" }, "hrisId": { "type": "string", "nullable": true }, "personalEmail": { "type": "string", "nullable": true }, "isManager": { "default": false, "type": "boolean" }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "department": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true }, "effectiveFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "nullable": true }, "effectiveTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "nullable": true }, "source": { "type": "string", "enum": [ "manual", "csv_import", "hris_sync", "partner_api" ], "description": "source of the membership record" } }, "required": [ "id", "department", "location", "jobTitle", "effectiveFrom", "effectiveTo", "source" ] } }, "managerLinks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "managerIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reportIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "effectiveFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "nullable": true }, "effectiveTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "nullable": true } }, "required": [ "id", "managerIndividualId", "reportIndividualId", "effectiveFrom", "effectiveTo" ] } }, "pendingChange": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "department": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true }, "effectiveFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "nullable": true }, "effectiveTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "nullable": true }, "source": { "type": "string", "enum": [ "manual", "csv_import", "hris_sync", "partner_api" ], "description": "source of the membership record" } }, "required": [ "id", "department", "location", "jobTitle", "effectiveFrom", "effectiveTo", "source" ], "nullable": true }, "photoUrl": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "auditSummary": { "type": "object", "properties": { "lastAction": { "type": "string", "nullable": true }, "lastActionAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true } }, "required": [ "lastAction", "lastActionAt" ] }, "connectionScore": { "type": "number", "nullable": true }, "behaviourProfile": { "type": "object", "properties": { "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ] }, "traitSpectrums": { "minItems": 4, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "D", "I", "S", "C" ] }, "name": { "type": "string", "minLength": 1 }, "leftPole": { "type": "string", "minLength": 1 }, "rightPole": { "type": "string", "minLength": 1 }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "band": { "type": "string", "enum": [ "VeryHigh", "High", "Low", "VeryLow" ], "description": "Behaviour band per facet, derived from raw combined score per legacy spec §3.1" } }, "required": [ "dimension", "name", "leftPole", "rightPole", "position", "band" ] } }, "selfImageScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "scoredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "discAdvanced": { "type": "object", "properties": { "workMaskScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "underPressureScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] } }, "required": [ "workMaskScores", "underPressureScores" ], "additionalProperties": false } }, "required": [ "connectionPowerType", "traitSpectrums", "selfImageScores", "scoredAt" ], "additionalProperties": false, "nullable": true }, "canViewBehaviour": { "type": "boolean" }, "canViewBehaviourByRole": { "type": "boolean" }, "canViewBehaviourByRoleUnresolved": { "type": "boolean" }, "personalisedInsights": { "nullable": true }, "transferredReports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "demographics": { "type": "object", "properties": { "yearOfBirth": { "type": "integer", "minimum": 1900, "maximum": 2100, "nullable": true }, "country": { "type": "string", "nullable": true }, "education": { "type": "string", "nullable": true }, "managementLevel": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "workType": { "type": "string", "nullable": true }, "nativeLanguage": { "type": "string", "enum": [ "Abkhazian", "Afar", "Afrikaans", "Akan", "Albanian", "Amharic", "Arabic", "Aragonese", "Armenian", "Assamese", "Avaric", "Avestan", "Aymara", "Azerbaijani", "Bambara", "Bashkir", "Basque", "Belarusian", "Bengali", "Bihari languages", "Bislama", "Bosnian", "Breton", "Bulgarian", "Burmese", "Catalan", "Central Khmer", "Chamorro", "Chechen", "Chichewa", "Chinese", "Church Slavic", "Chuvash", "Cornish", "Corsican", "Cree", "Croatian", "Czech", "Danish", "Divehi", "Dutch", "Dzongkha", "English", "Esperanto", "Estonian", "Ewe", "Faroese", "Fijian", "Finnish", "French", "Fulah", "Gaelic", "Galician", "Ganda", "Georgian", "German", "Greek", "Guarani", "Gujarati", "Haitian", "Hausa", "Hebrew", "Herero", "Hindi", "Hiri Motu", "Hungarian", "Icelandic", "Ido", "Igbo", "Indonesian", "Interlingua", "Interlingue", "Inuktitut", "Inupiaq", "Irish", "Italian", "Japanese", "Javanese", "Kalaallisut", "Kannada", "Kanuri", "Kashmiri", "Kazakh", "Kikuyu", "Kinyarwanda", "Kirghiz", "Komi", "Kongo", "Korean", "Kuanyama", "Kurdish", "Lao", "Latin", "Latvian", "Limburgish", "Lingala", "Lithuanian", "Luba-Katanga", "Luxembourgish", "Macedonian", "Malagasy", "Malay", "Malayalam", "Maltese", "Manx", "Maori", "Marathi", "Marshallese", "Mongolian", "Nauru", "Navajo", "Ndonga", "Nepali", "North Ndebele", "Northern Sami", "Norwegian", "Norwegian Bokmål", "Norwegian Nynorsk", "Occitan", "Ojibwa", "Oriya", "Oromo", "Ossetian", "Pali", "Pashto", "Persian", "Polish", "Portuguese", "Punjabi", "Quechua", "Romanian", "Romansh", "Rundi", "Russian", "Samoan", "Sango", "Sanskrit", "Sardinian", "Serbian", "Shona", "Sichuan Yi", "Sindhi", "Sinhala", "Slovak", "Slovenian", "Somali", "South Ndebele", "Southern Sotho", "Spanish", "Sundanese", "Swahili", "Swati", "Swedish", "Tagalog", "Tahitian", "Tajik", "Tamil", "Tatar", "Telugu", "Thai", "Tibetan", "Tigrinya", "Tonga", "Tsonga", "Tswana", "Turkish", "Turkmen", "Twi", "Uighur", "Ukrainian", "Urdu", "Uzbek", "Venda", "Vietnamese", "Volapük", "Walloon", "Welsh", "Western Frisian", "Wolof", "Xhosa", "Yiddish", "Yoruba", "Zhuang", "Zulu" ], "nullable": true } }, "required": [ "yearOfBirth", "country", "education", "managementLevel", "gender", "industry", "workType", "nativeLanguage" ], "nullable": true }, "demographicsSurvey": { "type": "object", "properties": { "surveyState": { "type": "string", "enum": [ "skipped", "complete" ] }, "consentedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } } }, "aboutMe": { "type": "object", "properties": { "interests": { "type": "array", "items": { "type": "string" }, "description": "free-text interest tags for the membership", "examples": [ [ "hiking", "jazz", "baking" ] ] }, "preferredCommunication": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "how this person prefers to be communicated with", "examples": [ "Slack, async where possible" ] }, "thingsToKnow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "anything else colleagues should know", "examples": [ "Deaf in one ear — face me when speaking, please." ] } }, "required": [ "interests", "preferredCommunication", "thingsToKnow" ], "nullable": true } }, "required": [ "id", "individualId", "firstName", "lastName", "email", "status", "role", "department", "location", "jobTitle", "photoHash", "managerId", "managerName", "directReportCount", "invitationStatus", "connectionPowerType", "createdAt", "hrisId", "personalEmail", "memberships", "managerLinks", "pendingChange", "photoUrl", "updatedAt", "auditSummary", "connectionScore", "behaviourProfile", "personalisedInsights", "demographics", "aboutMe" ] }, "CancelPendingChangeResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] } }, "required": [ "status" ] }, "BulkAssignManagerDto": { "type": "object", "properties": { "companyIndividualIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "managerCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "companyIndividualIds", "managerCompanyIndividualId" ] }, "BulkAssignManagerResponseDto": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "succeeded": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total", "succeeded", "failed", "skipped" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "assigned", "skipped", "error" ] }, "error": { "type": "string" } }, "required": [ "index", "id", "status" ] } } }, "required": [ "summary", "results" ] }, "BulkSetDepartmentDto": { "type": "object", "properties": { "companyIndividualIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "department": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "companyIndividualIds", "department" ] }, "BulkAttributeUpdateResponseDto": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "succeeded": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total", "succeeded", "failed", "skipped" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "updated", "skipped", "error" ] }, "error": { "type": "string" } }, "required": [ "index", "id", "status" ] } } }, "required": [ "summary", "results" ] }, "BulkSetLocationDto": { "type": "object", "properties": { "companyIndividualIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "location": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "companyIndividualIds", "location" ] }, "BulkArchiveDto": { "type": "object", "properties": { "companyIndividualIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "companyIndividualIds" ] }, "BulkArchiveResponseDto": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "succeeded": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total", "succeeded", "failed", "skipped" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "archived", "skipped", "failed" ] }, "error": { "type": "string" } }, "required": [ "index", "id", "status" ] } } }, "required": [ "summary", "results" ] }, "ArchiveColleagueDto": { "type": "object", "properties": { "transferReportsTo": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "CreateMembershipDto": { "type": "object", "properties": { "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the company-individual relationship", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "department": { "description": "department the individual belongs to", "examples": [ "Engineering" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "jobTitle": { "description": "job title of the individual", "examples": [ "Senior Developer" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "description": "work location", "examples": [ "Paris, France" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "effectiveFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "start date of the membership", "examples": [ "2026-01-15" ] }, "source": { "type": "string", "enum": [ "manual", "csv_import", "hris_sync", "partner_api" ], "description": "source of the membership record" } }, "required": [ "companyIndividualId", "effectiveFrom", "source" ] }, "MembershipResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "unique identifier of the membership", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the company-individual relationship", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "department the individual belongs to", "examples": [ "Engineering" ] }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "job title of the individual", "examples": [ "Senior Developer" ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "work location of the individual", "examples": [ "Paris, France" ] }, "effectiveFrom": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "start date of the membership (ISO datetime, midnight UTC), null if unset", "examples": [ "2026-01-15T00:00:00.000Z", null ] }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "end date of the membership (ISO datetime, midnight UTC), null if ongoing", "examples": [ "2026-12-31T00:00:00.000Z", null ] }, "source": { "type": "string", "enum": [ "manual", "csv_import", "hris_sync", "partner_api" ], "description": "how this membership was created" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] } }, "required": [ "id", "companyIndividualId", "tenantId", "department", "jobTitle", "location", "effectiveFrom", "effectiveTo", "source", "createdAt", "updatedAt" ] }, "UpdateMembershipDto": { "type": "object", "properties": { "department": { "description": "updated department", "examples": [ "Engineering" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "jobTitle": { "description": "updated job title", "examples": [ "Lead Developer" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "description": "updated work location", "examples": [ "London, UK" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "effectiveTo": { "description": "end date of the membership", "examples": [ "2026-12-31" ], "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] } } }, "SessionStatusResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "unique identifier of the account", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "unique identifier of the individual", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "company-individual record identifier for the current tenant", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789abc" ] }, "accessKind": { "default": "colleague", "description": "the logical access kind of the human relationship", "type": "string", "enum": [ "colleague", "integrations_admin" ] }, "role": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, { "type": "null" } ], "description": "role of the user in the current tenant; null for an Integrations Admin" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "current tenant identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "hasDirectCredentials": { "type": "boolean", "description": "whether the user can log in with username/password vs SSO-only", "examples": [ true ] }, "status": { "type": "string", "description": "current account status", "examples": [ "active" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "account creation timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "commercial": { "description": "the tenant's resolved commercial state (four stored fields plus the seam-resolved effectiveTier); absent when the request carried no commercial stamp", "type": "object", "properties": { "tier": { "type": "string", "enum": [ "Team", "Professional", "Expert" ] }, "subscriptionStatus": { "type": "string", "enum": [ "future", "trialing", "active", "non_renewing", "frozen", "paused", "cancelled" ] }, "startMode": { "type": "string", "enum": [ "trial", "active" ], "nullable": true }, "entitlements": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "legacy_advanced_vis" ] }, "source": { "type": "string", "enum": [ "legacy_migration", "accredited" ] }, "grantedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "key", "source", "grantedAt" ] } }, "effectiveTier": { "type": "string", "enum": [ "Team", "Professional", "Expert" ] } }, "required": [ "tier", "subscriptionStatus", "startMode", "entitlements", "effectiveTier" ] } }, "required": [ "id", "individualId", "companyIndividualId", "role", "tenantId", "hasDirectCredentials", "status", "createdAt", "updatedAt" ] }, "UserOrganisationResponseDto": { "type": "object", "properties": { "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant identifier of the organisation", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "companyName": { "type": "string", "minLength": 1, "description": "display name of the organisation", "examples": [ "Acme Corp" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ], "description": "user role within this organisation" }, "isCurrent": { "type": "boolean", "description": "whether this is the currently active organisation", "examples": [ true ] }, "relationshipType": { "description": "the user's relationship to this organisation (candidate / employee / former_employee); may be absent when served by an API version that does not yet populate it", "examples": [ "employee" ], "type": "string", "enum": [ "candidate", "employee", "former_employee" ] } }, "required": [ "tenantId", "companyName", "role", "isCurrent" ] }, "ChangeRoleDto": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "viewer" ], "description": "target role to assign to the user" } }, "required": [ "role" ] }, "ChangeRoleResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "unique identifier of the company-individual relationship", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the individual", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant identifier of the company", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "relationshipType": { "type": "string", "enum": [ "candidate", "employee", "former_employee" ], "description": "type of relationship with the company" }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ], "description": "role of the individual within the company" }, "hrisId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "external HRIS identifier for this relationship", "examples": [ "EMP-12345" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "propagation": { "type": "object", "properties": { "effective": { "type": "string", "enum": [ "next-token-mint" ] }, "maxDelaySeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "effective", "maxDelaySeconds" ], "description": "When the role change takes effect (next token mint), populated by the change-role endpoint." } }, "required": [ "id", "individualId", "tenantId", "relationshipType", "role", "hrisId", "createdAt", "updatedAt", "propagation" ] }, "RolesListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "unique identifier of the company-individual" }, "name": { "type": "string", "description": "full name of the colleague" }, "email": { "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,}$", "description": "email address of the colleague" }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ], "description": "current role of the colleague" }, "status": { "type": "string", "enum": [ "pending", "active" ], "description": "invitation/account status of the colleague" } }, "required": [ "companyIndividualId", "name", "email", "role", "status" ] } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "total number of matching records" }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "current page number" }, "pageSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "number of records per page" } }, "required": [ "data", "total", "page", "pageSize" ] }, "RoleDistributionResponseDto": { "type": "object", "properties": { "owner": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "org-wide count of owners" }, "admin": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "org-wide count of admins" }, "viewer": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "org-wide count of viewers" } }, "required": [ "owner", "admin", "viewer" ] }, "TransferOwnershipDto": { "type": "object", "properties": { "targetCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "ID of the company-individual to transfer ownership to" } }, "required": [ "targetCompanyIndividualId" ] }, "TransferOwnershipResponseDto": { "type": "object", "properties": { "previousOwner": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] } }, "required": [ "id", "role" ], "description": "the previous owner, now demoted to admin" }, "newOwner": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] } }, "required": [ "id", "role" ], "description": "the new owner, promoted from their previous role" }, "propagation": { "type": "object", "properties": { "effective": { "type": "string", "enum": [ "next-token-mint" ] }, "maxDelaySeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "effective", "maxDelaySeconds" ], "description": "When the role change takes effect (next token mint), populated by the transfer-ownership endpoint." } }, "required": [ "previousOwner", "newOwner", "propagation" ] }, "OrganisationProfileResponseDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "display name of the organisation (real — projected from companies.name)", "examples": [ "Acme Workforce" ] }, "billingAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "billing address (projected from companies.billing_address; null when unset)", "examples": [ "1 Onboarding Way, London, SW1A 1AA" ] }, "normGroup": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "assessment norm group (projected from companies.norm_group; null when unset)", "examples": [ "European" ] } }, "required": [ "name", "billingAddress", "normGroup" ], "additionalProperties": false }, "OrganisationLogoResponseDto": { "type": "object", "properties": { "hasLogo": { "type": "boolean", "description": "whether the organisation has an uploaded logo" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "public logo URL — null when no logo is set", "examples": [ "https://cdn.example.com/logos/acme.png" ] }, "contentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "logo MIME type — null when no logo is set", "examples": [ "image/png" ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "last logo update timestamp — null when no logo is set", "examples": [ "2026-06-18T10:30:00.000Z" ] } }, "required": [ "hasLogo", "url", "contentType", "updatedAt" ], "additionalProperties": false }, "DirectReportResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "companyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hrisId": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, "relationshipType": { "type": "string", "enum": [ "candidate", "employee", "former_employee" ], "description": "type of relationship between the individual and the company" }, "status": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ] }, "lifecycleStatus": { "type": "string", "enum": [ "active", "archived", "in_anonymisation", "tombstone" ] }, "membershipSuspendedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "sortFirstName": { "type": "string", "nullable": true }, "sortLastName": { "type": "string", "nullable": true }, "claimableIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "confidential": { "type": "boolean" }, "directoryHidden": { "type": "boolean" }, "confidentialAccessGroupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "accessKind": { "type": "string", "enum": [ "colleague", "service", "integrations_admin" ] }, "accredited": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "individualId", "companyId", "tenantId", "hrisId", "role", "relationshipType", "status", "lifecycleStatus", "membershipSuspendedAt", "sortFirstName", "sortLastName", "claimableIndividualId", "confidential", "directoryHidden", "confidentialAccessGroupId", "accessKind", "accredited", "createdAt", "updatedAt" ] }, "CreateManagerLinkDto": { "type": "object", "properties": { "managerIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the manager individual", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "reportIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the direct report individual", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] } }, "required": [ "managerIndividualId", "reportIndividualId" ] }, "ManagerLinkResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "unique identifier of the manager link", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "managerIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the manager individual", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "reportIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the direct report individual", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "effectiveFrom": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "link start date (ISO datetime, midnight UTC), null if unset", "examples": [ "2026-01-15T00:00:00.000Z", null ] }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "link end date (ISO datetime, midnight UTC), null while active", "examples": [ null ] } }, "required": [ "id", "managerIndividualId", "reportIndividualId", "tenantId", "createdAt", "updatedAt", "effectiveFrom", "effectiveTo" ] }, "PhotoUploadResponseDto": { "type": "object", "properties": { "photoHash": { "type": "string" } }, "required": [ "photoHash" ] }, "PhotoDeleteResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "localized confirmation message", "examples": [ "Photo removed" ] } }, "required": [ "message" ] }, "UpdateDemographicsDto": { "type": "object", "properties": { "yearOfBirth": { "type": "integer", "minimum": 1900, "maximum": 2100, "nullable": true }, "country": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "education": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "managementLevel": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "gender": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "industry": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "workType": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "nativeLanguage": { "type": "string", "enum": [ "Abkhazian", "Afar", "Afrikaans", "Akan", "Albanian", "Amharic", "Arabic", "Aragonese", "Armenian", "Assamese", "Avaric", "Avestan", "Aymara", "Azerbaijani", "Bambara", "Bashkir", "Basque", "Belarusian", "Bengali", "Bihari languages", "Bislama", "Bosnian", "Breton", "Bulgarian", "Burmese", "Catalan", "Central Khmer", "Chamorro", "Chechen", "Chichewa", "Chinese", "Church Slavic", "Chuvash", "Cornish", "Corsican", "Cree", "Croatian", "Czech", "Danish", "Divehi", "Dutch", "Dzongkha", "English", "Esperanto", "Estonian", "Ewe", "Faroese", "Fijian", "Finnish", "French", "Fulah", "Gaelic", "Galician", "Ganda", "Georgian", "German", "Greek", "Guarani", "Gujarati", "Haitian", "Hausa", "Hebrew", "Herero", "Hindi", "Hiri Motu", "Hungarian", "Icelandic", "Ido", "Igbo", "Indonesian", "Interlingua", "Interlingue", "Inuktitut", "Inupiaq", "Irish", "Italian", "Japanese", "Javanese", "Kalaallisut", "Kannada", "Kanuri", "Kashmiri", "Kazakh", "Kikuyu", "Kinyarwanda", "Kirghiz", "Komi", "Kongo", "Korean", "Kuanyama", "Kurdish", "Lao", "Latin", "Latvian", "Limburgish", "Lingala", "Lithuanian", "Luba-Katanga", "Luxembourgish", "Macedonian", "Malagasy", "Malay", "Malayalam", "Maltese", "Manx", "Maori", "Marathi", "Marshallese", "Mongolian", "Nauru", "Navajo", "Ndonga", "Nepali", "North Ndebele", "Northern Sami", "Norwegian", "Norwegian Bokmål", "Norwegian Nynorsk", "Occitan", "Ojibwa", "Oriya", "Oromo", "Ossetian", "Pali", "Pashto", "Persian", "Polish", "Portuguese", "Punjabi", "Quechua", "Romanian", "Romansh", "Rundi", "Russian", "Samoan", "Sango", "Sanskrit", "Sardinian", "Serbian", "Shona", "Sichuan Yi", "Sindhi", "Sinhala", "Slovak", "Slovenian", "Somali", "South Ndebele", "Southern Sotho", "Spanish", "Sundanese", "Swahili", "Swati", "Swedish", "Tagalog", "Tahitian", "Tajik", "Tamil", "Tatar", "Telugu", "Thai", "Tibetan", "Tigrinya", "Tonga", "Tsonga", "Tswana", "Turkish", "Turkmen", "Twi", "Uighur", "Ukrainian", "Urdu", "Uzbek", "Venda", "Vietnamese", "Volapük", "Walloon", "Welsh", "Western Frisian", "Wolof", "Xhosa", "Yiddish", "Yoruba", "Zhuang", "Zulu" ], "nullable": true } } }, "UpdateDemographicsSurveyDto": { "type": "object", "properties": { "surveyState": { "type": "string", "enum": [ "skipped", "complete" ] }, "consented": { "type": "boolean", "enum": [ true ] }, "demographics": { "type": "object", "properties": { "yearOfBirth": { "type": "integer", "minimum": 1900, "maximum": 2100, "nullable": true }, "country": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "education": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "managementLevel": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "gender": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "industry": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "workType": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "nativeLanguage": { "type": "string", "enum": [ "Abkhazian", "Afar", "Afrikaans", "Akan", "Albanian", "Amharic", "Arabic", "Aragonese", "Armenian", "Assamese", "Avaric", "Avestan", "Aymara", "Azerbaijani", "Bambara", "Bashkir", "Basque", "Belarusian", "Bengali", "Bihari languages", "Bislama", "Bosnian", "Breton", "Bulgarian", "Burmese", "Catalan", "Central Khmer", "Chamorro", "Chechen", "Chichewa", "Chinese", "Church Slavic", "Chuvash", "Cornish", "Corsican", "Cree", "Croatian", "Czech", "Danish", "Divehi", "Dutch", "Dzongkha", "English", "Esperanto", "Estonian", "Ewe", "Faroese", "Fijian", "Finnish", "French", "Fulah", "Gaelic", "Galician", "Ganda", "Georgian", "German", "Greek", "Guarani", "Gujarati", "Haitian", "Hausa", "Hebrew", "Herero", "Hindi", "Hiri Motu", "Hungarian", "Icelandic", "Ido", "Igbo", "Indonesian", "Interlingua", "Interlingue", "Inuktitut", "Inupiaq", "Irish", "Italian", "Japanese", "Javanese", "Kalaallisut", "Kannada", "Kanuri", "Kashmiri", "Kazakh", "Kikuyu", "Kinyarwanda", "Kirghiz", "Komi", "Kongo", "Korean", "Kuanyama", "Kurdish", "Lao", "Latin", "Latvian", "Limburgish", "Lingala", "Lithuanian", "Luba-Katanga", "Luxembourgish", "Macedonian", "Malagasy", "Malay", "Malayalam", "Maltese", "Manx", "Maori", "Marathi", "Marshallese", "Mongolian", "Nauru", "Navajo", "Ndonga", "Nepali", "North Ndebele", "Northern Sami", "Norwegian", "Norwegian Bokmål", "Norwegian Nynorsk", "Occitan", "Ojibwa", "Oriya", "Oromo", "Ossetian", "Pali", "Pashto", "Persian", "Polish", "Portuguese", "Punjabi", "Quechua", "Romanian", "Romansh", "Rundi", "Russian", "Samoan", "Sango", "Sanskrit", "Sardinian", "Serbian", "Shona", "Sichuan Yi", "Sindhi", "Sinhala", "Slovak", "Slovenian", "Somali", "South Ndebele", "Southern Sotho", "Spanish", "Sundanese", "Swahili", "Swati", "Swedish", "Tagalog", "Tahitian", "Tajik", "Tamil", "Tatar", "Telugu", "Thai", "Tibetan", "Tigrinya", "Tonga", "Tsonga", "Tswana", "Turkish", "Turkmen", "Twi", "Uighur", "Ukrainian", "Urdu", "Uzbek", "Venda", "Vietnamese", "Volapük", "Walloon", "Welsh", "Western Frisian", "Wolof", "Xhosa", "Yiddish", "Yoruba", "Zhuang", "Zulu" ], "nullable": true } } } }, "required": [ "surveyState" ] }, "UpdateMyDetailsDto": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 255 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "InitiateEmailVerificationDto": { "type": "object", "properties": { "email": { "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,}$" } }, "required": [ "email" ] }, "InitiateEmailVerificationResponseDto": { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "expiresAt" ] }, "VerifyEmailDto": { "type": "object", "properties": { "token": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-f]+$" } }, "required": [ "token" ] }, "ListAuditEventsResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "category": { "type": "string", "enum": [ "Profile", "Consent", "Sharing", "Compliance", "Assessment" ], "nullable": true }, "action": { "type": "string", "minLength": 1 }, "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "actorType": { "type": "string", "minLength": 1, "nullable": true }, "actorDisplayName": { "type": "string", "nullable": true }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "subjectCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "subjectDisplayName": { "type": "string", "nullable": true }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "nullable": true } }, "required": [ "id", "category", "action", "actorId", "actorType", "actorDisplayName", "tenantId", "subjectCompanyIndividualId", "subjectDisplayName", "occurredAt", "createdAt", "metadata" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "nextCursor": { "type": "string", "minLength": 1, "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "nextCursor", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "SubmitDsrRequestDto": { "type": "object", "properties": { "targetCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestType": { "type": "string", "enum": [ "erasure" ] } }, "required": [ "targetCompanyIndividualId", "requestType" ], "additionalProperties": false }, "DsrRequestResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "subjectCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "submitted", "under_review", "approved", "rejected", "in_retention_hold", "completed" ] }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "decidedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "inRetentionHoldUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "dpoRationale": { "type": "string", "nullable": true }, "history": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "submitted", "under_review", "approved", "rejected", "in_retention_hold", "completed" ] }, "actorCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "dpoRationale": { "type": "string", "nullable": true } }, "required": [ "status", "actorCompanyIndividualId", "occurredAt", "dpoRationale" ], "additionalProperties": false } } }, "required": [ "id", "tenantId", "subjectCompanyIndividualId", "status", "submittedAt", "decidedAt", "inRetentionHoldUntil", "completedAt", "createdAt", "updatedAt", "dpoRationale", "history" ], "additionalProperties": false }, "TermsDocumentEnvelopeResponseDto": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "string", "minLength": 1, "maxLength": 64 }, "documentType": { "type": "string", "enum": [ "terms", "privacy" ] }, "content": { "type": "string", "maxLength": 1000000 }, "contentUrl": { "type": "string", "maxLength": 2048, "pattern": "^https?:\\/\\/", "nullable": true }, "effectiveFrom": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "effectiveTo": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "version", "documentType", "content", "contentUrl", "effectiveFrom", "effectiveTo", "createdAt" ], "additionalProperties": false }, "meta": { "type": "object", "properties": {}, "additionalProperties": false, "description": "reserved metadata envelope (currently empty)" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "ConsentRecordsListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "consentedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "source": { "type": "string", "enum": [ "registration", "invitation", "reacceptance" ] }, "document": { "type": "object", "properties": { "version": { "type": "string" }, "documentType": { "type": "string", "enum": [ "terms", "privacy" ] }, "effectiveFrom": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "effectiveTo": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true } }, "required": [ "version", "documentType", "effectiveFrom", "effectiveTo" ], "additionalProperties": false } }, "required": [ "id", "consentedAt", "source", "document" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "count" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "ShareGrantResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sharer_company_individual_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recipient_company_individual_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "data_type": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] }, "source": { "type": "string", "enum": [ "voluntary", "org_configured" ] }, "recipient_role": { "type": "string", "enum": [ "peer", "manager" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "revoked_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true } }, "required": [ "id", "tenant_id", "sharer_company_individual_id", "recipient_company_individual_id", "data_type", "source", "recipient_role", "created_at", "revoked_at" ], "additionalProperties": false }, "CreateShareGrantBodyDto": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "single" ] }, "recipientCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "dataType": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] } }, "required": [ "mode", "recipientCompanyIndividualId", "dataType" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "team-bulk" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "dataType": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] } }, "required": [ "mode", "teamId", "dataType" ], "additionalProperties": false } ] }, "ManageSharingDataTypeViewDto": { "type": "object", "properties": { "dataType": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] }, "profileVisibility": { "type": "string", "enum": [ "public", "private" ] }, "outboundGrants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "counterpartyCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "counterpartyDisplayName": { "type": "string", "minLength": 1, "maxLength": 256 }, "dataType": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] }, "recipientRole": { "type": "string", "enum": [ "peer", "manager" ] }, "source": { "type": "string", "enum": [ "voluntary", "org_configured" ] }, "grantedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "counterpartyCompanyIndividualId", "counterpartyDisplayName", "dataType", "recipientRole", "source", "grantedAt" ], "additionalProperties": false } }, "inboundGrants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "counterpartyCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "counterpartyDisplayName": { "type": "string", "minLength": 1, "maxLength": 256 }, "dataType": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] }, "recipientRole": { "type": "string", "enum": [ "peer", "manager" ] }, "source": { "type": "string", "enum": [ "voluntary", "org_configured" ] }, "grantedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "counterpartyCompanyIndividualId", "counterpartyDisplayName", "dataType", "recipientRole", "source", "grantedAt" ], "additionalProperties": false } }, "managerSection": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "dataType": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] }, "category": { "type": "string", "enum": [ "insight", "connection_result", "fixed" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 256 }, "source": { "type": "string", "enum": [ "voluntary", "org_configured" ] }, "grantedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "dataType", "category", "label", "source", "grantedAt" ], "additionalProperties": false } }, "managerDisplayName": { "type": "string", "minLength": 1, "maxLength": 256, "nullable": true } }, "required": [ "items", "managerDisplayName" ], "additionalProperties": false } }, "required": [ "dataType", "profileVisibility", "outboundGrants", "inboundGrants", "managerSection" ], "additionalProperties": false }, "TeamShareCoverageDto": { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "dataType": { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, "hasUncoveredRecipients": { "type": "boolean" }, "uncoveredRecipientCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "enum": [ "uncovered_recipients", "all_recipients_covered", "no_eligible_recipients" ] } }, "required": [ "teamId", "dataType", "hasUncoveredRecipients", "uncoveredRecipientCount", "reason" ], "additionalProperties": false }, "ListShareGrantsResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sharer_company_individual_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recipient_company_individual_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "data_type": { "anyOf": [ { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, { "type": "string", "pattern": "^insight:.+$" }, { "type": "string", "pattern": "^connection_result:.+$" } ] }, "source": { "type": "string", "enum": [ "voluntary", "org_configured" ] }, "recipient_role": { "type": "string", "enum": [ "peer", "manager" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "revoked_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true } }, "required": [ "id", "tenant_id", "sharer_company_individual_id", "recipient_company_individual_id", "data_type", "source", "recipient_role", "created_at", "revoked_at" ], "additionalProperties": false } }, "nextCursor": { "type": "string", "minLength": 1, "nullable": true } }, "required": [ "data", "nextCursor" ], "additionalProperties": false }, "ShareInvitationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sender_company_individual_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recipient_company_individual_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "data_type": { "type": "string", "enum": [ "behaviour_overview", "connection_personal_results", "profile_visibility" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "accepted_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "dismissed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true } }, "required": [ "id", "tenant_id", "sender_company_individual_id", "recipient_company_individual_id", "data_type", "status", "created_at", "accepted_at", "dismissed_at" ], "additionalProperties": false }, "OrgSharingViewResponseDto": { "type": "object", "properties": { "organisations": { "type": "array", "items": { "type": "object", "properties": { "organisationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organisationName": { "type": "string", "minLength": 1 }, "sharedSince": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "status": { "type": "string", "enum": [ "active", "removal_requested" ] }, "assessments": { "type": "object", "properties": { "behaviour": { "type": "boolean" }, "aptitude": { "type": "boolean" }, "personality": { "type": "boolean" }, "emotional_intelligence": { "type": "boolean" } }, "required": [ "behaviour", "aptitude", "personality", "emotional_intelligence" ] } }, "required": [ "organisationId", "organisationName", "sharedSince", "status", "assessments" ] } } }, "required": [ "organisations" ] }, "RequestOrgSharingRemovalResponseDto": { "type": "object", "properties": { "organisation": { "type": "object", "properties": { "organisationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organisationName": { "type": "string", "minLength": 1 }, "sharedSince": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "status": { "type": "string", "enum": [ "active", "removal_requested" ] }, "assessments": { "type": "object", "properties": { "behaviour": { "type": "boolean" }, "aptitude": { "type": "boolean" }, "personality": { "type": "boolean" }, "emotional_intelligence": { "type": "boolean" } }, "required": [ "behaviour", "aptitude", "personality", "emotional_intelligence" ] } }, "required": [ "organisationId", "organisationName", "sharedSince", "status", "assessments" ] } }, "required": [ "organisation" ] }, "PendingReuseRequestsResponseDto": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "assessmentType": { "type": "string", "enum": [ "behaviour", "aptitude", "personality", "emotional_intelligence" ] }, "completedOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "freshness": { "type": "string", "enum": [ "current", "over_a_year" ] }, "requests": { "type": "array", "items": { "type": "object", "properties": { "organisationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organisationName": { "type": "string", "minLength": 1 }, "invitedOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "canTakeAgain": { "type": "boolean" } }, "required": [ "organisationId", "organisationName", "invitedOn", "assignmentId", "canTakeAgain" ] } } }, "required": [ "assessmentType", "completedOn", "freshness", "requests" ] } }, "pendingCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "groups", "pendingCount" ] }, "ShareExistingResultResponseDto": { "type": "object", "properties": { "organisation": { "type": "object", "properties": { "organisationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organisationName": { "type": "string", "minLength": 1 }, "sharedSince": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "status": { "type": "string", "enum": [ "active", "removal_requested" ] }, "assessments": { "type": "object", "properties": { "behaviour": { "type": "boolean" }, "aptitude": { "type": "boolean" }, "personality": { "type": "boolean" }, "emotional_intelligence": { "type": "boolean" } }, "required": [ "behaviour", "aptitude", "personality", "emotional_intelligence" ] } }, "required": [ "organisationId", "organisationName", "sharedSince", "status", "assessments" ] } }, "required": [ "organisation" ] }, "UpdateProfileVisibilityBodyDto": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "public", "private" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "ProfileVisibilityResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "owner_company_individual_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "tenant_id", "owner_company_individual_id", "visibility", "created_at", "updated_at" ], "additionalProperties": false }, "OrgOffboardingRequestDto": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "OrgOffboardingResponseDto": { "type": "object", "properties": { "timerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "firesAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "timerId", "firesAt" ], "additionalProperties": false }, "TombstoneLookupResponseDto": { "type": "object", "properties": { "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lifecycleStatus": { "type": "string", "enum": [ "tombstone" ] }, "name": { "type": "string" } }, "required": [ "companyIndividualId", "individualId", "lifecycleStatus", "name" ], "additionalProperties": false }, "OrgInsightVisibilityRowDto": { "type": "object", "properties": { "insightId": { "type": "string", "minLength": 1, "maxLength": 128 }, "autoVisible": { "type": "boolean" }, "eligible": { "type": "boolean" }, "neverAutoVisible": { "type": "boolean" }, "heading": { "type": "string" }, "description": { "type": "string" } }, "required": [ "insightId", "autoVisible", "eligible", "neverAutoVisible", "heading", "description" ], "additionalProperties": false }, "UpdateOrgInsightVisibilityBodyDto": { "type": "object", "properties": { "insightId": { "type": "string", "minLength": 1, "maxLength": 128 }, "autoVisibleToManagers": { "type": "boolean" } }, "required": [ "insightId", "autoVisibleToManagers" ], "additionalProperties": false }, "AutoVisibleInsightsResponseDto": { "type": "object", "properties": { "insightIds": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "insightIds" ], "additionalProperties": false }, "AboutMeResponseDto": { "type": "object", "properties": { "interests": { "type": "array", "items": { "type": "string" }, "description": "free-text interest tags for the membership", "examples": [ [ "hiking", "jazz", "baking" ] ] }, "preferredCommunication": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "how this person prefers to be communicated with", "examples": [ "Slack, async where possible" ] }, "thingsToKnow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "anything else colleagues should know", "examples": [ "Deaf in one ear — face me when speaking, please." ] } }, "required": [ "interests", "preferredCommunication", "thingsToKnow" ] }, "PartnerAccessRequestReviewDto": { "type": "object", "properties": { "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "partnerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the Partner owning the API Client" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the Customer Tenant whose Owner is reviewing the request" }, "apiClientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "authorityKind": { "type": "string", "enum": [ "partner-approved" ] }, "status": { "type": "string", "enum": [ "pending" ] }, "requestVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "the immutable reviewed version — monotonic from 1" }, "scopeFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 over the canonical Scope bytes" }, "scope": { "type": "object", "properties": { "partnerRole": { "type": "string", "enum": [ "consumer", "source-of-record" ], "description": "the Partner's role over the approved data domains" }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "read", "write" ] }, "description": "never empty" }, "domains": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "results", "teams", "users" ] }, "description": "never empty" } }, "required": [ "partnerRole", "actions", "domains" ], "additionalProperties": false, "description": "the complete canonical reviewed authority" }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC instant the request was frozen" } }, "required": [ "grantId", "partnerId", "tenantId", "apiClientId", "authorityKind", "status", "requestVersion", "scopeFingerprint", "scope", "requestedAt" ], "additionalProperties": false }, "PartnerAccessApprovalDto": { "type": "object", "properties": { "requestVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "the immutable reviewed version — monotonic from 1" }, "scopeFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 over the canonical Scope bytes" } }, "required": [ "requestVersion", "scopeFingerprint" ], "additionalProperties": false }, "PartnerAccessApprovalResultDto": { "type": "object", "properties": { "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "the immutable reviewed version — monotonic from 1" }, "scopeFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 over the canonical Scope bytes" }, "serviceMembershipId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the retained, now-active Service Membership" }, "approvedByIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the eligible Owner who approved" }, "status": { "type": "string", "enum": [ "active" ] } }, "required": [ "grantId", "requestVersion", "scopeFingerprint", "serviceMembershipId", "approvedByIndividualId", "status" ], "additionalProperties": false }, "PartnerAccessRejectionDto": { "type": "object", "properties": { "requestVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "the immutable reviewed version — monotonic from 1" }, "scopeFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 over the canonical Scope bytes" } }, "required": [ "requestVersion", "scopeFingerprint" ], "additionalProperties": false }, "PartnerAccessRejectionResultDto": { "type": "object", "properties": { "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "the immutable reviewed version — monotonic from 1" }, "scopeFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 over the canonical Scope bytes" }, "status": { "type": "string", "enum": [ "rejected" ] }, "rejectedByIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the eligible Owner who refused" }, "rejectedByCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the refusing Owner's membership in the Tenant, as re-read at commit time" }, "rejectedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC instant the refusal was committed" } }, "required": [ "grantId", "requestVersion", "scopeFingerprint", "status", "rejectedByIndividualId", "rejectedByCompanyIndividualId", "rejectedAt" ], "additionalProperties": false }, "PartnerTenantRequestAccessOutcomeDto": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "request_access" ] } }, "required": [ "outcome" ], "additionalProperties": false }, "PartnerTenantAdminResolutionRequiredOutcomeDto": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "admin_resolution_required" ] } }, "required": [ "outcome" ], "additionalProperties": false }, "PartnerTenantCreateRequestDto": { "type": "object", "properties": { "customerName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "the display name for the new Customer Tenant" }, "customerOwnerEmail": { "type": "string", "maxLength": 320, "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$", "format": "email", "description": "the Customer Owner's full email address" }, "customerDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "the Customer's separately asserted domain" } }, "required": [ "customerName", "customerOwnerEmail" ], "additionalProperties": false }, "PartnerTenantCreatedOutcomeDto": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "created" ] }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the immutable Customer/Tenant identity" } }, "required": [ "outcome", "tenantId" ], "additionalProperties": false }, "IntegrationDiagnosticListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the diagnostic — one canonical integration activity row" }, "apiClientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the API Client whose permitted history this belongs to" }, "credentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the EXACT Credential that produced this row, preserved across rotation" }, "tenantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "the Tenant the operation addressed, or null for an above-Tenant operation" }, "operation": { "type": "string", "maxLength": 120, "pattern": "^[a-z][A-Za-z0-9]*$", "description": "the stable published operationId of the originating operation" }, "accessExpression": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*:[rw]$", "description": "a coarse Grant Scope token, `domain:action`" }, "description": "every Grant Scope the originating operation required" }, "outcome": { "type": "string", "enum": [ "failed", "succeeded" ], "description": "whether the recorded integration operation succeeded or failed" }, "safeReason": { "anyOf": [ { "type": "string", "enum": [ "DOWNSTREAM_DEPENDENCY_UNAVAILABLE", "INTERNAL_ERROR", "REQUEST_REJECTED_BY_BUSINESS_RULE", "STATUS_TRANSITION_NOT_ALLOWED" ], "description": "a bounded, safe reason code for a failed integration operation" }, { "type": "null" } ], "description": "the bounded safe reason, set only when the outcome is `failed`" }, "recordKind": { "type": "string", "enum": [ "assessment_assignment" ], "description": "the kind of record the integration operation acted on" }, "recordRef": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "description": "the opaque Thomas UUID or safe Partner-supplied reference of the record" }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "when the recorded operation ran" }, "currentIntegrationStatus": { "type": "string", "enum": [ "failed", "succeeded" ], "description": "the newest outcome on this record's lineage for this API Client" }, "lastRunAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "when this record's lineage last ran for this API Client" } }, "required": [ "id", "apiClientId", "credentialId", "tenantId", "operation", "accessExpression", "outcome", "safeReason", "recordKind", "recordRef", "occurredAt", "currentIntegrationStatus", "lastRunAt" ], "additionalProperties": false, "description": "one safe, bounded diagnostic for a Partner integration operation" }, "description": "the page, newest first" }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "opaque cursor for the next page, or null on the last page" }, "pageSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "the explicit bound this page was read under" } }, "required": [ "items", "nextCursor", "pageSize" ], "additionalProperties": false }, "IntegrationDiagnosticReadResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the diagnostic — one canonical integration activity row" }, "apiClientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the API Client whose permitted history this belongs to" }, "credentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the EXACT Credential that produced this row, preserved across rotation" }, "tenantId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "the Tenant the operation addressed, or null for an above-Tenant operation" }, "operation": { "type": "string", "maxLength": 120, "pattern": "^[a-z][A-Za-z0-9]*$", "description": "the stable published operationId of the originating operation" }, "accessExpression": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*:[rw]$", "description": "a coarse Grant Scope token, `domain:action`" }, "description": "every Grant Scope the originating operation required" }, "outcome": { "type": "string", "enum": [ "failed", "succeeded" ], "description": "whether the recorded integration operation succeeded or failed" }, "safeReason": { "anyOf": [ { "type": "string", "enum": [ "DOWNSTREAM_DEPENDENCY_UNAVAILABLE", "INTERNAL_ERROR", "REQUEST_REJECTED_BY_BUSINESS_RULE", "STATUS_TRANSITION_NOT_ALLOWED" ], "description": "a bounded, safe reason code for a failed integration operation" }, { "type": "null" } ], "description": "the bounded safe reason, set only when the outcome is `failed`" }, "recordKind": { "type": "string", "enum": [ "assessment_assignment" ], "description": "the kind of record the integration operation acted on" }, "recordRef": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "description": "the opaque Thomas UUID or safe Partner-supplied reference of the record" }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "when the recorded operation ran" }, "currentIntegrationStatus": { "type": "string", "enum": [ "failed", "succeeded" ], "description": "the newest outcome on this record's lineage for this API Client" }, "lastRunAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "when this record's lineage last ran for this API Client" } }, "required": [ "id", "apiClientId", "credentialId", "tenantId", "operation", "accessExpression", "outcome", "safeReason", "recordKind", "recordRef", "occurredAt", "currentIntegrationStatus", "lastRunAt" ], "additionalProperties": false }, "WebhookSubscriptionCreateRequestDto": { "type": "object", "properties": { "endpointUrl": { "type": "string", "format": "uri", "description": "a public HTTPS webhook destination on the default port, without credentials or a fragment" } }, "required": [ "endpointUrl" ], "additionalProperties": false }, "WebhookSubscriptionCreateResponseDto": { "type": "object", "properties": { "subscriptionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "endpointUrl": { "type": "string", "format": "uri", "description": "a public HTTPS webhook destination on the default port, without credentials or a fragment" }, "signingSecret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "a 256-bit base64url signing secret returned only on creation or rotation" }, "signingSecretVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "activatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "subscriptionId", "endpointUrl", "signingSecret", "signingSecretVersion", "activatedAt", "createdAt" ], "additionalProperties": false }, "WebhookSubscriptionReadResponseDto": { "type": "object", "properties": { "subscriptionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "endpointUrl": { "type": "string", "format": "uri", "description": "a public HTTPS webhook destination on the default port, without credentials or a fragment" }, "signingSecretVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "subscriptionId", "endpointUrl", "signingSecretVersion", "createdAt", "updatedAt" ], "additionalProperties": false }, "WebhookSubscriptionUpdateRequestDto": { "type": "object", "properties": { "endpointUrl": { "type": "string", "format": "uri", "description": "a public HTTPS webhook destination on the default port, without credentials or a fragment" } }, "required": [ "endpointUrl" ], "additionalProperties": false }, "WebhookSigningSecretRotateRequestDto": { "type": "object", "properties": { "reason": { "default": "routine", "type": "string", "enum": [ "routine", "compromise" ], "description": "routine keeps the previous secret verifying for 24h; compromise retires it now" } }, "additionalProperties": false }, "WebhookSigningSecretRotateResponseDto": { "type": "object", "properties": { "subscriptionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "signingSecret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "a 256-bit base64url signing secret returned only on creation or rotation" }, "signingSecretVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "activatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "subscriptionId", "signingSecret", "signingSecretVersion", "activatedAt" ], "additionalProperties": false }, "CreateConversationBodyDto": { "type": "object", "properties": { "contextTag": { "type": "string", "enum": [ "personal", "manager", "org_analyst" ] }, "entryPoint": { "type": "string", "enum": [ "thomai_card", "persistent_button", "thomai_fab", "prompt_card", "input_bar", "unprompted" ] }, "pageId": { "type": "string", "enum": [ "individual", "team", "org_analyst", "manager", "home", "unprompted", "connection_template1_results" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "contextTag", "entryPoint" ], "additionalProperties": false }, "ConversationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "contextTag": { "type": "string", "enum": [ "personal", "manager", "org_analyst" ] }, "entryPoint": { "type": "string", "minLength": 1 }, "pageId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "lastMessageAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "contextTag", "entryPoint", "pageId", "title", "lastMessageAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "ConversationsListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "contextTag": { "type": "string", "enum": [ "personal", "manager", "org_analyst" ] }, "entryPoint": { "type": "string", "minLength": 1 }, "pageId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "lastMessageAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "contextTag", "entryPoint", "pageId", "title", "createdAt", "lastMessageAt" ], "additionalProperties": false } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "items", "nextCursor" ], "additionalProperties": false }, "ConversationDetailResponseDto": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "contextTag": { "type": "string", "enum": [ "personal", "manager", "org_analyst" ] }, "entryPoint": { "type": "string", "minLength": 1 }, "pageId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "lastMessageAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "contextTag", "entryPoint", "pageId", "title", "lastMessageAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "metadata": { "nullable": true }, "actions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "actionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "enum": [ "PUSH_TO_HOME_FEED" ] }, "executedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "actionId", "kind", "executedAt" ], "additionalProperties": false } } }, "required": [ "id", "role", "content", "seq", "createdAt", "metadata" ], "additionalProperties": false } }, "nextMessagesCursor": { "type": "string", "nullable": true } }, "required": [ "conversation", "messages", "nextMessagesCursor" ], "additionalProperties": false }, "UpdateConversationBodyDto": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "title" ], "additionalProperties": false }, "SendMessageBodyDto": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 1 }, "clientMessageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pageId": { "type": "string", "enum": [ "individual", "team", "org_analyst", "manager", "home", "unprompted", "connection_template1_results" ] }, "pageParams": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "entryPoint": { "type": "string", "enum": [ "thomai_card", "persistent_button", "thomai_fab", "prompt_card", "input_bar", "unprompted" ] }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "self" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "individual_id" ] }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "individualId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "team_id" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "teamId" ], "additionalProperties": false } ] }, "recentEvents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "type", "id", "occurredAt" ], "additionalProperties": false } }, "priorAction": { "type": "object", "properties": { "kind": { "type": "string", "minLength": 1 }, "entityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind" ], "additionalProperties": false } }, "required": [ "intent", "clientMessageId", "pageId", "pageParams", "entryPoint" ], "additionalProperties": false }, "PushMessageActionBodyDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PUSH_TO_HOME_FEED" ] }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "kind", "payload" ], "additionalProperties": false }, "AiCoachingMessageActionResponseDto": { "type": "object", "properties": { "actionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "enum": [ "PUSH_TO_HOME_FEED" ] }, "executedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "alreadyAdded": { "type": "boolean" } }, "required": [ "actionId", "kind", "executedAt", "alreadyAdded" ], "additionalProperties": false }, "CxiCardsResponseDto": { "type": "object", "properties": { "cards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "minLength": 1 }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "kind", "data" ] } } }, "required": [ "cards" ] }, "CreateTeamSessionsQuestionsBodyDto": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 1 }, "sessionDirective": { "type": "string", "minLength": 1 } }, "required": [ "intent", "sessionDirective" ], "additionalProperties": false }, "SubmitAssessmentRequestDto": { "type": "object", "properties": { "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] }, "responses": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "questionIndex": { "type": "integer", "minimum": 0, "maximum": 23 }, "most": { "type": "string", "enum": [ "D", "I", "S", "C" ] }, "least": { "type": "string", "enum": [ "D", "I", "S", "C" ] } }, "required": [ "questionIndex", "most", "least" ] }, { "type": "object", "properties": { "questionIndex": { "type": "integer", "minimum": 0, "maximum": 23 }, "most": { "type": "integer", "minimum": 0, "maximum": 3 }, "least": { "type": "integer", "minimum": 0, "maximum": 3 } }, "required": [ "questionIndex", "most", "least" ] } ] } }, { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } ] } }, "required": [ "assessmentType", "responses" ] }, "SubmitAssessmentResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "PENDING" ] } }, "required": [ "id", "status" ] }, "ConnectionPowerResponseDto": { "type": "object", "properties": { "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "nullable": true }, "assessmentCompletedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true } }, "required": [ "connectionPowerType", "assessmentCompletedAt" ] }, "AssessmentStatusPublicResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "SCORED", "FAILED" ] }, "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] }, "resultId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isCurrentUser": { "type": "boolean" }, "hasAccount": { "type": "boolean" } }, "required": [ "status", "assessmentType", "hasAccount" ] }, "AssessmentContextResponseDto": { "type": "object", "properties": { "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invitedEmail": { "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,}$" } }, "required": [ "individualId", "invitedEmail" ] }, "EncryptedQuestionBundleResponseDto": { "type": "object", "properties": { "encryptedBundle": { "type": "string", "minLength": 1 }, "iv": { "type": "string", "minLength": 1 }, "sessionKey": { "type": "string", "minLength": 1 }, "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "encryptedBundle", "iv", "sessionKey", "assignmentId" ] }, "AssessmentStatusResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "SCORED", "FAILED" ] }, "scoredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "nullable": true }, "resultSummary": { "type": "object", "properties": { "workMaskScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "underPressureScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "selfImageScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ] }, "traitSpectrums": { "minItems": 4, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "D", "I", "S", "C" ] }, "name": { "type": "string", "minLength": 1 }, "leftPole": { "type": "string", "minLength": 1 }, "rightPole": { "type": "string", "minLength": 1 }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "band": { "type": "string", "enum": [ "VeryHigh", "High", "Low", "VeryLow" ], "description": "Behaviour band per facet, derived from raw combined score per legacy spec §3.1" } }, "required": [ "dimension", "name", "leftPole", "rightPole", "position", "band" ] } } }, "required": [ "workMaskScores", "underPressureScores", "selfImageScores", "connectionPowerType", "traitSpectrums" ], "nullable": true } }, "required": [ "id", "status" ] }, "AssessmentHistoryResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] }, "scoredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "nullable": true }, "status": { "type": "string", "enum": [ "COMPLETED", "SCORED" ] }, "provenance": { "type": "object", "properties": { "organisationName": { "type": "string" } }, "required": [ "organisationName" ], "nullable": true } }, "required": [ "id", "assessmentType", "scoredAt", "connectionPowerType", "status", "provenance" ] } } }, "required": [ "data" ] }, "ComparisonProfileResponseDto": { "type": "object", "properties": { "viewer": { "type": "object", "properties": { "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ] }, "traitSpectrums": { "minItems": 4, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "D", "I", "S", "C" ] }, "name": { "type": "string", "minLength": 1 }, "leftPole": { "type": "string", "minLength": 1 }, "rightPole": { "type": "string", "minLength": 1 }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "band": { "type": "string", "enum": [ "VeryHigh", "High", "Low", "VeryLow" ], "description": "Behaviour band per facet, derived from raw combined score per legacy spec §3.1" } }, "required": [ "dimension", "name", "leftPole", "rightPole", "position", "band" ] } }, "selfImageScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "scoredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "discAdvanced": { "type": "object", "properties": { "workMaskScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "underPressureScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] } }, "required": [ "workMaskScores", "underPressureScores" ], "additionalProperties": false } }, "required": [ "connectionPowerType", "traitSpectrums", "selfImageScores", "scoredAt" ], "additionalProperties": false }, "colleague": { "type": "object", "properties": { "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ] }, "traitSpectrums": { "minItems": 4, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "D", "I", "S", "C" ] }, "name": { "type": "string", "minLength": 1 }, "leftPole": { "type": "string", "minLength": 1 }, "rightPole": { "type": "string", "minLength": 1 }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "band": { "type": "string", "enum": [ "VeryHigh", "High", "Low", "VeryLow" ], "description": "Behaviour band per facet, derived from raw combined score per legacy spec §3.1" } }, "required": [ "dimension", "name", "leftPole", "rightPole", "position", "band" ] } }, "selfImageScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "scoredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "discAdvanced": { "type": "object", "properties": { "workMaskScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "underPressureScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] } }, "required": [ "workMaskScores", "underPressureScores" ], "additionalProperties": false } }, "required": [ "connectionPowerType", "traitSpectrums", "selfImageScores", "scoredAt" ], "additionalProperties": false }, "reading": { "type": "string", "enum": [ "directional", "neutral" ], "description": "server-declared comparison reading: 'directional' (caller is one of the pair — self, second-person) or 'neutral' (caller is neither — colleague-vs-colleague, third-person)" }, "comparisonContent": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "description": "canonical snapshot key `comparison.{assessmentType}.{perspective}.{traitShortCode}.{individual1Banding}.{individual2Banding}` (derived at fetch)" }, "assessmentType": { "type": "string", "enum": [ "behaviour", "connection", "personality", "emotional_intelligence", "aptitude" ], "description": "the assessment instrument (or Family-B surface) a content item belongs to" }, "trait": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[a-z][a-z0-9_]*$", "description": "the trait both bands are measured on (same-trait, R7)" }, "individual1Banding": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[a-z][a-z0-9_]*$", "description": "individual 1's band — the viewer when perspective='self' (R6)" }, "individual2Banding": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[a-z][a-z0-9_]*$", "description": "individual 2's band — the named colleague when perspective='self' (R6)" }, "perspective": { "type": "string", "enum": [ "self", "other", "team" ], "description": "'self' (viewer vs colleague, directional) or 'other' (two colleagues, unordered) — R3" }, "description": { "type": "string", "description": "rich-text body (HTML): what the band pairing means" }, "action": { "type": "string", "description": "rich-text body (HTML): what to do about it (0–N

bullets)" } }, "required": [ "key", "assessmentType", "trait", "individual1Banding", "individual2Banding", "perspective", "description", "action" ], "additionalProperties": false, "description": "runtime shape of a unified, perspective-aware comparison_insight item" } } }, "required": [ "viewer", "colleague", "reading" ], "additionalProperties": false }, "BehaviourProfileResponseDto": { "type": "object", "properties": { "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ] }, "traitSpectrums": { "minItems": 4, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "D", "I", "S", "C" ] }, "name": { "type": "string", "minLength": 1 }, "leftPole": { "type": "string", "minLength": 1 }, "rightPole": { "type": "string", "minLength": 1 }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "band": { "type": "string", "enum": [ "VeryHigh", "High", "Low", "VeryLow" ], "description": "Behaviour band per facet, derived from raw combined score per legacy spec §3.1" } }, "required": [ "dimension", "name", "leftPole", "rightPole", "position", "band" ] } }, "selfImageScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "scoredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "discAdvanced": { "type": "object", "properties": { "workMaskScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] }, "underPressureScores": { "type": "object", "properties": { "d": { "type": "integer", "minimum": 0, "maximum": 1000 }, "i": { "type": "integer", "minimum": 0, "maximum": 1000 }, "s": { "type": "integer", "minimum": 0, "maximum": 1000 }, "c": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "d", "i", "s", "c" ] } }, "required": [ "workMaskScores", "underPressureScores" ], "additionalProperties": false } }, "required": [ "connectionPowerType", "traitSpectrums", "selfImageScores", "scoredAt" ], "additionalProperties": false }, "CreateAssignmentRequestDto": { "type": "object", "properties": { "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "individualId", "assessmentType" ] }, "AssignmentResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] }, "assignedBy": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assignedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "EXPIRED" ] }, "resultId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "accessToken": { "type": "string" }, "created": { "type": "boolean" } }, "required": [ "id", "tenantId", "individualId", "assessmentType", "assignedBy", "assignedAt", "status", "createdAt", "updatedAt" ] }, "BulkCreateAssignmentRequestDto": { "type": "object", "properties": { "individualIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "individualIds", "assessmentType" ] }, "BulkAssignmentResponseDto": { "type": "object", "properties": { "created": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] }, "assignedBy": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assignedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "EXPIRED" ] }, "resultId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "accessToken": { "type": "string" }, "created": { "type": "boolean" } }, "required": [ "id", "tenantId", "individualId", "assessmentType", "assignedBy", "assignedAt", "status", "createdAt", "updatedAt" ] } } }, "required": [ "created", "skipped", "results" ] }, "AssignmentListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] }, "assignedBy": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assignedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "EXPIRED" ] }, "resultId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "accessToken": { "type": "string" }, "created": { "type": "boolean" } }, "required": [ "id", "tenantId", "individualId", "assessmentType", "assignedBy", "assignedAt", "status", "createdAt", "updatedAt" ] } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "total" ] }, "ResumeAssignmentResponseDto": { "type": "object", "properties": { "accessToken": { "type": "string", "minLength": 1 } }, "required": [ "accessToken" ] }, "UpdateAssignmentStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "EXPIRED" ] } }, "required": [ "status" ] }, "CandidateBulkAssignResponseDto": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "succeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "total", "succeeded", "failed", "skipped" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "created", "skipped", "failed" ] }, "reason": { "type": "string" } }, "required": [ "individualId", "status" ] } } }, "required": [ "summary", "results" ] }, "SendAssessmentReminderRequestDto": { "type": "object", "properties": { "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assessmentType": { "type": "string", "enum": [ "behaviour", "personality" ] } }, "required": [ "individualId", "assessmentType" ] }, "SendAssessmentReminderResponseDto": { "type": "object", "properties": { "dispatched": { "type": "boolean" }, "alreadySent": { "type": "boolean" } }, "required": [ "dispatched", "alreadySent" ] }, "ReuseCheckResponseDto": { "type": "object", "properties": { "hasExistingResults": { "type": "boolean" }, "resultId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "assessmentType": { "type": "string", "nullable": true }, "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "nullable": true } }, "required": [ "hasExistingResults", "resultId", "assessmentType", "connectionPowerType" ] }, "ConsentBodyDto": { "type": "object", "properties": { "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "tenantId" ] }, "ConsentResponseDto": { "type": "object", "properties": { "consentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resultId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "consentedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "connectionPowerType": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "nullable": true } }, "required": [ "consentId", "resultId", "tenantId", "consentedAt", "connectionPowerType" ] }, "InitiateClaimDto": { "type": "object", "properties": { "email": { "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,}$" }, "orphanIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "InitiateClaimResponseDto": { "type": "object", "properties": { "claimId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "maskedEmail": { "type": "string" }, "orphanIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "claimId", "maskedEmail", "orphanIndividualId" ] }, "ResendClaimDto": { "type": "object", "properties": { "orphanIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "orphanIndividualId" ] }, "ResendClaimResponseDto": { "type": "object", "properties": { "accepted": { "type": "boolean", "description": "the re-send request was accepted", "enum": [ true ] } }, "required": [ "accepted" ] }, "VerifyClaimDto": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 } }, "required": [ "token" ] }, "VerifyClaimResponseDto": { "type": "object", "properties": { "merged": { "type": "boolean" }, "resultCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "merged", "resultCount" ] }, "PdfDownloadRequestDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "single-insight", "multi-insight", "full-profile" ] }, "contentSlots": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "mode" ] }, "PdfDownloadResponseDto": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1 } }, "required": [ "jobId" ] }, "PdfStatusResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processing", "failed" ] } }, "required": [ "status" ] }, "CreateSessionRequestDto": { "type": "object", "properties": { "keycloakToken": { "type": "string", "minLength": 1 }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "keycloakToken" ] }, "SessionResponseDto": { "type": "object", "properties": { "accessToken": { "type": "string", "minLength": 1, "description": "JWT access token for API authentication", "examples": [ "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature" ] }, "expiresIn": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "token validity duration in seconds", "examples": [ 600 ] }, "accessKind": { "default": "colleague", "description": "the logical access kind of the authenticated human relationship", "type": "string", "enum": [ "colleague", "integrations_admin" ] }, "role": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "viewer" ] }, { "type": "null" } ], "description": "role of the authenticated user in the current tenant; null for an Integrations Admin" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "current tenant identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "unique identifier of the authenticated individual", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "company-individual record identifier for the current tenant", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789abc" ] }, "isManager": { "default": false, "description": "whether the user manages at least one active direct report (content-selection only, not an RBAC role)", "examples": [ false ], "type": "boolean" }, "relationshipType": { "default": "employee", "description": "the authenticated user's relationship to the current tenant (candidate / employee / former_employee)", "examples": [ "employee" ], "type": "string", "enum": [ "candidate", "employee", "former_employee" ] } }, "required": [ "accessToken", "expiresIn", "role", "tenantId", "individualId", "companyIndividualId" ] }, "SwitchOrgRequestDto": { "type": "object", "properties": { "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "target organisation tenant identifier to switch to", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] } }, "required": [ "tenantId" ] }, "CreateInvitationRequestDto": { "type": "object", "properties": { "email": { "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,}$", "description": "email address of the person to invite", "examples": [ "jane.doe@acme.com" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ], "description": "role to assign to the invited user" }, "firstName": { "description": "first name of the invited person", "examples": [ "Jane" ], "type": "string", "minLength": 1 }, "lastName": { "description": "last name of the invited person", "examples": [ "Doe" ], "type": "string", "minLength": 1 } }, "required": [ "email", "role" ] }, "CreateInvitationResponseDto": { "type": "object", "properties": { "invitationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "identifier of the created invitation" }, "token": { "type": "string", "minLength": 1, "description": "raw invitation token to embed in the invite link" } }, "required": [ "invitationId", "token" ] }, "RedeemInvitationRequestDto": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "invitation token received via email", "examples": [ "dG9rZW4tYWJjMTIzLWRlZjQ1Ni1naGk3ODk" ] } }, "required": [ "token" ] }, "ValidateInvitationResponseDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "pending", "accepted", "revoked", "expired" ], "description": "resolved lifecycle state of an invitation token" }, "invitedEmail": { "anyOf": [ { "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,}$" }, { "type": "string", "const": "" } ], "description": "email the invitation was issued to, or empty when the invitation has not resolved an individual", "examples": [ "jane.doe@acme.com", "" ] }, "orgName": { "type": "string", "description": "name of the inviting organisation", "examples": [ "Acme Ltd" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ], "description": "role the invitation grants" }, "individualId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "resolved individual, if pre-resolved at creation" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant the invitation belongs to" } }, "required": [ "state", "invitedEmail", "orgName", "role", "individualId", "tenantId" ] }, "RedeemInvitationResponseDto": { "type": "object", "properties": { "individualId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "resolved individual, or null if not pre-resolved" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant the invitation belongs to" }, "role": { "type": "string", "enum": [ "owner", "admin", "viewer" ], "description": "role the invitation grants" } }, "required": [ "individualId", "tenantId", "role" ] }, "ProfileInsightCardsResponseDto": { "type": "object", "properties": { "cards": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "description": "discriminant — a fully-resolved, renderable card", "enum": [ "open" ] }, "contentSlot": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[a-z][a-z0-9_]*$", "description": "the content slot this card renders" }, "heading": { "type": "string", "minLength": 1, "description": "authored card heading (translated content attribute)" }, "description": { "type": "string", "description": "authored card description rich-text" }, "paragraphs": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "assembled, token-substituted body paragraphs, in displayOrder" }, "icon": { "type": "string", "description": "authored icon id — carried even though web omits it (R1)" }, "sourcedFrom": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "behaviour", "connection", "personality", "emotional_intelligence", "aptitude" ], "description": "the assessment instrument (or Family-B surface) a content item belongs to" }, "description": "The DISTINCT instruments whose content items fed this card, in canonical enum order. Required and non-empty — a card always comes from ≥1 instrument. Drives the \"SOURCED FROM\" provenance badge. Today the single-instrument serving path yields [\"behaviour\"]." } }, "required": [ "state", "contentSlot", "heading", "description", "paragraphs", "icon", "sourcedFrom" ], "additionalProperties": false, "description": "a render-ready resolved (OPEN) profile insight card" }, { "type": "object", "properties": { "state": { "type": "string", "description": "discriminant — a gated card whose prerequisite instrument(s) are incomplete", "enum": [ "locked" ] }, "contentSlot": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[a-z][a-z0-9_]*$", "description": "the content slot this locked card holds (keeps its app-default order slot)" }, "heading": { "type": "string", "minLength": 1, "description": "authored card heading — the topic that is coming up (the locked card title)" }, "missingAssessments": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "behaviour", "connection", "personality", "emotional_intelligence", "aptitude" ], "description": "the assessment instrument (or Family-B surface) a content item belongs to" }, "description": "the UNMET required instruments, in the card's AUTHORED required_assessments order (Q3). Non-empty — a locked card always names ≥1 missing instrument (the first drives the self \"Take {X}\" CTA / other \"Not yet available\" notice; R5 guarantees it is never Behaviour)." }, "tease": { "description": "SELF-only genuine content tease (the authored description as plain text). OMITTED on the other perspective — a colleague insight is never teased (ADR-009 / firm content principle).", "type": "string" } }, "required": [ "state", "contentSlot", "heading", "missingAssessments" ], "additionalProperties": false, "description": "a gated (LOCKED) profile insight card — nothing to show yet" } ], "description": "a per-position profile insight card — OPEN (resolved content) or LOCKED (gated)" }, "description": "cards in app-default order (snapshot/displayOrder; FR8 — no personalised re-sort)" }, "slots": { "default": [], "description": "THO-XXXX: resolved content for bespoke-surface slots (profile rail, Overview tab). Independent of `cards` — a slot here has no card and never renders as a tile. `.default([])` so a client reading an older response still parses.", "type": "array", "items": { "type": "object", "properties": { "contentSlot": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[a-z][a-z0-9_]*$", "description": "the content slot this content was resolved for" }, "paragraphs": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "assembled, token-substituted body paragraphs, in displayOrder" }, "sourcedFrom": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "behaviour", "connection", "personality", "emotional_intelligence", "aptitude" ], "description": "the assessment instrument (or Family-B surface) a content item belongs to" }, "description": "the DISTINCT instruments whose content items fed this slot, in enum order" } }, "required": [ "contentSlot", "paragraphs", "sourcedFrom" ], "additionalProperties": false, "description": "resolved content for one bespoke-surface content slot (no card chrome)" } }, "floor": { "anyOf": [ { "type": "object", "properties": { "heading": { "type": "string", "minLength": 1, "description": "floor heading (self-voice never-blank section)" }, "body": { "type": "string", "minLength": 1, "description": "floor body copy" } }, "required": [ "heading", "body" ], "additionalProperties": false, "description": "page-level never-blank floor shown only when zero cards render" }, { "type": "null" } ], "description": "non-null ONLY when zero cards render (mutually exclusive with a non-empty cards array)" } }, "required": [ "cards", "floor" ], "additionalProperties": false }, "CompleteOnboardingRequestDto": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "first name of the user" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "last name of the user" }, "jobTitle": { "description": "optional job title", "type": "string", "maxLength": 200 }, "languagePreference": { "type": "string", "enum": [ "en-gb" ], "description": "preferred platform language code" }, "tcConsentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "timestamp when T&C consent was given" }, "privacyConsentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "timestamp when privacy policy consent was given" } }, "required": [ "firstName", "lastName", "languagePreference", "tcConsentAt", "privacyConsentAt" ] }, "CompleteOnboardingResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "whether onboarding was completed successfully" }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "timestamp when onboarding was completed" } }, "required": [ "success", "completedAt" ] }, "OnboardingStatusResponseDto": { "type": "object", "properties": { "completed": { "type": "boolean", "description": "whether onboarding has been completed" }, "firstName": { "description": "first name from Individual record (when not completed)", "type": "string" }, "lastName": { "description": "last name from Individual record (when not completed)", "type": "string" }, "email": { "description": "email from Individual record (when not completed)", "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,}$" }, "claimableHistory": { "description": "present when claimable assessment history was detected", "type": "object", "properties": { "orphanEmail": { "type": "string", "description": "masked email of the claimable individual" }, "orphanIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "ID of the individual with claimable history" } }, "required": [ "orphanEmail", "orphanIndividualId" ] } }, "required": [ "completed" ] }, "RecordTransparencyAcceptanceRequestDto": { "type": "object", "properties": { "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "locale": { "type": "string", "minLength": 2 } }, "required": [ "assignmentId" ] }, "TransparencyAcceptanceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "controller": { "type": "string", "minLength": 1 }, "purpose": { "type": "string", "enum": [ "recruitment", "employment" ] }, "subjectPrincipal": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "locale": { "type": "string", "minLength": 2 }, "tcsVersionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "acceptedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "assignmentId", "controller", "purpose", "subjectPrincipal", "locale", "tcsVersionHash", "acceptedAt", "createdAt" ] }, "PersonalityReaderResultDto": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ] }, "gradient": { "type": "object", "properties": { "tier": { "type": "string", "minLength": 1 }, "traits": { "minItems": 6, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "conscientiousness", "adjustment", "curiosity", "riskApproach", "ambiguityAcceptance", "competitiveness" ] }, "label": { "type": "string", "minLength": 1 }, "percentile": { "type": "integer", "minimum": 1, "maximum": 99 }, "contentBand": { "type": "string", "enum": [ "very_low", "low", "moderate", "high", "very_high" ] }, "definition": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 } }, "required": [ "key", "label", "percentile", "contentBand" ], "additionalProperties": false } }, "relativeStrengths": { "minItems": 3, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "trait": { "type": "string", "enum": [ "conscientiousness", "adjustment", "curiosity", "riskApproach", "ambiguityAcceptance", "competitiveness" ] }, "rank": { "type": "integer", "minimum": 1, "maximum": 3 }, "direction": { "type": "string", "enum": [ "high", "low" ] } }, "required": [ "trait", "rank", "direction" ], "additionalProperties": false } } }, "required": [ "tier", "traits", "relativeStrengths" ], "additionalProperties": false }, "leadership": { "type": "object", "properties": { "tier": { "type": "string", "minLength": 1 }, "traits": { "minItems": 6, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "conscientiousness", "adjustment", "curiosity", "riskApproach", "ambiguityAcceptance", "competitiveness" ] }, "label": { "type": "string", "minLength": 1 }, "percentile": { "type": "integer", "minimum": 1, "maximum": 99 }, "definition": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "band": { "type": "string", "enum": [ "low", "moderate", "optimal", "excessive" ] }, "bandRanges": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "band": { "type": "string", "enum": [ "low", "moderate", "optimal", "excessive" ] }, "lower": { "type": "integer", "minimum": 1, "maximum": 99 }, "upper": { "type": "integer", "minimum": 1, "maximum": 99 }, "lowerInclusive": { "type": "boolean" }, "upperInclusive": { "type": "boolean" } }, "required": [ "band", "lower", "upper", "lowerInclusive", "upperInclusive" ] } }, "optimalLeadership": { "type": "integer", "minimum": 1, "maximum": 99 }, "leadershipImplication": { "type": "string", "minLength": 1 }, "leadershipTips": { "minItems": 3, "maxItems": 3, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "key", "label", "percentile", "band", "bandRanges", "optimalLeadership" ], "additionalProperties": false } }, "relativeStrengths": { "minItems": 3, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "trait": { "type": "string", "enum": [ "conscientiousness", "adjustment", "curiosity", "riskApproach", "ambiguityAcceptance", "competitiveness" ] }, "rank": { "type": "integer", "minimum": 1, "maximum": 3 }, "direction": { "type": "string", "enum": [ "high", "low" ] } }, "required": [ "trait", "rank", "direction" ], "additionalProperties": false } } }, "required": [ "tier", "traits", "relativeStrengths" ], "additionalProperties": false } }, "required": [ "status", "gradient" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "errored" ] } }, "required": [ "status" ], "additionalProperties": false } ] }, "PersonalityReaderSelfViewResultDto": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ] }, "selfView": { "type": "object", "properties": { "resultId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "viewerIsSubject": { "type": "boolean", "const": false }, "ratingEnabled": { "type": "boolean", "const": false }, "subjectName": { "type": "string", "minLength": 1 }, "freshnessStatus": { "type": "string", "enum": [ "fresh", "nudge", "decision-stale" ] }, "origin": { "type": "string", "enum": [ "recruitment", "employment" ] }, "asOfDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "blocks": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "definition": { "type": "string", "minLength": 1 }, "tips": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "blockId", "title", "tips" ] } }, "traitSummary": { "type": "array", "items": { "type": "object", "properties": { "traitKey": { "type": "string", "enum": [ "conscientiousness", "adjustment", "curiosity", "riskApproach", "ambiguityAcceptance", "competitiveness" ] }, "label": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 } }, "required": [ "traitKey", "label", "summary" ] } } }, "required": [ "resultId", "viewerIsSubject", "ratingEnabled", "subjectName", "freshnessStatus", "blocks", "traitSummary" ] } }, "required": [ "status", "selfView" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "status" ] } ] }, "PersonalityPdfRequestDto": { "type": "object", "properties": {}, "additionalProperties": false }, "PersonalityPdfResponseDto": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1 } }, "required": [ "jobId" ] }, "CreateExplicitTeamDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "team display name", "examples": [ "My Project Team" ] }, "memberIndividualIds": { "description": "individual IDs of initial team members (role=member)", "examples": [ [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] ], "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "ownerIndividualIds": { "description": "individual IDs of additional team owners beyond the creator", "examples": [ [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] ], "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "visibility": { "type": "string", "enum": [ "visible", "hidden" ], "description": "team visibility setting", "examples": [ "visible" ] } }, "required": [ "name" ] }, "TeamWithMembersResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "name": { "type": "string", "description": "team display name", "examples": [ "Alice Smith's team" ] }, "teamType": { "type": "string", "enum": [ "implicit", "explicit" ], "description": "type of team — implicit (from org hierarchy) or explicit (user-created)", "examples": [ "implicit" ] }, "sourceManagerIndividualId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "manager individual ID for implicit teams", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "visibility": { "type": "string", "enum": [ "visible", "hidden" ], "description": "team visibility setting", "examples": [ "visible" ] }, "firstSharedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "timestamp the team was first shared (visibility flipped to visible) — null until first share, immutable thereafter", "examples": [ null ] }, "needsOwnerAssignment": { "type": "boolean", "description": "whether the team currently has no active owner and needs reassignment", "examples": [ false ] }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "soft delete timestamp", "examples": [ null ] }, "inactiveAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "timestamp when team became inactive (all members archived)", "examples": [ null ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team-member row identifier", "examples": [ "d4e5f6a7-b8c9-4012-8def-234567890123" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "individual identifier", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "companyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "company individual identifier", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "role of a team member", "examples": [ "owner" ] }, "status": { "type": "string", "enum": [ "pending", "active", "archived", "deletion_requested" ], "description": "company-individual lifecycle status of this member — `active` owners are the ones that count toward the sole-host / orphan-detection guards (THO-1129)", "examples": [ "active" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] } }, "required": [ "id", "teamId", "individualId", "companyIndividualId", "tenantId", "role", "status", "createdAt", "updatedAt" ] }, "description": "team members including owners" } }, "required": [ "id", "tenantId", "name", "teamType", "sourceManagerIndividualId", "visibility", "firstSharedAt", "needsOwnerAssignment", "deletedAt", "inactiveAt", "createdAt", "updatedAt", "members" ] }, "ListConnectionTeamsResponseDto": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "tenant identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "name": { "type": "string", "description": "team display name", "examples": [ "Alice Smith's team" ] }, "teamType": { "type": "string", "enum": [ "implicit", "explicit" ], "description": "type of team — implicit (from org hierarchy) or explicit (user-created)", "examples": [ "implicit" ] }, "sourceManagerIndividualId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "manager individual ID for implicit teams", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "visibility": { "type": "string", "enum": [ "visible", "hidden" ], "description": "team visibility setting", "examples": [ "visible" ] }, "firstSharedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "timestamp the team was first shared (visibility flipped to visible) — null until first share, immutable thereafter", "examples": [ null ] }, "needsOwnerAssignment": { "type": "boolean", "description": "whether the team currently has no active owner and needs reassignment", "examples": [ false ] }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "soft delete timestamp", "examples": [ null ] }, "inactiveAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "timestamp when team became inactive (all members archived)", "examples": [ null ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-01-15T10:30:00.000Z" ] } }, "required": [ "id", "tenantId", "name", "teamType", "sourceManagerIndividualId", "visibility", "firstSharedAt", "needsOwnerAssignment", "deletedAt", "inactiveAt", "createdAt", "updatedAt" ] } }, "TeamDynamicsResponseDto": { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "members": { "type": "array", "items": { "type": "object", "properties": { "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "individual identifier of the team member", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "displayName": { "type": "string", "minLength": 1, "description": "first name of the team member for display in the People panel", "examples": [ "Alice" ] }, "connectionPower": { "anyOf": [ { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "description": "behavioural archetype used for colour-coding connection powers", "examples": [ "action" ] }, { "type": "null" } ], "description": "dominant connection power — null when unassessed", "examples": [ "energy" ] }, "behaviourScales": { "anyOf": [ { "type": "object", "properties": { "accommodatingDirect": { "type": "number", "minimum": 0, "maximum": 100, "description": "bipolar scale: Accommodating (0) to Direct (100)", "examples": [ 72 ] }, "reflectiveOutgoing": { "type": "number", "minimum": 0, "maximum": 100, "description": "bipolar scale: Reflective (0) to Outgoing (100)", "examples": [ 45 ] }, "spontaneousMethodical": { "type": "number", "minimum": 0, "maximum": 100, "description": "bipolar scale: Spontaneous (0) to Methodical (100)", "examples": [ 88 ] }, "pragmaticPerfectionist": { "type": "number", "minimum": 0, "maximum": 100, "description": "bipolar scale: Pragmatic (0) to Perfectionist (100)", "examples": [ 33 ] } }, "required": [ "accommodatingDirect", "reflectiveOutgoing", "spontaneousMethodical", "pragmaticPerfectionist" ] }, { "type": "null" } ], "description": "four bipolar dimension scale scores — null when unassessed", "examples": [ null ] }, "assessmentStatus": { "type": "string", "enum": [ "assessed", "unassessed" ], "description": "whether this member has completed their assessment", "examples": [ "assessed" ] } }, "required": [ "individualId", "displayName", "connectionPower", "behaviourScales", "assessmentStatus" ] }, "description": "all team members regardless of assessment status", "examples": [ [] ] }, "powerDistribution": { "type": "object", "properties": { "action": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "count of assessed members with action power", "examples": [ 3 ] }, "energy": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "count of assessed members with energy power", "examples": [ 2 ] }, "stability": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "count of assessed members with stability power", "examples": [ 4 ] }, "precision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "count of assessed members with precision power", "examples": [ 1 ] } }, "required": [ "action", "energy", "stability", "precision" ], "description": "count of assessed members per connection power", "examples": [ { "action": 3, "energy": 2, "stability": 4, "precision": 1 } ] }, "dominantPower": { "anyOf": [ { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "description": "behavioural archetype used for colour-coding connection powers", "examples": [ "action" ] }, { "type": "null" } ], "description": "most common power — null when no assessed members; tie-break falls back to action", "examples": [ "stability" ] }, "strengthsAndWatchouts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "strength", "watchout" ], "description": "discriminator for strength vs watch-out styling", "examples": [ "strength" ] }, "title": { "type": "string", "description": "card heading", "examples": [ "High Energy Collaboration" ] }, "description": { "type": "string", "description": "card body text", "examples": [ "Your team thrives on energetic discussion and quick decision-making." ] }, "narrativeContent": { "anyOf": [ { "type": "object", "properties": { "body": { "type": "string", "description": "narrative text with embedded token placeholders", "examples": [ "%firstName, your team shows a strong preference for action." ] }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "description": "token placeholder in narrative body (e.g. %firstName)", "examples": [ "%firstName" ] }, "value": { "type": "string", "description": "runtime replacement value for the token", "examples": [ "Alice" ] } }, "required": [ "key", "value" ] }, "description": "list of token key/value pairs for runtime replacement", "examples": [ [ { "key": "%firstName", "value": "Alice" } ] ] } }, "required": [ "body", "tokens" ] }, { "type": "null" } ], "description": "optional personalised narrative with runtime tokens", "examples": [ null ] } }, "required": [ "type", "title", "description", "narrativeContent" ] }, "description": "strength and watch-out cards — may be empty array", "examples": [ [] ] }, "teamProfileSummary": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "trait": { "type": "string", "enum": [ "D", "I", "S", "C" ], "description": "the DISC trait this Detail-tab profile paragraph belongs to", "examples": [ "S" ] }, "content": { "anyOf": [ { "type": "object", "properties": { "body": { "type": "string", "description": "narrative text with embedded token placeholders", "examples": [ "%firstName, your team shows a strong preference for action." ] }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "description": "token placeholder in narrative body (e.g. %firstName)", "examples": [ "%firstName" ] }, "value": { "type": "string", "description": "runtime replacement value for the token", "examples": [ "Alice" ] } }, "required": [ "key", "value" ] }, "description": "list of token key/value pairs for runtime replacement", "examples": [ [ { "key": "%firstName", "value": "Alice" } ] ] } }, "required": [ "body", "tokens" ] }, { "type": "null" } ], "description": "the trait × mean-team-band profile paragraph — null when that item is unauthored", "examples": [ null ] } }, "required": [ "trait", "content" ] } }, { "type": "null" } ], "description": "per-DISC-trait Detail-tab profile paragraphs (D/I/S/C order) — null when no assessed members", "examples": [ null ] } }, "required": [ "teamId", "members", "powerDistribution", "dominantPower", "strengthsAndWatchouts", "teamProfileSummary" ] }, "ConnectionPowerProfileResponseDto": { "type": "object", "properties": { "power": { "type": "string", "enum": [ "action", "energy", "stability", "precision" ], "description": "the spotlight member power this profile is keyed by — distinct from the team-level dominant power", "examples": [ "action" ] }, "strengthsToDrawOn": { "anyOf": [ { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "description": "per-power prose body authored in Kontent.ai", "examples": [ "Sarah moves fast — Action dominance means momentum is never a problem." ] } }, "required": [ "body" ] }, { "type": "null" } ], "description": "strengths-to-draw-on card; null when no Kontent.ai entry exists for this power", "examples": [ null ] }, "howToBringThemIn": { "anyOf": [ { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "description": "per-power prose body authored in Kontent.ai", "examples": [ "Sarah moves fast — Action dominance means momentum is never a problem." ] } }, "required": [ "body" ] }, { "type": "null" } ], "description": "how-to-bring-them-in card; null when no Kontent.ai entry exists for this power", "examples": [ null ] } }, "required": [ "power", "strengthsToDrawOn", "howToBringThemIn" ] }, "TeamSessionsSummaryResponseDto": { "type": "object", "properties": { "nextSession": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "scheduledDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true } }, "required": [ "id", "name", "scheduledDate" ] }, { "type": "null" } ], "description": "soonest planned session by scheduledDate ASC; null when no planned session exists" }, "completedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "count of sessions in status=completed for this team" } }, "required": [ "nextSession", "completedCount" ] }, "TeamSessionListResponseDto": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "session identifier", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "session display name", "examples": [ "Q2 Trust Building" ] }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "discarded" ] }, "intent": { "type": "string", "minLength": 1, "maxLength": 500, "description": "session intent", "examples": [ "improve_communication" ] }, "customIntent": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "custom intent text, null if standard intent used", "examples": [ null ] }, "durationMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "session duration in minutes", "examples": [ 90 ] }, "scheduledDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "scheduled date/time, null if not scheduled", "examples": [ "2026-05-15T14:00:00.000Z" ] }, "keyTakeaways": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "key takeaways captured at session close, null until completed", "examples": [ "We agreed to add a 5-minute pause before big decisions.", null ] }, "actionItems": { "description": "action items associated with this session", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "action item identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "parent session identifier", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "assigneeIndividualId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "individual assigned to this action item; null = team-level (whole team) action", "examples": [ "c3d4e5f6-a7b8-4123-9def-234567890123", null ] }, "text": { "type": "string", "minLength": 1, "description": "action item description", "examples": [ "Schedule 1:1 with each team member" ] }, "completed": { "type": "boolean", "description": "whether the action item has been completed", "examples": [ false ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-05-15T14:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-05-15T14:30:00.000Z" ] } }, "required": [ "id", "sessionId", "assigneeIndividualId", "text", "completed", "createdAt", "updatedAt" ] } }, "reflectDraft": { "description": "mid-session reflect draft; null/absent when none saved or after Complete/Discard", "anyOf": [ { "type": "object", "properties": { "takeaways": { "type": "string", "maxLength": 5000, "description": "saved key-takeaways draft (empty string when none saved yet)", "examples": [ "We agreed to add a 5-minute pause before big decisions." ] }, "actions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500, "description": "queued team-action text", "examples": [ "Block 30 mins on Mondays for a no-meetings focus window." ] }, "suggested": { "type": "boolean", "description": "true when added from a ThomAI suggestion, false for a custom action" }, "suggestionId": { "description": "source suggestion id when suggested=true; carries the \"Added\" tick across reload", "examples": [ "build_trust-1" ], "type": "string", "minLength": 1 } }, "required": [ "text", "suggested" ] }, "description": "queued team actions in display order" } }, "required": [ "takeaways", "actions" ] }, { "type": "null" } ] }, "diveInQuestionTotal": { "description": "total number of dive-in question prompts for this session intent (populated on completed-session reads)", "examples": [ 3 ], "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "discussionItemIds": { "description": "curated discussion items in display order (ontology + custom-question ids)", "type": "array", "items": { "type": "string", "minLength": 1 } }, "customQuestions": { "description": "hydrated content for any custom-question ids", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "stable custom-question id (matches an entry in discussionItemIds)" }, "content": { "type": "string", "minLength": 1, "maxLength": 500, "description": "author-supplied question text" } }, "required": [ "id", "content" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-05-15T14:00:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-05-15T14:00:00.000Z" ] } }, "required": [ "id", "teamId", "name", "status", "intent", "customIntent", "durationMinutes", "scheduledDate", "keyTakeaways", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "1-indexed page number" }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "rows per page" }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "total session count for the team" }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "total page count derived from total / pageSize" } }, "required": [ "page", "pageSize", "total", "totalPages" ] } }, "required": [ "sessions", "pagination" ] }, "UpdateExplicitTeamDto": { "type": "object", "properties": { "name": { "description": "team display name", "examples": [ "Updated Team Name" ], "type": "string", "minLength": 1, "maxLength": 100 }, "visibility": { "type": "string", "enum": [ "visible", "hidden" ], "description": "team visibility setting", "examples": [ "visible" ] }, "memberIndividualIds": { "description": "full replacement list of member individual IDs (role=member)", "examples": [ [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] ], "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "ownerIndividualIds": { "description": "full replacement list of owner individual IDs", "examples": [ [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] ], "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } }, "TeamTransferOwnershipDto": { "type": "object", "properties": { "targetIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "individual ID of the new owner" } }, "required": [ "targetIndividualId" ] }, "ReassignTeamOwnerDto": { "type": "object", "properties": { "newOwnerIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "individual ID of the new team owner" } }, "required": [ "newOwnerIndividualId" ] }, "ReassignTeamOwnerResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "name": { "type": "string", "description": "team display name", "examples": [ "Alice Smith's team" ] } }, "required": [ "id", "name" ] }, "ProfileConnectionReflectionsResponseDto": { "type": "object", "properties": { "reflections": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the personal-reflection run identifier (matches connection_measure_runs.id)", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC timestamp the user submitted the reflection (connection_measure_runs.closedAt; personal-reflection runs are single-participant per Pattern 7, so submission closes the run and closedAt is the canonical submit time — see Guarantee #7 in the Cross-PRD Routing Contract above)", "examples": [ "2026-04-15T10:30:00.000Z" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the team the user reflected on (FR22 default-from-manager or FR21 alternative pick)", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "teamName": { "type": "string", "minLength": 1, "description": "live-derived team display name at fetch time", "examples": [ "Engineering Team" ] }, "dimensions": { "minItems": 6, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "dimension score on a 0–100 scale (FR42a)", "examples": [ 72 ] }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "dimension", "score", "banding" ] }, "description": "six dimension scores; personal reflections are single-participant and not subject to min-group-3 suppression (Pattern 7)", "examples": [ [ { "dimension": "appreciation", "score": 78, "banding": "MODERATE" }, { "dimension": "belonging", "score": 85, "banding": "HIGH" }, { "dimension": "cohesion", "score": 62, "banding": "LOW" }, { "dimension": "contribution", "score": 71, "banding": "MODERATE" }, { "dimension": "trust", "score": 88, "banding": "HIGH" }, { "dimension": "wellbeing", "score": 74, "banding": "MODERATE" } ] ] }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "overall composite score for this reflection (FR42a)", "examples": [ 76.3 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for the overall score", "examples": [ "MODERATE" ] } }, "required": [ "runId", "submittedAt", "teamId", "teamName", "dimensions", "overallScore", "overallBanding" ] }, "description": "private list of the requester's Template 1 reflections, newest-first (FR24a)", "examples": [ [] ] } }, "required": [ "reflections" ] }, "IndividualConnectionScoreResponseDto": { "type": "object", "properties": { "compositeScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "overall composite score for selected team (FR47); null when no closed runs exist on any team", "examples": [ 73.8, null ] }, "banding": { "anyOf": [ { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] }, { "type": "null" } ], "description": "banding for the composite score; null when compositeScore is null", "examples": [ "MODERATE", null ] }, "teamId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "the team selected by FR47 tiebreakers a/b/c; null when no qualifying team", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479", null ] }, "teamName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "live-derived team display name; null when no qualifying team", "examples": [ "Engineering Team", null ] }, "teamType": { "anyOf": [ { "type": "string", "enum": [ "implicit", "explicit" ], "description": "type of team — implicit (from org hierarchy) or explicit (user-created)", "examples": [ "implicit" ] }, { "type": "null" } ], "description": "implicit or explicit (FR47 tiebreaker b prefers explicit); null when no qualifying team", "examples": [ "implicit", null ] }, "runClosedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "UTC closedAt of the run whose composite is shown; null when no qualifying team", "examples": [ "2026-04-15T10:30:00.000Z", null ] }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "UUID of the FR47-selected run; null when no qualifying team. Pairs with runClosedAt.", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479", null ] }, "previousCompositeScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "composite of the immediately prior scored run on the FR47-selected team; null on first-ever run or when the all-null cohort applies", "examples": [ 70.5, null ] }, "overallTrend": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "integer delta of compositeScore vs the immediately prior scored run on the FR47-selected team. Backend-computed; FE never re-derives. Null on first-ever run.", "examples": [ 3, null ] } }, "required": [ "compositeScore", "banding", "teamId", "teamName", "teamType", "runClosedAt", "runId", "previousCompositeScore", "overallTrend" ] }, "ProfileConnectionTeamResultsResponseDto": { "type": "object", "properties": { "teamResults": { "type": "array", "items": { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the team membership the row represents", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "teamName": { "type": "string", "minLength": 1, "description": "live-derived team display name at fetch time", "examples": [ "Engineering Team" ] }, "teamType": { "type": "string", "enum": [ "implicit", "explicit" ], "description": "explicit (admin-created) or implicit (manager-link)", "examples": [ "implicit" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the closed scored team-checkin run this row represents", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "runClosedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC timestamp the run closed (connection_measure_runs.closedAt)", "examples": [ "2026-04-15T10:30:00.000Z" ] }, "runRequestedByName": { "type": "string", "minLength": 1, "description": "display name of the company-individual who requested the run", "examples": [ "Alex Manager" ] }, "overallScore": { "type": "integer", "minimum": 0, "maximum": 100, "description": "team aggregate overall composite score for this run (0..100 integer per AC #4)", "examples": [ 76 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for the team aggregate overall score", "examples": [ "MODERATE" ] } }, "required": [ "teamId", "teamName", "teamType", "runId", "runClosedAt", "runRequestedByName", "overallScore", "overallBanding" ] }, "description": "private list of team-results enriched with the subject's score, newest-first by runClosedAt", "examples": [ [] ] } }, "required": [ "teamResults" ] }, "OrganisationHeatmapResponseDto": { "type": "object", "properties": { "teams": { "type": "array", "items": { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier; live-derived", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "teamName": { "type": "string", "minLength": 1, "description": "live-derived team display name (no snapshot, consistent with home-hero)", "examples": [ "Engineering Team" ] }, "teamType": { "type": "string", "enum": [ "implicit", "explicit" ], "description": "drives row icon (FR53: buildings for implicit, users for explicit)", "examples": [ "implicit" ] }, "dimensions": { "minItems": 6, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "cell": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "no-run", "in-progress", "insufficient", "scored" ], "description": "drives all four FR53b rendering branches", "examples": [ "scored" ] }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "cell numeric score on 0-100 scale; null unless state === scored", "examples": [ 73, null ] }, "banding": { "anyOf": [ { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] }, { "type": "null" } ], "description": "banding for cell score; null unless state === scored", "examples": [ "MODERATE", null ] }, "trendDelta": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "signed delta vs prior closed run; null when no prior or state !== scored", "examples": [ 4.5, null ] }, "priorScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "prior closed run score; atomically paired with trendDelta", "examples": [ 69.3, null ] } }, "required": [ "state", "score", "banding", "trendDelta", "priorScore" ] } }, "required": [ "dimension", "cell" ] }, "description": "exactly six dimension cells, in display order — see ConnectionDimensions constant" }, "overall": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "no-run", "in-progress", "insufficient", "scored" ], "description": "drives all four FR53b rendering branches", "examples": [ "scored" ] }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "cell numeric score on 0-100 scale; null unless state === scored", "examples": [ 73, null ] }, "banding": { "anyOf": [ { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] }, { "type": "null" } ], "description": "banding for cell score; null unless state === scored", "examples": [ "MODERATE", null ] }, "trendDelta": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "signed delta vs prior closed run; null when no prior or state !== scored", "examples": [ 4.5, null ] }, "priorScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "prior closed run score; atomically paired with trendDelta", "examples": [ 69.3, null ] } }, "required": [ "state", "score", "banding", "trendDelta", "priorScore" ], "description": "the overall composite cell; uses $--static-{pink,orange,green}-300 tokens per FR67l" }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "latest run identifier for this team; null only when no run exists", "examples": [ "b2c3d4e5-f6a7-4901-bcde-f12345678901", null ] }, "runStatus": { "anyOf": [ { "type": "string", "enum": [ "scheduled", "open", "scored", "cancelled" ], "description": "run lifecycle state (A3: sealed-run model)", "examples": [ "open" ] }, { "type": "null" } ], "description": "latest run status; mirrors connection_measure_runs.status; null when no run", "examples": [ "scored", null ] }, "participantCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "participants on the latest run; null when no run", "examples": [ 5, null ] }, "teamMemberCount": { "description": "total team membership size (the Responses-column denominator); null when no membership row exists for the team", "examples": [ 12, null ], "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "departments": { "description": "distinct department names across the team members (derived from memberships.department, deduplicated, in stable sort order); empty array when no member has a department string", "examples": [ [ "Engineering", "Design" ], [] ], "type": "array", "items": { "type": "string", "minLength": 1 } }, "host": { "description": "team host: explicit teams → team owner, implicit teams → manager link target; null when neither exists", "examples": [ { "id": "b2c3d4e5-f6a7-4901-bcde-f12345678901", "name": "Jane Smith" }, null ], "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1 } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "runClosedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "latest scored-run closedAt; null when latest run is not yet scored", "examples": [ "2026-04-15T10:30:00.000Z", null ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "interval": { "type": "string", "enum": [ "monthly", "quarterly", "annually" ], "description": "recurrence interval (FR37 + THO-925)", "examples": [ "monthly", "quarterly", "annually" ] }, "nextRunDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "enabled": { "type": "boolean" } }, "required": [ "interval", "nextRunDate", "enabled" ] }, { "type": "null" } ], "description": "monthly recurrence config (FR37); null when no config row exists, otherwise the three sub-fields are all non-null" } }, "required": [ "teamId", "teamName", "teamType", "dimensions", "overall", "runId", "runStatus", "participantCount", "runClosedAt", "recurrence" ] }, "description": "team rows for the current page; empty when no teams in scope (FR50/FR52)" }, "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "echo of the requested period; frontend convenience for cache-key reads", "examples": [ "2026-04" ] }, "viewMode": { "type": "string", "enum": [ "score", "trends" ], "description": "echo of the requested view mode", "examples": [ "score" ] }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "1-indexed page number" }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "rows per page" }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "total in-scope team count after filters, before pagination" }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "total page count derived from total / pageSize" } }, "required": [ "page", "pageSize", "total", "totalPages" ], "description": "offset-pagination envelope; total reflects the filtered count before pagination" } }, "required": [ "teams", "period", "viewMode", "pagination" ] }, "BulkDeployRequestDto": { "type": "object", "properties": { "teamIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "UUIDs of teams to deploy a Connection Check-in to; 1-500 teams per FR27 + NFR4 scale", "examples": [ [ "f47ac10b-58cc-4372-a567-0e02b2c3d479", "a1b2c3d4-e5f6-4890-abcd-ef1234567890" ] ] }, "dueDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC due date applied to every selected team run; per-team dueDate divergence is out of scope (FR27)", "examples": [ "2026-05-15T23:59:59.000Z" ] }, "recurrenceInterval": { "description": "optional recurrence interval; omit for one-off deployment (FR27)", "examples": [ "monthly" ], "type": "string", "enum": [ "monthly", "quarterly", "annually" ] } }, "required": [ "teamIds", "dueDate" ] }, "BulkDeployResponseDto": { "type": "object", "properties": { "teams": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "success": { "type": "boolean", "enum": [ true ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "measureId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "dueDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "recurrencePersisted": { "type": "boolean" } }, "required": [ "teamId", "success", "runId", "measureId", "dueDate" ] }, { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "success": { "type": "boolean", "const": false }, "errorCode": { "type": "string", "enum": [ "RUN_ALREADY_OPEN", "TEAM_OUT_OF_SCOPE", "TEAM_NOT_FOUND", "DUE_DATE_IN_PAST", "DUE_DATE_EXCEEDS_MAX", "TEAM_HAS_NO_MEMBERS", "UNKNOWN" ], "description": "per-team failure / skip reason codes for bulk deploy", "examples": [ "RUN_ALREADY_OPEN" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "teamId", "success", "errorCode", "message" ] } ] } }, "successCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skippedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failureCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "teams", "successCount", "skippedCount", "failureCount" ] }, "RecurrenceConfigDto": { "type": "object", "properties": { "interval": { "type": "string", "enum": [ "monthly", "quarterly", "annually" ], "description": "recurrence cadence; the BullMQ processor uses this to compute the next nextRunDate after each fire", "examples": [ "monthly", "quarterly", "annually" ] }, "nextRunDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC timestamp of the next recurrence-driven run; mid-cycle interval edits do not mutate this — A6", "examples": [ "2026-05-15T10:00:00.000Z" ] }, "enabled": { "type": "boolean", "description": "FR37 enable/disable flag — false pauses recurrence without dropping the config row", "examples": [ true ] } }, "required": [ "interval", "nextRunDate", "enabled" ] }, "RecurrenceConfigResponseDto": { "type": "object", "properties": { "interval": { "type": "string", "enum": [ "monthly", "quarterly", "annually" ], "description": "recurrence cadence; the BullMQ processor uses this to compute the next nextRunDate after each fire", "examples": [ "monthly", "quarterly", "annually" ] }, "nextRunDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC timestamp of the next recurrence-driven run; mid-cycle interval edits do not mutate this — A6", "examples": [ "2026-05-15T10:00:00.000Z" ] }, "enabled": { "type": "boolean", "description": "FR37 enable/disable flag — false pauses recurrence without dropping the config row", "examples": [ true ] }, "measureId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "connection_measure row identifier persisting this recurrence", "examples": [ "c3d4e5f6-a7b8-4012-8def-123456789012" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team this recurrence configuration belongs to", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "recurrencePersisted": { "type": "boolean", "description": "true when the BullMQ recurrence job was enqueued in the same request; false when the column write committed but the queue.add threw (orphan to be healed by the bootstrap backfill sweep). Mirrors `BulkDeployTeamResultSchema.recurrencePersisted`.", "examples": [ true ] } }, "required": [ "interval", "nextRunDate", "enabled", "measureId", "teamId", "recurrencePersisted" ] }, "RequestCheckInDto": { "type": "object", "properties": { "measureType": { "type": "string", "enum": [ "personal_reflection", "team_checkin" ], "description": "type of connection measure — determines data flow and isolation rules", "examples": [ "team_checkin" ] }, "dueDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "due date — max 14 days from creation (FR30)", "examples": [ "2026-04-30T23:59:59.000Z" ] } }, "required": [ "measureType", "dueDate" ], "additionalProperties": false }, "RequestCheckInResponseDto": { "type": "object", "properties": { "measureId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "connection measure identifier", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "newly created run identifier", "examples": [ "d4e5f6a7-b890-1234-cdef-567890123456" ] }, "status": { "type": "string", "enum": [ "scheduled", "open", "scored", "cancelled" ], "description": "always open for one-off runs", "examples": [ "open" ] }, "dueDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "confirmed due date", "examples": [ "2026-04-30T23:59:59.000Z" ] }, "snapshotMemberCount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "total members captured in the run snapshot", "examples": [ 6 ] } }, "required": [ "measureId", "runId", "status", "dueDate", "snapshotMemberCount" ] }, "ParticipationResponseDto": { "type": "object", "properties": { "completed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "number of participants who have completed — never names (FR33)", "examples": [ 4 ] }, "total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "total snapshot members", "examples": [ 6 ] } }, "required": [ "completed", "total" ] }, "HistoricalRunListDto": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the closed run identifier (matches connection_measure_runs.id)", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "closedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC timestamp of the scored-run transition (FR44c)", "examples": [ "2026-04-15T10:30:00.000Z" ] }, "participantCount": { "type": "integer", "minimum": 3, "maximum": 9007199254740991, "description": "number of participants who completed; minimum 3 per FR44c (defence-in-depth pin against API filter regressions)", "examples": [ 5 ] }, "focusAreaDimension": { "anyOf": [ { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, { "type": "null" } ], "description": "focus area decided at close (FR48a); null when all dimensions are HIGH (FR48b)", "examples": [ "cohesion", null ] } }, "required": [ "runId", "closedAt", "participantCount", "focusAreaDimension" ] }, "description": "historical closed runs with ≥3 responses, newest-first by closedAt (FR44c)", "examples": [ [] ] } }, "required": [ "runs" ] }, "ConnectionDimensionContentDto": { "type": "object", "properties": { "narrative": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "connection_summary text with tokens resolved; null if no content entry exists for this dimension+locale" }, "habits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "text": { "type": "string" } }, "required": [ "id", "text" ] }, "description": "connection_habits items ordered by sortOrder" } }, "required": [ "narrative", "habits" ] }, "ConnectionMeasureRunResponseDto": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "run identifier", "examples": [ "d4e5f6a7-b890-1234-cdef-567890123456" ] }, "measureId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "parent measure identifier", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] }, "measureType": { "type": "string", "enum": [ "personal_reflection", "team_checkin" ], "description": "type of connection measure — determines data flow and isolation rules", "examples": [ "team_checkin" ] }, "status": { "type": "string", "enum": [ "scheduled", "open", "scored", "cancelled" ], "description": "run lifecycle state (A3: sealed-run model)", "examples": [ "open" ] }, "period": { "type": "string", "minLength": 1, "description": "period identifier for date stepper navigation (A2)", "examples": [ "2026-04" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "due date; null for scheduled runs", "examples": [ "2026-04-30T23:59:59.000Z" ] }, "participation": { "anyOf": [ { "type": "object", "properties": { "completed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "number of participants who have completed — never names (FR33)", "examples": [ 4 ] }, "total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "total snapshot members", "examples": [ 6 ] } }, "required": [ "completed", "total" ] }, { "type": "null" } ], "description": "participation count; null when scheduled", "examples": [ { "completed": 4, "total": 6 } ] }, "results": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run this result belongs to", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the team this result belongs to", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "dimension score on a 0–100 scale (FR42a)", "examples": [ 72 ] }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "dimension", "score", "banding" ] }, "description": "aggregated scores for all six dimensions; empty array when scoresAvailable is false (Pattern 3 suppression)" }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "overall composite score (FR42a)", "examples": [ 73.8 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for overall score", "examples": [ "MODERATE" ] }, "participantCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "number of participants who completed", "examples": [ 5 ] }, "scoresAvailable": { "type": "boolean", "description": "derived: true when participantCount >= min-group threshold (Pattern 3)", "examples": [ true ] }, "participantsNeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "max(0, threshold - participantCount) — frontend never imports the threshold", "examples": [ 0 ] }, "trendDeltas": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "delta": { "type": "number", "description": "signed difference from prior run score", "examples": [ 4.5 ] }, "priorScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "score from the prior scored run", "examples": [ 67.5 ] } }, "required": [ "dimension", "delta", "priorScore" ] } }, { "type": "null" } ], "description": "trend compared to prior scored run; null for first run", "examples": [ null ] }, "overallTrend": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "delta of the composite overallScore vs the immediately prior scored run, rounded to integer; null when no prior scored run exists. Backend-computed so the FE never re-derives from per-dimension deltas (which only equals the composite delta under uniform weighting).", "examples": [ 3 ] }, "focusArea": { "anyOf": [ { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, { "type": "null" } ], "description": "lowest-scoring dimension (FR48a); null for first run", "examples": [ "cohesion" ] } }, "required": [ "runId", "teamId", "dimensions", "overallScore", "overallBanding", "participantCount", "scoresAvailable", "participantsNeeded", "trendDeltas", "overallTrend", "focusArea" ] }, { "type": "null" } ], "description": "team aggregate results; null when not scored (sealed-run: Pattern 2)" } }, "required": [ "runId", "measureId", "measureType", "status", "period", "dueDate", "participation", "results" ] }, "TeamResultsPageResponseDto": { "type": "object", "properties": { "teamResult": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run this result belongs to", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the team this result belongs to", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "dimension score on a 0–100 scale (FR42a)", "examples": [ 72 ] }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "dimension", "score", "banding" ] }, "description": "aggregated scores for all six dimensions; empty array when scoresAvailable is false (Pattern 3 suppression)" }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "overall composite score (FR42a)", "examples": [ 73.8 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for overall score", "examples": [ "MODERATE" ] }, "participantCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "number of participants who completed", "examples": [ 5 ] }, "scoresAvailable": { "type": "boolean", "description": "derived: true when participantCount >= min-group threshold (Pattern 3)", "examples": [ true ] }, "participantsNeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "max(0, threshold - participantCount) — frontend never imports the threshold", "examples": [ 0 ] }, "trendDeltas": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "delta": { "type": "number", "description": "signed difference from prior run score", "examples": [ 4.5 ] }, "priorScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "score from the prior scored run", "examples": [ 67.5 ] } }, "required": [ "dimension", "delta", "priorScore" ] } }, { "type": "null" } ], "description": "trend compared to prior scored run; null for first run", "examples": [ null ] }, "overallTrend": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "delta of the composite overallScore vs the immediately prior scored run, rounded to integer; null when no prior scored run exists. Backend-computed so the FE never re-derives from per-dimension deltas (which only equals the composite delta under uniform weighting).", "examples": [ 3 ] }, "focusArea": { "anyOf": [ { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, { "type": "null" } ], "description": "lowest-scoring dimension (FR48a); null for first run", "examples": [ "cohesion" ] } }, "required": [ "runId", "teamId", "dimensions", "overallScore", "overallBanding", "participantCount", "scoresAvailable", "participantsNeeded", "trendDeltas", "overallTrend", "focusArea" ] }, "teamName": { "type": "string", "description": "team display name" }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team UUID" }, "teamType": { "type": "string", "enum": [ "implicit", "explicit" ], "description": "type of team — implicit (from org hierarchy) or explicit (user-created)", "examples": [ "implicit" ] }, "runPeriod": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "ISO month string (YYYY-MM) for the run period" }, "closedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "run-close timestamp for the team aggregate" }, "availablePeriods": { "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "description": "all scored run periods for this team, most recent first" }, "previousResult": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run this result belongs to", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the team this result belongs to", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "dimension score on a 0–100 scale (FR42a)", "examples": [ 72 ] }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "dimension", "score", "banding" ] }, "description": "aggregated scores for all six dimensions; empty array when scoresAvailable is false (Pattern 3 suppression)" }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "overall composite score (FR42a)", "examples": [ 73.8 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for overall score", "examples": [ "MODERATE" ] }, "participantCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "number of participants who completed", "examples": [ 5 ] }, "scoresAvailable": { "type": "boolean", "description": "derived: true when participantCount >= min-group threshold (Pattern 3)", "examples": [ true ] }, "participantsNeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "max(0, threshold - participantCount) — frontend never imports the threshold", "examples": [ 0 ] }, "trendDeltas": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "delta": { "type": "number", "description": "signed difference from prior run score", "examples": [ 4.5 ] }, "priorScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "score from the prior scored run", "examples": [ 67.5 ] } }, "required": [ "dimension", "delta", "priorScore" ] } }, { "type": "null" } ], "description": "trend compared to prior scored run; null for first run", "examples": [ null ] }, "overallTrend": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "delta of the composite overallScore vs the immediately prior scored run, rounded to integer; null when no prior scored run exists. Backend-computed so the FE never re-derives from per-dimension deltas (which only equals the composite delta under uniform weighting).", "examples": [ 3 ] }, "focusArea": { "anyOf": [ { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, { "type": "null" } ], "description": "lowest-scoring dimension (FR48a); null for first run", "examples": [ "cohesion" ] } }, "required": [ "runId", "teamId", "dimensions", "overallScore", "overallBanding", "participantCount", "scoresAvailable", "participantsNeeded", "trendDeltas", "overallTrend", "focusArea" ] }, { "type": "null" } ], "description": "prior team result for trend delta; null if first scored run" }, "narratives": { "anyOf": [ { "type": "object", "properties": { "overall": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "overall connection narrative; null until the AI-generated summary is available — the client collapses the hero slot on null" }, "dimensions": { "type": "object", "propertyNames": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "additionalProperties": { "type": "string" }, "required": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "per-dimension narrative keyed by dimension name; partial — E5.7 lazy endpoint owns per-dimension values" } }, "required": [ "overall", "dimensions" ] }, { "type": "null" } ], "description": "localised narratives with token replacement; null at MVP" }, "trailingSeries": { "description": "trailing closed-run scores up to and including the current run, oldest-first; max 6 values; per FR44b (sparkline of trailing 6 closed runs). Optional for backward compatibility with API nodes that have not yet shipped E5.6 — consumers should default missing values to empty arrays.", "type": "object", "properties": { "overall": { "maxItems": 6, "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 100 }, "description": "trailing overall scores up to and including the current run, oldest-first; max 6 values" }, "dimensions": { "type": "object", "propertyNames": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "additionalProperties": { "maxItems": 6, "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "trailing per-dimension scores keyed by dimension name; oldest-first; max 6 values per dimension" } }, "required": [ "overall", "dimensions" ] }, "viewerHasCompleted": { "type": "boolean", "description": "FR46a gate — true iff the viewer has a completed IndividualResult for this run; drives the \"My results\" cross-link" } }, "required": [ "teamResult", "teamName", "teamId", "teamType", "runPeriod", "closedAt", "availablePeriods", "previousResult", "narratives", "viewerHasCompleted" ] }, "TeamConnectionSummaryResponseDto": { "type": "object", "properties": { "lastScoredRun": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "most recent scored run identifier", "examples": [ "a3b1c2d4-5678-4901-abcd-1234567890ab" ] }, "period": { "type": "string", "description": "run period (ISO month or comparable label, mirrors ConnectionMeasureRun.period)", "examples": [ "2026-04" ] }, "focusArea": { "anyOf": [ { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, { "type": "null" } ], "description": "connection dimension flagged for follow-up; null when no flag (FR48b)" }, "focusAreaScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "score of the focus dimension; null when focusArea is null", "examples": [ 42 ] } }, "required": [ "runId", "period", "focusArea", "focusAreaScore" ] }, { "type": "null" } ], "description": "most recent scored run summary; null when team has no scored run yet" } }, "required": [ "lastScoredRun" ] }, "SendReminderResponseDto": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "run the reminder targeted", "examples": [ "d4e5f6a7-b890-1234-cdef-567890123456" ] }, "bucketKey": { "type": "string", "minLength": 1, "description": "6h idempotency bucket key (`:`)", "examples": [ "d4e5f6a7-b890-1234-cdef-567890123456:80345" ] }, "alreadySent": { "type": "boolean", "description": "true when the request was a no-op replay within the same 6h bucket", "examples": [ false ] } }, "required": [ "runId", "bucketKey", "alreadySent" ] }, "CancelRunResponseDto": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "run that was cancelled", "examples": [ "d4e5f6a7-b890-1234-cdef-567890123456" ] }, "status": { "type": "string", "description": "always cancelled — the response shape is fixed regardless of replay", "enum": [ "cancelled" ] }, "alreadyCancelled": { "type": "boolean", "description": "true when the run was already cancelled before this call (no-op replay)", "examples": [ false ] } }, "required": [ "runId", "status", "alreadyCancelled" ] }, "ConnectionMeasureResponseDto": { "type": "object", "properties": { "measureId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "measure identifier", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "measureType": { "type": "string", "enum": [ "personal_reflection", "team_checkin" ], "description": "type of connection measure — determines data flow and isolation rules", "examples": [ "team_checkin" ] }, "currentRun": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "run identifier", "examples": [ "d4e5f6a7-b890-1234-cdef-567890123456" ] }, "measureId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "parent measure identifier", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] }, "measureType": { "type": "string", "enum": [ "personal_reflection", "team_checkin" ], "description": "type of connection measure — determines data flow and isolation rules", "examples": [ "team_checkin" ] }, "status": { "type": "string", "enum": [ "scheduled", "open", "scored", "cancelled" ], "description": "run lifecycle state (A3: sealed-run model)", "examples": [ "open" ] }, "period": { "type": "string", "minLength": 1, "description": "period identifier for date stepper navigation (A2)", "examples": [ "2026-04" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "due date; null for scheduled runs", "examples": [ "2026-04-30T23:59:59.000Z" ] }, "participation": { "anyOf": [ { "type": "object", "properties": { "completed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "number of participants who have completed — never names (FR33)", "examples": [ 4 ] }, "total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "total snapshot members", "examples": [ 6 ] } }, "required": [ "completed", "total" ] }, { "type": "null" } ], "description": "participation count; null when scheduled", "examples": [ { "completed": 4, "total": 6 } ] }, "results": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run this result belongs to", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the team this result belongs to", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "dimension score on a 0–100 scale (FR42a)", "examples": [ 72 ] }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "dimension", "score", "banding" ] }, "description": "aggregated scores for all six dimensions; empty array when scoresAvailable is false (Pattern 3 suppression)" }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "overall composite score (FR42a)", "examples": [ 73.8 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for overall score", "examples": [ "MODERATE" ] }, "participantCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "number of participants who completed", "examples": [ 5 ] }, "scoresAvailable": { "type": "boolean", "description": "derived: true when participantCount >= min-group threshold (Pattern 3)", "examples": [ true ] }, "participantsNeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "max(0, threshold - participantCount) — frontend never imports the threshold", "examples": [ 0 ] }, "trendDeltas": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "delta": { "type": "number", "description": "signed difference from prior run score", "examples": [ 4.5 ] }, "priorScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "score from the prior scored run", "examples": [ 67.5 ] } }, "required": [ "dimension", "delta", "priorScore" ] } }, { "type": "null" } ], "description": "trend compared to prior scored run; null for first run", "examples": [ null ] }, "overallTrend": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "delta of the composite overallScore vs the immediately prior scored run, rounded to integer; null when no prior scored run exists. Backend-computed so the FE never re-derives from per-dimension deltas (which only equals the composite delta under uniform weighting).", "examples": [ 3 ] }, "focusArea": { "anyOf": [ { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, { "type": "null" } ], "description": "lowest-scoring dimension (FR48a); null for first run", "examples": [ "cohesion" ] } }, "required": [ "runId", "teamId", "dimensions", "overallScore", "overallBanding", "participantCount", "scoresAvailable", "participantsNeeded", "trendDeltas", "overallTrend", "focusArea" ] }, { "type": "null" } ], "description": "team aggregate results; null when not scored (sealed-run: Pattern 2)" } }, "required": [ "runId", "measureId", "measureType", "status", "period", "dueDate", "participation", "results" ] }, { "type": "null" } ], "description": "the current or most recent run; null if no runs exist" }, "lastScoredRun": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "run identifier", "examples": [ "d4e5f6a7-b890-1234-cdef-567890123456" ] }, "measureId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "parent measure identifier", "examples": [ "c3d4e5f6-a7b8-9012-cdef-123456789012" ] }, "measureType": { "type": "string", "enum": [ "personal_reflection", "team_checkin" ], "description": "type of connection measure — determines data flow and isolation rules", "examples": [ "team_checkin" ] }, "status": { "type": "string", "enum": [ "scheduled", "open", "scored", "cancelled" ], "description": "run lifecycle state (A3: sealed-run model)", "examples": [ "open" ] }, "period": { "type": "string", "minLength": 1, "description": "period identifier for date stepper navigation (A2)", "examples": [ "2026-04" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "due date; null for scheduled runs", "examples": [ "2026-04-30T23:59:59.000Z" ] }, "participation": { "anyOf": [ { "type": "object", "properties": { "completed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "number of participants who have completed — never names (FR33)", "examples": [ 4 ] }, "total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "total snapshot members", "examples": [ 6 ] } }, "required": [ "completed", "total" ] }, { "type": "null" } ], "description": "participation count; null when scheduled", "examples": [ { "completed": 4, "total": 6 } ] }, "results": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run this result belongs to", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the team this result belongs to", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "dimension score on a 0–100 scale (FR42a)", "examples": [ 72 ] }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "dimension", "score", "banding" ] }, "description": "aggregated scores for all six dimensions; empty array when scoresAvailable is false (Pattern 3 suppression)" }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "overall composite score (FR42a)", "examples": [ 73.8 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for overall score", "examples": [ "MODERATE" ] }, "participantCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "number of participants who completed", "examples": [ 5 ] }, "scoresAvailable": { "type": "boolean", "description": "derived: true when participantCount >= min-group threshold (Pattern 3)", "examples": [ true ] }, "participantsNeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "max(0, threshold - participantCount) — frontend never imports the threshold", "examples": [ 0 ] }, "trendDeltas": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "delta": { "type": "number", "description": "signed difference from prior run score", "examples": [ 4.5 ] }, "priorScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "score from the prior scored run", "examples": [ 67.5 ] } }, "required": [ "dimension", "delta", "priorScore" ] } }, { "type": "null" } ], "description": "trend compared to prior scored run; null for first run", "examples": [ null ] }, "overallTrend": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "delta of the composite overallScore vs the immediately prior scored run, rounded to integer; null when no prior scored run exists. Backend-computed so the FE never re-derives from per-dimension deltas (which only equals the composite delta under uniform weighting).", "examples": [ 3 ] }, "focusArea": { "anyOf": [ { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, { "type": "null" } ], "description": "lowest-scoring dimension (FR48a); null for first run", "examples": [ "cohesion" ] } }, "required": [ "runId", "teamId", "dimensions", "overallScore", "overallBanding", "participantCount", "scoresAvailable", "participantsNeeded", "trendDeltas", "overallTrend", "focusArea" ] }, { "type": "null" } ], "description": "team aggregate results; null when not scored (sealed-run: Pattern 2)" } }, "required": [ "runId", "measureId", "measureType", "status", "period", "dueDate", "participation", "results" ] }, { "type": "null" } ], "description": "most recent scored run; null if none exists" }, "latestClosedRunWasInsufficient": { "type": "boolean", "description": "true iff the most recent closed run had <3 scored individual results; false otherwise", "examples": [ false ] } }, "required": [ "measureId", "teamId", "measureType", "currentRun", "lastScoredRun", "latestClosedRunWasInsufficient" ] }, "GettingStartedTrackerResponseDto": { "type": "object", "properties": { "steps": { "minItems": 3, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "assessments", "firstCheckIn", "firstSession" ], "description": "which of the three steps this row represents", "examples": [ "firstCheckIn" ] }, "state": { "type": "string", "enum": [ "locked", "active", "complete" ], "description": "current visual state for the tracker", "examples": [ "active" ] }, "completedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "sub-units satisfied (assessments: members done; firstCheckIn/firstSession: 0 or 1)", "examples": [ 2 ] }, "totalCount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "sub-units required to complete this step (assessments: team-member count; firstCheckIn/firstSession: 1)", "examples": [ 5 ] }, "inProgress": { "description": "open-run summary surfaced on `firstCheckIn` when state==='active' and a `ConnectionMeasureRun` is open", "type": "object", "properties": { "respondedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "count of team members who have submitted a response to the open run" }, "teamSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "total team members eligible to respond to the open run" } }, "required": [ "respondedCount", "teamSize" ] }, "lockReason": { "description": "why this step is locked; only valid on `firstSession` when state==='locked' (THO-1795)", "type": "string", "enum": [ "assessmentsIncomplete", "checkInInProgress" ], "examples": [ "checkInInProgress" ] } }, "required": [ "id", "state", "completedCount", "totalCount" ] }, "description": "exactly three steps in display order: assessments, firstCheckIn, firstSession" }, "allComplete": { "type": "boolean", "description": "server-derived: true iff every step's state === 'complete'; the frontend uses this for FR49c auto-hide", "examples": [ false ] } }, "required": [ "steps", "allComplete" ] }, "GetQuestionnaireResponseDto": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run being loaded", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "measureType": { "type": "string", "enum": [ "personal_reflection", "team_checkin" ], "description": "type of connection measure — determines data flow and isolation rules", "examples": [ "team_checkin" ] }, "status": { "type": "string", "enum": [ "scheduled", "open", "scored", "cancelled" ], "description": "run lifecycle state (A3: sealed-run model)", "examples": [ "open" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "target team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "teamName": { "type": "string", "minLength": 1, "description": "target team name for the FR40 context banner" }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "non-null when the current user has already submitted for this run", "examples": [ null, "2026-04-16T10:30:00.000Z" ] }, "questions": { "minItems": 36, "maxItems": 36, "type": "array", "items": { "type": "object", "properties": { "displayOrdinal": { "type": "integer", "minimum": 1, "maximum": 36, "description": "position in the shuffled display order (1–36)", "examples": [ 1 ] }, "questionOrdinal": { "type": "integer", "minimum": 1, "maximum": 36, "description": "original instrument ordinal — hidden from the user, submitted back as-is (FR39c un-shuffle)", "examples": [ 17 ] }, "text": { "type": "string", "minLength": 1, "description": "question text in the user's locale", "examples": [ "I feel valued by my team." ] } }, "required": [ "displayOrdinal", "questionOrdinal", "text" ] }, "description": "36 questions in shuffled display order; questionOrdinal is the original instrument ordinal (FR39c)" } }, "required": [ "runId", "measureType", "status", "teamId", "teamName", "submittedAt", "questions" ] }, "SubmitQuestionnaireDto": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run being responded to", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "responses": { "minItems": 36, "maxItems": 36, "type": "array", "items": { "type": "object", "properties": { "questionOrdinal": { "type": "integer", "minimum": 1, "maximum": 36, "description": "original question ordinal after un-shuffling (1–36)", "examples": [ 1 ] }, "value": { "type": "integer", "minimum": 1, "maximum": 7, "description": "7-point Likert response (FR39a)", "examples": [ 5 ] } }, "required": [ "questionOrdinal", "value" ] }, "description": "exactly 36 question responses — all-or-nothing submission (FR39d)", "examples": [ [ { "questionOrdinal": 1, "value": 5 }, { "questionOrdinal": 2, "value": 3 } ] ] } }, "required": [ "runId", "responses" ] }, "SubmitQuestionnaireResponseDto": { "type": "object", "properties": { "snapshotMemberId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the snapshot member row", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "submission timestamp", "examples": [ "2026-04-16T10:30:00.000Z" ] }, "individualResult": { "type": "object", "properties": { "snapshotMemberId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "snapshot member who submitted", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run this result belongs to", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "dimensions": { "minItems": 6, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "dimension score on a 0–100 scale (FR42a)", "examples": [ 72 ] }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "dimension", "score", "banding" ] }, "description": "scores for all six dimensions", "examples": [ [ { "dimension": "appreciation", "score": 78, "banding": "MODERATE" }, { "dimension": "belonging", "score": 85, "banding": "HIGH" }, { "dimension": "cohesion", "score": 62, "banding": "LOW" }, { "dimension": "contribution", "score": 71, "banding": "MODERATE" }, { "dimension": "trust", "score": 88, "banding": "HIGH" }, { "dimension": "wellbeing", "score": 74, "banding": "MODERATE" } ] ] }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "overall composite score (FR42a)", "examples": [ 76.3 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for overall score", "examples": [ "MODERATE" ] } }, "required": [ "snapshotMemberId", "runId", "dimensions", "overallScore", "overallBanding" ], "description": "immediate individual results (FR43)" } }, "required": [ "snapshotMemberId", "submittedAt", "individualResult" ] }, "IndividualResultsPageResponseDto": { "type": "object", "properties": { "individualResult": { "type": "object", "properties": { "snapshotMemberId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "snapshot member who submitted", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run this result belongs to", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "dimensions": { "minItems": 6, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "dimension score on a 0–100 scale (FR42a)", "examples": [ 72 ] }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "dimension", "score", "banding" ] }, "description": "scores for all six dimensions", "examples": [ [ { "dimension": "appreciation", "score": 78, "banding": "MODERATE" }, { "dimension": "belonging", "score": 85, "banding": "HIGH" }, { "dimension": "cohesion", "score": 62, "banding": "LOW" }, { "dimension": "contribution", "score": 71, "banding": "MODERATE" }, { "dimension": "trust", "score": 88, "banding": "HIGH" }, { "dimension": "wellbeing", "score": 74, "banding": "MODERATE" } ] ] }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "overall composite score (FR42a)", "examples": [ 76.3 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for overall score", "examples": [ "MODERATE" ] } }, "required": [ "snapshotMemberId", "runId", "dimensions", "overallScore", "overallBanding" ] }, "measureType": { "type": "string", "enum": [ "personal_reflection", "team_checkin" ] }, "teamName": { "type": "string", "description": "team display name" }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team UUID" }, "runPeriod": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "ISO month string (YYYY-MM) for the run period" }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "participant's submission timestamp for the current run" }, "availablePeriods": { "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "description": "all scored run periods for this team + individual, most recent first" }, "availableRuns": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "period", "runId" ] }, "description": "period→runId pairs (same order as availablePeriods) so the date stepper can resolve a chosen period to a runId for navigation" }, "previousResult": { "anyOf": [ { "type": "object", "properties": { "snapshotMemberId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "snapshot member who submitted", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "the run this result belongs to", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "dimensions": { "minItems": 6, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "dimension score on a 0–100 scale (FR42a)", "examples": [ 72 ] }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "dimension", "score", "banding" ] }, "description": "scores for all six dimensions", "examples": [ [ { "dimension": "appreciation", "score": 78, "banding": "MODERATE" }, { "dimension": "belonging", "score": 85, "banding": "HIGH" }, { "dimension": "cohesion", "score": 62, "banding": "LOW" }, { "dimension": "contribution", "score": 71, "banding": "MODERATE" }, { "dimension": "trust", "score": 88, "banding": "HIGH" }, { "dimension": "wellbeing", "score": 74, "banding": "MODERATE" } ] ] }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "overall composite score (FR42a)", "examples": [ 76.3 ] }, "overallBanding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "banding for overall score", "examples": [ "MODERATE" ] } }, "required": [ "snapshotMemberId", "runId", "dimensions", "overallScore", "overallBanding" ] }, { "type": "null" } ], "description": "prior result for trend delta; null if first result" }, "teamVisibility": { "type": "string", "enum": [ "visible", "hidden" ], "description": "Team-private flag (FR46a) — when \"hidden\" the team results cross-link must be suppressed regardless of aggregation availability" }, "teamResultsAvailable": { "type": "boolean", "description": "Server pre-computed gate — true iff team result exists, run is scored, AND participantCount >= CONNECTION_MIN_GROUP_THRESHOLD_DEFAULT" }, "narratives": { "anyOf": [ { "type": "object", "properties": { "overall": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "overall connection narrative; null until the AI-generated summary is available — the client collapses the hero slot on null" }, "dimensions": { "type": "object", "propertyNames": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "additionalProperties": { "type": "string" }, "required": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "per-dimension narrative keyed by dimension name; partial — E5.7 lazy endpoint owns per-dimension values" } }, "required": [ "overall", "dimensions" ] }, { "type": "null" } ], "description": "localised narratives with token replacement; null at MVP" }, "overallScoreHistory": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "period", "score", "banding" ] }, "description": "overall connection scores across the most recent scored runs (oldest → newest; max 6) — drives the desktop hero sparkline; viewed run is located via the sibling runPeriod field (findIndex(p => p.period === runPeriod); -1 means the viewed run sits outside the trailing window and the FE suppresses the filled terminal dot)" }, "dimensionHistory": { "type": "object", "propertyNames": { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, "additionalProperties": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "banding": { "type": "string", "enum": [ "LOW", "MODERATE", "HIGH" ], "description": "score banding classification", "examples": [ "MODERATE" ] } }, "required": [ "period", "score", "banding" ] } }, "required": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "per-dimension connection scores across the most recent scored runs, keyed by dimension (oldest → newest, current last; max 6 per dimension) — drives the desktop dimension-card sparklines" } }, "required": [ "individualResult", "measureType", "teamName", "teamId", "runPeriod", "submittedAt", "availablePeriods", "availableRuns", "previousResult", "teamVisibility", "teamResultsAvailable", "narratives", "overallScoreHistory", "dimensionHistory" ] }, "SessionIntentResponseDto": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "intent identifier", "examples": [ "improve_communication" ] }, "label": { "type": "string", "minLength": 1, "description": "display label", "examples": [ "Improve Communication" ] }, "description": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "intent description; null when there is no genuine description distinct from the label", "examples": [ "Focus on improving team communication patterns" ] }, "dimension": { "anyOf": [ { "type": "string", "enum": [ "appreciation", "belonging", "cohesion", "contribution", "trust", "wellbeing" ], "description": "one of the six connection dimensions", "examples": [ "trust" ] }, { "type": "null" } ], "description": "connection dimension for recommended-intent matching", "examples": [ "cohesion" ] } }, "required": [ "id", "label", "description", "dimension" ] }, "DiscussionItemResponseDto": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "discussion item identifier", "examples": [ "disc-001" ] }, "content": { "type": "string", "minLength": 1, "description": "discussion item content", "examples": [ "What does effective communication look like in our team?" ] }, "topic": { "description": "optional topic grouping", "examples": [ "communication" ], "type": "string" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "display order", "examples": [ 1 ] } }, "required": [ "id", "content", "sortOrder" ] }, "DiveInContentResponseDto": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "content block identifier", "examples": [ "dive-001" ] }, "phaseStep": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "step number within the dive-in phase", "examples": [ 1 ] }, "content": { "type": "string", "minLength": 1, "description": "content for this dive-in step", "examples": [ "Take turns sharing one thing you appreciate about a colleague." ] }, "coachingPlaceholder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "placeholder for the AI coaching integration", "examples": [ null ] } }, "required": [ "id", "phaseStep", "content", "coachingPlaceholder" ] }, "description": "content blocks for the requested phase step (may be empty)" }, "isFinal": { "type": "boolean", "description": "true when this is the last phase step (no content exists for phaseStep+1)" } }, "required": [ "blocks", "isFinal" ] }, "CreateSessionDto": { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "session display name", "examples": [ "Q2 Trust Building" ] }, "intent": { "type": "string", "minLength": 1, "maxLength": 500, "description": "selected session intent", "examples": [ "improve_communication" ] }, "customIntent": { "description": "free-text custom intent when \"other\" is selected", "examples": [ "Discuss Q3 priorities" ], "type": "string", "minLength": 1, "maxLength": 500 }, "durationMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "session duration in minutes", "examples": [ 90 ] }, "scheduledDate": { "description": "optional scheduled date/time for the session", "examples": [ "2026-05-15T14:00:00.000Z" ], "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "discussionItemIds": { "description": "curated discussion items in display order (ontology + custom-question ids)", "examples": [ [ "9f1c1d2c-3a4b-4d5e-8f10-aaaaaaaaaaaa", "custom-7c2d-9b" ] ], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^(custom-[A-Za-z0-9_-]+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "customQuestions": { "description": "content for any custom-question ids in discussionItemIds", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "pattern": "^custom-", "description": "stable client-assigned custom-question id (must match an entry in discussionItemIds)", "examples": [ "custom-7c2d-9b" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 500, "description": "author-supplied question text", "examples": [ "How are we doing on follow-through?" ] } }, "required": [ "id", "content" ] } } }, "required": [ "teamId", "name", "intent", "durationMinutes" ] }, "TeamSessionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "session identifier", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "team identifier", "examples": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "session display name", "examples": [ "Q2 Trust Building" ] }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "discarded" ] }, "intent": { "type": "string", "minLength": 1, "maxLength": 500, "description": "session intent", "examples": [ "improve_communication" ] }, "customIntent": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "custom intent text, null if standard intent used", "examples": [ null ] }, "durationMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "session duration in minutes", "examples": [ 90 ] }, "scheduledDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "scheduled date/time, null if not scheduled", "examples": [ "2026-05-15T14:00:00.000Z" ] }, "keyTakeaways": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "key takeaways captured at session close, null until completed", "examples": [ "We agreed to add a 5-minute pause before big decisions.", null ] }, "actionItems": { "description": "action items associated with this session", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "action item identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "parent session identifier", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "assigneeIndividualId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "individual assigned to this action item; null = team-level (whole team) action", "examples": [ "c3d4e5f6-a7b8-4123-9def-234567890123", null ] }, "text": { "type": "string", "minLength": 1, "description": "action item description", "examples": [ "Schedule 1:1 with each team member" ] }, "completed": { "type": "boolean", "description": "whether the action item has been completed", "examples": [ false ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-05-15T14:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-05-15T14:30:00.000Z" ] } }, "required": [ "id", "sessionId", "assigneeIndividualId", "text", "completed", "createdAt", "updatedAt" ] } }, "reflectDraft": { "description": "mid-session reflect draft; null/absent when none saved or after Complete/Discard", "anyOf": [ { "type": "object", "properties": { "takeaways": { "type": "string", "maxLength": 5000, "description": "saved key-takeaways draft (empty string when none saved yet)", "examples": [ "We agreed to add a 5-minute pause before big decisions." ] }, "actions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500, "description": "queued team-action text", "examples": [ "Block 30 mins on Mondays for a no-meetings focus window." ] }, "suggested": { "type": "boolean", "description": "true when added from a ThomAI suggestion, false for a custom action" }, "suggestionId": { "description": "source suggestion id when suggested=true; carries the \"Added\" tick across reload", "examples": [ "build_trust-1" ], "type": "string", "minLength": 1 } }, "required": [ "text", "suggested" ] }, "description": "queued team actions in display order" } }, "required": [ "takeaways", "actions" ] }, { "type": "null" } ] }, "diveInQuestionTotal": { "description": "total number of dive-in question prompts for this session intent (populated on completed-session reads)", "examples": [ 3 ], "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "discussionItemIds": { "description": "curated discussion items in display order (ontology + custom-question ids)", "type": "array", "items": { "type": "string", "minLength": 1 } }, "customQuestions": { "description": "hydrated content for any custom-question ids", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "stable custom-question id (matches an entry in discussionItemIds)" }, "content": { "type": "string", "minLength": 1, "maxLength": 500, "description": "author-supplied question text" } }, "required": [ "id", "content" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-05-15T14:00:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-05-15T14:00:00.000Z" ] } }, "required": [ "id", "teamId", "name", "status", "intent", "customIntent", "durationMinutes", "scheduledDate", "keyTakeaways", "createdAt", "updatedAt" ] }, "UpdateSessionDto": { "type": "object", "properties": { "name": { "description": "updated session name", "examples": [ "Q2 Trust Building" ], "type": "string", "minLength": 1, "maxLength": 200 }, "intent": { "description": "updated session intent", "examples": [ "build_trust" ], "type": "string", "minLength": 1, "maxLength": 500 }, "customIntent": { "description": "updated custom intent", "examples": [ "Team retrospective" ], "type": "string", "minLength": 1, "maxLength": 500 }, "durationMinutes": { "description": "updated session duration in minutes", "examples": [ 90 ], "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "scheduledDate": { "description": "updated scheduled date/time", "examples": [ "2026-05-20T10:00:00.000Z" ], "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "description": "transition session to a new status", "type": "string", "enum": [ "planned", "in_progress", "completed", "discarded" ] }, "discussionItemIds": { "description": "curated discussion items in display order (ontology + custom-question ids)", "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^(custom-[A-Za-z0-9_-]+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "customQuestions": { "description": "content for any custom-question ids in discussionItemIds", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "pattern": "^custom-", "description": "stable client-assigned custom-question id (must match an entry in discussionItemIds)" }, "content": { "type": "string", "minLength": 1, "maxLength": 500, "description": "author-supplied question text" } }, "required": [ "id", "content" ] } } } }, "CompleteSessionDto": { "type": "object", "properties": { "keyTakeaways": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "description": "free-text takeaways captured by the owner; null clears the field", "examples": [ "We learned how Robert likes pause-time before big decisions." ] }, "actionItems": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500, "description": "action item description", "examples": [ "Block 30 mins on Mondays for a no-meetings focus window." ] }, "assigneeIndividualId": { "type": "null", "description": "must be null — per-individual assignment lands in a future story", "examples": [ null ] } }, "required": [ "text", "assigneeIndividualId" ] }, "description": "action items to persist on session completion (may be empty)" } }, "required": [ "keyTakeaways", "actionItems" ] }, "SaveReflectDraftDto": { "type": "object", "properties": { "takeaways": { "type": "string", "maxLength": 5000, "description": "saved key-takeaways draft (empty string when none saved yet)", "examples": [ "We agreed to add a 5-minute pause before big decisions." ] }, "actions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500, "description": "queued team-action text", "examples": [ "Block 30 mins on Mondays for a no-meetings focus window." ] }, "suggested": { "type": "boolean", "description": "true when added from a ThomAI suggestion, false for a custom action" }, "suggestionId": { "description": "source suggestion id when suggested=true; carries the \"Added\" tick across reload", "examples": [ "build_trust-1" ], "type": "string", "minLength": 1 } }, "required": [ "text", "suggested" ] }, "description": "queued team actions in display order" } }, "required": [ "takeaways", "actions" ] }, "SessionActionItemResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "action item identifier", "examples": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "parent session identifier", "examples": [ "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }, "assigneeIndividualId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "individual assigned to this action item; null = team-level (whole team) action", "examples": [ "c3d4e5f6-a7b8-4123-9def-234567890123", null ] }, "text": { "type": "string", "minLength": 1, "description": "action item description", "examples": [ "Schedule 1:1 with each team member" ] }, "completed": { "type": "boolean", "description": "whether the action item has been completed", "examples": [ false ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "creation timestamp", "examples": [ "2026-05-15T14:30:00.000Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "last update timestamp", "examples": [ "2026-05-15T14:30:00.000Z" ] } }, "required": [ "id", "sessionId", "assigneeIndividualId", "text", "completed", "createdAt", "updatedAt" ] }, "SuggestedActionsResponseDto": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 1, "description": "source intent identifier" }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "stable identifier, unique per intent", "examples": [ "build_trust-1" ] }, "text": { "type": "string", "minLength": 1, "description": "suggested action copy", "examples": [ "Pair team members with different behaviour styles for a sprint." ] }, "intent": { "type": "string", "minLength": 1, "description": "source intent identifier", "examples": [ "build_trust" ] } }, "required": [ "id", "text", "intent" ] } } }, "required": [ "intent", "suggestions" ] }, "FeedListResponseDto": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceEventId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "eventType": { "type": "string", "enum": [ "reciprocal_share_invitation", "dsar_completion", "manager_link_created", "manager_link_removed", "team_membership_added", "team_membership_removed", "direct_report_assessment_complete", "direct_report_measure_complete", "teammate_assessment_complete", "teammate_measure_complete", "self_assessment_complete", "self_measure_complete", "check_in_due", "check_in_reminder", "action_item", "coaching_prompt", "appreciation_received", "connection_measure_deployed", "empty_state_onboarding" ] }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "state": { "type": "string", "enum": [ "pending", "acted", "dismissed", "expired" ] }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "actedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "dismissedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "clusterSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "nullable": true }, "deepLinkListUrl": { "type": "string", "nullable": true }, "subjectDisplayName": { "type": "string", "minLength": 1, "nullable": true }, "subjectCompanyIndividualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "nullable": true }, "responseCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "nullable": true } }, "required": [ "id", "sourceEventId", "eventType", "occurredAt", "state", "payload", "actedAt", "dismissedAt", "clusterSize", "deepLinkListUrl" ], "additionalProperties": false } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false }, "HabitTodayResponseDto": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "item": { "type": "object", "properties": { "itemDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "itemType": { "type": "string", "enum": [ "send_appreciation", "acknowledgement_reflection", "deep_link_to_source" ], "description": "the three rotating daily habit-item types (FR9a)", "examples": [ "acknowledgement_reflection" ] }, "ontologyTemplateId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "payload": { "type": "object", "properties": { "itemType": { "type": "string", "enum": [ "send_appreciation", "acknowledgement_reflection", "deep_link_to_source" ], "description": "the three rotating daily habit-item types (FR9a)", "examples": [ "acknowledgement_reflection" ] }, "ontologyTemplateId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "promptCopy": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string", "minLength": 1 }, "ctaLabel": { "type": "string", "minLength": 1 } }, "required": [ "title", "subtitle", "ctaLabel" ], "additionalProperties": false }, "deepLinkTarget": { "type": "string", "minLength": 1 }, "recipientHint": { "type": "object", "properties": { "individualId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1 }, "companyIndividualId": { "type": "string" }, "photoHash": { "type": "string", "nullable": true } }, "required": [ "individualId", "name" ], "additionalProperties": false } }, "required": [ "itemType", "ontologyTemplateId", "promptCopy" ], "additionalProperties": false }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "dismissedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true } }, "required": [ "itemDate", "itemType", "ontologyTemplateId", "payload", "completedAt", "dismissedAt" ], "additionalProperties": false, "nullable": true }, "streak": { "type": "object", "properties": { "currentStreak": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "longestStreak": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastCompletedDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "nullable": true }, "lastMilestoneAcknowledged": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "nullable": true } }, "required": [ "currentStreak", "longestStreak", "lastCompletedDate", "lastMilestoneAcknowledged" ], "additionalProperties": false, "nullable": true }, "hasCompletedFirstMeasure": { "type": "boolean" } }, "required": [ "enabled", "item", "streak", "hasCompletedFirstMeasure" ], "additionalProperties": false }, "HabitStreakCompleteRequestDto": { "type": "object", "properties": { "messageBody": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "AppreciationSendRequestDto": { "type": "object", "properties": { "recipientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "messageBody": { "type": "string", "minLength": 1 } }, "required": [ "recipientId", "messageBody" ], "additionalProperties": false }, "AppreciationSendResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "sentAt" ], "additionalProperties": false }, "AppreciationReceivedDetailDto": { "type": "object", "properties": { "senderName": { "type": "string", "nullable": true }, "senderAvatarUrl": { "type": "string", "nullable": true }, "messageBody": { "type": "string" }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "canThankBack": { "type": "boolean" } }, "required": [ "senderName", "senderAvatarUrl", "messageBody", "sentAt", "canThankBack" ], "additionalProperties": false }, "OrgKpisResponseDto": { "type": "object", "properties": { "kpis": { "type": "object", "properties": { "assessmentCompletion": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true }, "checkinParticipation": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true }, "teamsActivated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "nullable": true }, "teamsTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "nullable": true }, "deltas": { "type": "object", "properties": { "assessmentDeltaPp": { "type": "number", "nullable": true }, "checkinDeltaPp": { "type": "number", "nullable": true }, "teamsDeltaCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "nullable": true } }, "required": [ "assessmentDeltaPp", "checkinDeltaPp", "teamsDeltaCount" ], "additionalProperties": false, "nullable": true } }, "required": [ "assessmentCompletion", "checkinParticipation", "teamsActivated", "teamsTotal", "deltas" ], "additionalProperties": false }, "asOfDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "nullable": true } }, "required": [ "kpis", "asOfDate" ], "additionalProperties": false }, "ThomAI_PageId": { "type": "string", "enum": [ "individual", "team", "org_analyst", "manager", "home", "unprompted" ] }, "ThomAI_EntryPoint": { "type": "string", "enum": [ "thomai_card", "persistent_button", "thomai_fab", "prompt_card", "input_bar", "unprompted" ] }, "ThomAI_ThomaiErrorCode": { "type": "string", "enum": [ "THOMAI_PERMISSION_DENIED", "THOMAI_LLM_GUARDRAIL_REJECTED", "THOMAI_CTX_SIGNATURE_INVALID", "THOMAI_RATE_LIMITED", "THOMAI_UPSTREAM_TIMEOUT", "THOMAI_VALIDATION_FAILED", "THOMAI_INTERNAL" ] }, "ThomAI_ThomaiErrorEnvelope": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "$ref": "#/components/schemas/ThomAI_ThomaiErrorCode" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } }, "ThomAI_ConversationTurn": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string" }, "messageId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ThomAI_RecentEvent": { "type": "object", "required": [ "type", "id", "occurredAt" ], "properties": { "type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" } } }, "ThomAI_PriorAction": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string" }, "entityId": { "type": "string", "format": "uuid" } } }, "ThomAI_AssistRequestTarget": { "oneOf": [ { "type": "object", "required": [ "kind" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "self" ] } } }, { "type": "object", "required": [ "kind", "individualId" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "individual_id" ] }, "individualId": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "kind", "teamId" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "team_id" ] }, "teamId": { "type": "string", "format": "uuid" } } } ], "discriminator": { "propertyName": "kind" } }, "ThomAI_AssistRequest": { "type": "object", "required": [ "requestId", "clientMessageId", "intent", "entryPoint", "pageId", "pageParams" ], "properties": { "requestId": { "type": "string", "format": "uuid" }, "clientMessageId": { "type": "string", "format": "uuid" }, "intent": { "type": "string", "minLength": 1 }, "entryPoint": { "$ref": "#/components/schemas/ThomAI_EntryPoint" }, "pageId": { "$ref": "#/components/schemas/ThomAI_PageId" }, "pageParams": { "type": "object", "additionalProperties": true }, "target": { "$ref": "#/components/schemas/ThomAI_AssistRequestTarget" }, "recentEvents": { "type": "array", "items": { "$ref": "#/components/schemas/ThomAI_RecentEvent" } }, "priorAction": { "$ref": "#/components/schemas/ThomAI_PriorAction" }, "conversationHistory": { "type": "array", "items": { "$ref": "#/components/schemas/ThomAI_ConversationTurn" } }, "compactedConversation": { "type": "string" } } }, "ThomAI_TeamSessionsQuestionsRequest": { "type": "object", "required": [ "intent", "sessionDirective", "teamId" ], "properties": { "intent": { "type": "string", "minLength": 1 }, "sessionDirective": { "type": "string", "minLength": 1 }, "teamId": { "type": "string", "format": "uuid" } } }, "ThomAI_CompactRequest": { "type": "object", "required": [ "conversationHistory" ], "properties": { "conversationHistory": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ThomAI_ConversationTurn" } } } }, "ThomAI_CompactResponse": { "type": "object", "required": [ "compactedConversation" ], "properties": { "compactedConversation": { "type": "object", "additionalProperties": true } } }, "ThomAI_CardsRequest": { "type": "object", "required": [ "pageId", "pageParams" ], "properties": { "pageId": { "$ref": "#/components/schemas/ThomAI_PageId" }, "pageParams": { "type": "object", "additionalProperties": true } } }, "ThomAI_Card": { "type": "object", "required": [ "id", "kind", "data" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } } }, "ThomAI_CardsResponse": { "type": "object", "required": [ "cards" ], "properties": { "cards": { "type": "array", "items": { "$ref": "#/components/schemas/ThomAI_Card" } } } }, "ThomAI_SseStatusEvent": { "type": "object", "required": [ "kind", "message", "phase" ], "properties": { "kind": { "type": "string", "const": "status" }, "message": { "type": "string" }, "phase": { "type": "string" } } }, "ThomAI_SseMetadataEvent": { "type": "object", "required": [ "kind", "mlflowTraceId", "conversationId", "messageId" ], "properties": { "kind": { "type": "string", "const": "metadata" }, "mlflowTraceId": { "type": "string" }, "conversationId": { "type": "string", "format": "uuid" }, "messageId": { "type": "string", "format": "uuid" }, "explainability": { "type": "array", "items": { "type": "object", "required": [ "kind", "label" ], "properties": { "kind": { "type": "string", "enum": [ "disc", "connection_model" ] }, "label": { "type": "string" } } } }, "eventEmitFailed": { "type": "boolean" } } }, "ThomAI_SseTokenEvent": { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "const": "token" }, "text": { "type": "string" } } }, "ThomAI_SseClarificationRequestEvent": { "type": "object", "required": [ "kind", "question" ], "properties": { "kind": { "type": "string", "const": "clarification_request" }, "question": { "type": "string" }, "suggestedReplies": { "type": "array", "items": { "type": "string" } } } }, "ThomAI_SseStructuredPayloadEvent": { "type": "object", "required": [ "kind", "payloadKind", "data" ], "properties": { "kind": { "type": "string", "const": "structured_payload" }, "payloadKind": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } } }, "ThomAI_SseHeartbeatEvent": { "type": "object", "required": [ "kind", "ts" ], "properties": { "kind": { "type": "string", "const": "heartbeat" }, "ts": { "type": "string", "format": "date-time" } } }, "ThomAI_SseErrorEvent": { "type": "object", "required": [ "kind", "error", "message" ], "properties": { "kind": { "type": "string", "const": "error" }, "error": { "$ref": "#/components/schemas/ThomAI_ThomaiErrorCode" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } }, "ThomAI_SseDoneEvent": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "const": "done" }, "outputTokens": { "type": "integer", "minimum": 0 }, "latencyMs": { "type": "integer", "minimum": 0 } } }, "ThomAI_SseEvent": { "oneOf": [ { "$ref": "#/components/schemas/ThomAI_SseStatusEvent" }, { "$ref": "#/components/schemas/ThomAI_SseMetadataEvent" }, { "$ref": "#/components/schemas/ThomAI_SseTokenEvent" }, { "$ref": "#/components/schemas/ThomAI_SseClarificationRequestEvent" }, { "$ref": "#/components/schemas/ThomAI_SseStructuredPayloadEvent" }, { "$ref": "#/components/schemas/ThomAI_SseHeartbeatEvent" }, { "$ref": "#/components/schemas/ThomAI_SseErrorEvent" }, { "$ref": "#/components/schemas/ThomAI_SseDoneEvent" } ], "discriminator": { "propertyName": "kind", "mapping": { "status": "#/components/schemas/ThomAI_SseStatusEvent", "metadata": "#/components/schemas/ThomAI_SseMetadataEvent", "token": "#/components/schemas/ThomAI_SseTokenEvent", "clarification_request": "#/components/schemas/ThomAI_SseClarificationRequestEvent", "structured_payload": "#/components/schemas/ThomAI_SseStructuredPayloadEvent", "heartbeat": "#/components/schemas/ThomAI_SseHeartbeatEvent", "error": "#/components/schemas/ThomAI_SseErrorEvent", "done": "#/components/schemas/ThomAI_SseDoneEvent" } } } } }, "security": [ { "bearer": [] } ], "x-tagGroups": [ { "name": "Identity & Access", "description": "Authentication, account sessions, first-login onboarding, personal profile and invitations — the access plumbing for every individual.", "tags": [ "Authentication", "Accounts", "Onboarding", "My Profile", "Invitations" ] }, { "name": "People", "description": "The employee population — directory, profiles, administration, roles and the manager/org-structure graph. One population; tags split by what you are doing, not who.", "tags": [ "Colleagues & Profiles", "People Administration", "Roles & Permissions", "Manager Links", "Memberships" ] }, { "name": "Organization", "description": "Company-level profile, branding and analytics. Analytics anticipates the Growth 'Analyse Space'.", "tags": [ "Organization Profile", "Branding", "Organization Analytics" ] }, { "name": "Connection", "description": "The core product — teams, connection measures, runs, questionnaires, 1:1 sessions and the org-level rollup.", "tags": [ "Teams", "Check-ins & Runs", "Questionnaires", "1:1 Sessions", "Session Content", "My Connection", "Organization Connection" ] }, { "name": "Assessments", "description": "Instrument delivery and results. A master group with one tag per instrument — Behaviour today; Personality, EI and Aptitude in a later release.", "tags": [ "Behaviour", "Assignments", "Reports", "Claims", "Personality" ] }, { "name": "Coaching (ThomAI)", "description": "The persistent AI coach — conversations, suggestion cards and team-session question generation.", "tags": [ "AI Coaching", "Coaching Cards", "Team Sessions" ] }, { "name": "Nudges & Recognition", "description": "The engagement layer — peer recognition plus content-ontology-driven prompts, fed by assessment, connection and ThomAI.", "tags": [ "Recognition", "Habits", "Feedback" ] }, { "name": "Notifications", "description": "The in-app activity feed — carries recognition, habit prompts, action items, share invitations and DSAR notices.", "tags": [ "Activity Feed" ] }, { "name": "Privacy & Compliance", "description": "Consent lifecycle, data-subject requests, sharing, visibility, audit and legal documents.", "tags": [ "Consent", "Data Subject Requests", "Sharing", "Profile Visibility", "Manager Visibility", "Audit Log", "Offboarding", "Legal Documents" ] }, { "name": "Partners & Integration", "description": "The partner-facing surface — OAuth client-credentials auth, webhooks and API-triggered assessment delivery. Token issuance ships now; the webhook and delivery surfaces are reserved for a later release.", "tags": [ "Partner Auth", "Partner Tenants", "Partner Diagnostics", "Partner Events & Webhooks", "Partner access governance" ] }, { "name": "Platform", "description": "Operational endpoints — health, feature flags and the platform portal probe.", "tags": [ "Health", "Feature Flags" ] } ] }