{ "openapi": "3.0.0", "info": { "title": "MyEssentials API", "description": "MyEssentials REST API for customer management, policies, claims, and billing. Supports both OAuth2 password grant flow for authentication and Bearer token for API access.", "version": "v1.0.0" }, "servers": [ { "url": "/api", "description": "MyEssentials API Server" }, { "url": "/api/v1" } ], "paths": { "/v1/admin/data/subset": { "post": { "tags": [ "Admin" ], "summary": "Extract data subset", "description": "Queue a data subset extraction job. Samples customers proportionally across years, extracts all related reference and transactional data, anonymizes PII, and writes JSON files to the configured storage disk. Requires admin:full scope (SUPERUSER only).", "operationId": "31eeca5332f8c5da460d0782971e97fa", "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "per_year": { "description": "Customers to sample per year", "type": "integer", "maximum": 1000, "minimum": 1, "example": 100 }, "seed": { "description": "Random seed for reproducible sampling", "type": "integer", "example": 42 }, "skip_anonymize": { "description": "Skip PII anonymization", "type": "boolean", "example": false }, "customers": { "description": "Specific customer IDs to extract", "type": "array", "items": { "type": "integer" } }, "name": { "description": "Directory name for the output", "type": "string", "maxLength": 255, "example": "qa-march" }, "path": { "description": "Custom output path (overrides name)", "type": "string", "maxLength": 500 }, "disk": { "description": "Storage disk (defaults to FILESYSTEM_DISK)", "type": "string", "maxLength": 50, "example": "s3" } }, "type": "object" } } } }, "responses": { "202": { "description": "Extraction job queued", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Job dispatched" }, "data": { "properties": { "job_id": { "type": "string", "format": "uuid", "example": "9e1a3b5c-4d2f-6e7a-8b9c-0d1e2f3a4b5c" }, "type": { "type": "string", "example": "data:subset" }, "queued_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/admin/data/customer-pull": { "post": { "tags": [ "Admin" ], "summary": "Pull specific customers", "description": "Queue a customer pull job for specific customer IDs. Extracts customer-only tables (no reference data), applies ID-based PII masking for predictable debug values, and writes JSON files to the configured storage disk. Requires admin:full scope (SUPERUSER only).", "operationId": "9697b91ba205195acc5f5a754ee37c9e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids" ], "properties": { "ids": { "description": "Customer IDs to pull", "type": "array", "items": { "type": "integer" }, "example": [ 12345, 67890 ] }, "name": { "description": "Directory name for the output", "type": "string", "maxLength": 255, "example": "ticket-123" }, "path": { "description": "Custom output path (overrides name)", "type": "string", "maxLength": 500 }, "disk": { "description": "Storage disk (defaults to FILESYSTEM_DISK)", "type": "string", "maxLength": 50, "example": "s3" } }, "type": "object" } } } }, "responses": { "202": { "description": "Customer pull job queued", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Job dispatched" }, "data": { "properties": { "job_id": { "type": "string", "format": "uuid", "example": "9e1a3b5c-4d2f-6e7a-8b9c-0d1e2f3a4b5c" }, "type": { "type": "string", "example": "data:customer-pull" }, "queued_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/admin/data/import": { "post": { "tags": [ "Admin" ], "summary": "Import data subset", "description": "Queue a data subset import job. Imports previously extracted JSON files into the database. Supports fresh mode (migrate:fresh before import) and optional test user seeding. Blocked in production. Requires admin:full scope (SUPERUSER only).", "operationId": "92e291780e58dc7aad1533d6be9d4934", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "description": "Directory name to import (searches data-subsets/ and customer-pulls/)", "type": "string", "maxLength": 255, "example": "qa-march" }, "path": { "description": "Full path to import directory (alternative to name)", "type": "string", "maxLength": 500 }, "fresh": { "description": "Run migrate:fresh before importing", "type": "boolean", "example": false }, "skip_test_users": { "description": "Skip seeding test user accounts", "type": "boolean", "example": false }, "disk": { "description": "Storage disk (defaults to FILESYSTEM_DISK)", "type": "string", "maxLength": 50, "example": "s3" } }, "type": "object" } } } }, "responses": { "202": { "description": "Import job queued", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Job dispatched" }, "data": { "properties": { "job_id": { "type": "string", "format": "uuid", "example": "9e1a3b5c-4d2f-6e7a-8b9c-0d1e2f3a4b5c" }, "type": { "type": "string", "example": "data:subset-import" }, "queued_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "Forbidden — blocked in production or insufficient permissions", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Data import is not allowed in production" } }, "type": "object" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/admin/data/jobs/{id}": { "get": { "tags": [ "Admin" ], "summary": "Get job status", "description": "Check the status of a data subset job (extract, customer pull, or import). Returns status, timing, output on completion, or error on failure. Requires admin:full scope (SUPERUSER only).", "operationId": "d56219668c4890e66c4ad92b582fd73a", "parameters": [ { "$ref": "#/components/parameters/UuidPath" } ], "responses": { "200": { "description": "Job status retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Success" }, "data": { "properties": { "job": { "properties": { "id": { "type": "string", "format": "uuid", "example": "9e1a3b5c-4d2f-6e7a-8b9c-0d1e2f3a4b5c" }, "type": { "type": "string", "example": "data:subset" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ], "example": "completed" }, "result": { "description": "Structured result data set by the job", "type": "object", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "output": { "description": "Command output (only when completed)", "type": "string", "nullable": true }, "error": { "description": "Error message (only when failed)", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/auth/heartbeat": { "post": { "tags": [ "Authentication" ], "summary": "Session heartbeat with optional token refresh", "description": "Report client activity and optionally refresh the access token if it is near expiry. Extends the refresh token lifetime (sliding window) when the user is active.", "operationId": "88472c19e777e117cb35bb53fb198003", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "refresh_token" ], "properties": { "refresh_token": { "description": "Current refresh token", "type": "string" }, "active": { "description": "Whether the user is actively interacting", "type": "boolean", "example": true }, "access_token_expires_at": { "description": "Unix timestamp when the current access token expires", "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Heartbeat acknowledged, session status returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "oauth2": [] } ] } }, "/v1/admin/ip-whitelist": { "get": { "tags": [ "Admin" ], "summary": "List IP whitelist entries", "description": "Retrieve all IP whitelist entries. Whitelisted IPs bypass rate limiting. Requires admin:full scope (SUPERUSER only).", "operationId": "e07449366c3936163925a0def2902241", "responses": { "200": { "description": "IP whitelist retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "IP whitelist retrieved" }, "data": { "properties": { "entries": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "ip_address": { "type": "string", "example": "192.168.1.0/24" }, "description": { "type": "string", "example": "Office network", "nullable": true }, "added_by": { "type": "string", "example": "1" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Admin" ], "summary": "Add IP to whitelist", "description": "Add an IP address or CIDR range to the rate-limit whitelist. Requires admin:full scope (SUPERUSER only).", "operationId": "8e37a5157351dcec24292e87cff0ab39", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ip_address" ], "properties": { "ip_address": { "description": "IPv4, IPv6, or CIDR notation", "type": "string", "example": "10.0.0.1" }, "description": { "type": "string", "maxLength": 255, "example": "VPN endpoint", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "IP address added to whitelist", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "IP address added to whitelist" }, "data": { "properties": { "entry": { "properties": { "id": { "type": "integer", "example": 1 }, "ip_address": { "type": "string", "example": "10.0.0.1" }, "description": { "type": "string", "example": "VPN endpoint", "nullable": true }, "added_by": { "type": "string", "example": "1" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/admin/ip-whitelist/{id}": { "delete": { "tags": [ "Admin" ], "summary": "Remove IP from whitelist", "description": "Delete an IP whitelist entry. Requires admin:full scope (SUPERUSER only).", "operationId": "3c6a257e3911fda3b2d08e5ed867e029", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "IP whitelist entry removed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "IP whitelist entry removed" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Authenticate user and obtain access tokens", "description": "Authenticate a user or customer using credentials. Returns access + refresh tokens on success, or an MFA challenge if two-factor is enabled. Requires OAuth client credentials via the oauth.client middleware.", "operationId": "a737ffa1c8ed11fa01dc02774b1ebb03", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequestBody" } } } }, "responses": { "200": { "description": "Authentication successful or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "oauth2": [] } ] } }, "/v1/auth/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout and revoke tokens", "description": "Revoke all tokens for the authenticated user and invalidate the session.", "operationId": "00143a51e18a6ca12b47c9c38218fdd2", "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "refresh_token": { "description": "Optional refresh token to revoke explicitly", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfully logged out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/auth/mfa/recovery-codes": { "get": { "tags": [ "Authentication" ], "summary": "List MFA recovery codes", "description": "Retrieve the current set of MFA recovery codes for the authenticated user.", "operationId": "f60b09d4e33f668cab7aab8fd08fdc9c", "responses": { "200": { "description": "Recovery codes retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Recovery codes retrieved" }, "data": { "properties": { "recovery_codes": { "type": "array", "items": { "type": "string" }, "example": [ "ABCD-1234", "EFGH-5678" ] }, "count": { "type": "integer", "example": 8 } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/auth/mfa/recovery-codes/regenerate": { "post": { "tags": [ "Authentication" ], "summary": "Regenerate MFA recovery codes", "description": "Generate a new set of recovery codes, invalidating all previous codes.", "operationId": "23c6bf9d5b98d7445155c05323b5d524", "responses": { "200": { "description": "Recovery codes regenerated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Recovery codes regenerated" }, "data": { "properties": { "recovery_codes": { "type": "array", "items": { "type": "string" }, "example": [ "WXYZ-9012", "MNOP-3456" ] }, "count": { "type": "integer", "example": 8 } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/auth/mfa/verify": { "post": { "tags": [ "Authentication" ], "summary": "Verify MFA code and complete authentication", "description": "Submit a TOTP code or recovery code to complete multi-factor authentication. Returns access + refresh tokens on success. Optionally trust the device to bypass MFA on future logins.", "operationId": "9f3a877834c9fcb70d9ef17976a1aff4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "mfa_token" ], "properties": { "mfa_token": { "description": "MFA session token from login response", "type": "string" }, "code": { "description": "Six-digit TOTP code", "type": "string", "maxLength": 6, "minLength": 6, "example": "123456" }, "recovery_code": { "description": "Recovery code (alternative to TOTP code)", "type": "string", "nullable": true }, "trust_device": { "description": "Trust this device for future logins", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "MFA verification successful, tokens issued", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "MFA verification successful" }, "authorization": { "$ref": "#/components/schemas/AuthorizationToken" }, "data": { "properties": { "mfa_verified": { "type": "boolean", "example": true }, "method": { "type": "string", "enum": [ "totp", "recovery_code" ], "example": "totp" }, "trusted_device": { "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "oauth2": [] } ] } }, "/v1/auth/password/reset": { "post": { "tags": [ "Authentication" ], "summary": "Request a password reset link", "description": "Send a password reset link to the specified email address. Returns the same success message regardless of whether the email exists (prevents email enumeration).", "operationId": "283296972b427953d31422f62b96109a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reset link sent (if account exists)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "If an account exists with that email, a password reset link has been sent." } }, "type": "object" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "oauth2": [] } ] } }, "/v1/auth/password/update": { "post": { "tags": [ "Authentication" ], "summary": "Reset password with token", "description": "Update the user password using a valid reset token. Password must contain uppercase, lowercase, number, and special character.", "operationId": "841c5d478ab7b75c9c9e9dd2a1d267f9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "token", "email", "password", "password_confirmation" ], "properties": { "token": { "description": "Password reset token from email link", "type": "string" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "description": "Must include uppercase, lowercase, number, and special character", "type": "string", "format": "password", "minLength": 8 }, "password_confirmation": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Password updated successfully." } }, "type": "object" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "oauth2": [] } ] } }, "/v1/permissions": { "get": { "tags": [ "Permissions" ], "summary": "List permissions", "description": "List all available V6 permissions grouped by category. Supports optional filtering by category and free-text search on name or display name.", "operationId": "fa0624032b8e6a4c0800e5ea400c13aa", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Permissions retrieved successfully" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/admin/rate-limit-blocks": { "get": { "tags": [ "Admin" ], "summary": "List active rate limit blocks", "description": "Retrieve all active rate limit blocks. Optionally filter by identifier or type. Requires admin:full scope (SUPERUSER only).", "operationId": "f429484fd0a08f3849eab8ddb9901d52", "parameters": [ { "name": "identifier", "in": "query", "description": "Filter by blocked identifier (email, IP)", "required": false, "schema": { "type": "string" } }, { "name": "identifier_type", "in": "query", "description": "Filter by identifier type", "required": false, "schema": { "type": "string", "enum": [ "email", "ip", "composite" ] } } ], "responses": { "200": { "description": "Active rate limit blocks retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Active rate limit blocks retrieved" }, "data": { "properties": { "blocks": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "identifier": { "type": "string", "example": "user@example.com" }, "identifier_type": { "type": "string", "example": "email" }, "block_level": { "type": "string", "enum": [ "soft", "hard", "permanent" ], "example": "soft" }, "blocked_until": { "type": "string", "format": "date-time", "nullable": true }, "reason": { "type": "string", "example": "Too many failed login attempts" }, "attempts": { "type": "integer", "example": 5 }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/admin/rate-limit-blocks/{id}": { "delete": { "tags": [ "Admin" ], "summary": "Clear a rate limit block", "description": "Manually resolve an active rate limit block. Requires admin:full scope (SUPERUSER only).", "operationId": "d9c84affb61b085716aff931d4382d4f", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Rate limit block cleared", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Rate limit block cleared" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/auth/refresh": { "post": { "tags": [ "Authentication" ], "summary": "Refresh an access token", "description": "Exchange a valid refresh token for a new access token. The refresh token is not rotated.", "operationId": "0b09c10e455a783d0e5b2e4161689355", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "refresh_token" ], "properties": { "refresh_token": { "description": "The refresh token from login", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "oauth2": [] } ] } }, "/v1/roles": { "get": { "tags": [ "Roles" ], "summary": "List roles", "description": "List all system-defined roles with their permission counts. Requires the user.view permission.", "operationId": "a448629036e949218119a4c226cba154", "responses": { "200": { "description": "Roles retrieved successfully" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/auth/token": { "post": { "tags": [ "Authentication" ], "summary": "OAuth2 password grant (tooling)", "description": "Standard OAuth2 password grant endpoint for tooling (Swagger UI, OWASP ZAP, Postman). Accepts form-encoded or JSON credentials and returns a standard OAuth2 token response. Bypasses MFA — use /v1/auth/login for interactive authentication with MFA support.", "operationId": "585c908e2fdace88de8d90b8d426171f", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "grant_type", "username", "password" ], "properties": { "grant_type": { "type": "string", "enum": [ "password" ], "example": "password" }, "username": { "description": "User email address", "type": "string", "example": "admin@example.com" }, "password": { "description": "User password", "type": "string", "format": "password", "example": "SecurePass1!" } }, "type": "object" } } } }, "responses": { "200": { "description": "Token issued successfully", "content": { "application/json": { "schema": { "properties": { "access_token": { "description": "JWT access token", "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "description": "Seconds until access token expires", "type": "integer", "example": 3600 }, "refresh_token": { "description": "JWT refresh token", "type": "string" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "oauth2": [] } ] } }, "/v1/customers/{id}/addresses": { "get": { "tags": [ "Customers" ], "summary": "Get customer addresses", "description": "Retrieve all addresses associated with a customer, including shipping, billing, and physical addresses.", "operationId": "8c02fa41a2b125b170b6c60b94c7e55e", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Addresses retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/customers/{id}/claims": { "get": { "tags": [ "Customers" ], "summary": "Get customer insurance claims", "description": "Retrieve all insurance claims for a customer, grouped by status (approved, pending, denied). Includes claim details, policy information, hearing aid details, and a summary with counts.", "operationId": "818719d568dad2e6627743163c499c6c", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Claims retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerClaimsResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get customer details", "description": "Retrieve full customer information including personal data, contact information, billing preferences, addresses, and vendor associations (store, franchise, group).", "operationId": "cacda085b8ec9213a1831408608cb95c", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Customer details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Customers" ], "summary": "Update a customer", "description": "Update an existing customer record by ID.", "operationId": "9e9b55d052286aaefd4cc7980eb91fa7", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequestBody" } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/customers": { "post": { "tags": [ "Customers" ], "summary": "Create a customer", "description": "Create a new customer record within the authenticated tenant.", "operationId": "03d494655b1d4c7b47f6d26d498730e9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequestBody" } } } }, "responses": { "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/customers/{id}/notes": { "get": { "tags": [ "Customers" ], "summary": "Get customer notes", "description": "Retrieve all notes for a customer, sorted by creation date (newest first). Includes full note content, author information, and HTML summary (truncated to 300 characters).", "operationId": "867c7d494465533d321439658048871e", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Notes retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Success" }, "data": { "properties": { "notes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerNote" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Customers" ], "summary": "Create a customer note", "description": "Create a new note for a customer. HTML content is sanitized to prevent XSS attacks. Only allows formatting from editor toolbar: Bold, Italic, Link, Ordered List, Bullet List.", "operationId": "3f7f3f9312ba84b7c62d695cf6e15df6", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNoteRequest" } } } }, "responses": { "201": { "description": "Note created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "Created" }, "message": { "type": "string", "example": "Note created successfully" }, "data": { "properties": { "note": { "$ref": "#/components/schemas/CustomerNote" } }, "type": "object" } }, "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/customers/{id}/payments": { "get": { "tags": [ "Customers" ], "summary": "Get customer payment history", "description": "Retrieve customer invoices grouped by status (past_due, paid, failed, upcoming, negated) with payment information, line items, and totals. Includes a summary with counts and financial totals.", "operationId": "d3d9ad7a20ff1a3811c016935d910a46", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Payment history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPaymentsResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/customers/{id}/policies": { "get": { "tags": [ "Customers" ], "summary": "Get customer policies", "description": "Retrieve all insurance policies for a customer, including hearing aid information, plan details, and renewal status. Policies are sorted by start date (newest first) and include a summary with counts.", "operationId": "acb6b1d564ec9b33eceacdae9964797f", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Policies retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPoliciesData" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/customers/{id}/vendors": { "get": { "tags": [ "Customers" ], "summary": "Get customer vendor associations", "description": "Retrieve the store, franchise, and group associations for a customer. Currently assumes one store/franchise/group relationship per customer.", "operationId": "6a4613e04ea8795aa3865f1b585a0397", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Vendor associations retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerVendorsData" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/queues/status": { "get": { "tags": [ "Queues" ], "summary": "Get queue status counts", "description": "Retrieve pending counts for various queue items: battery requests, referral requests, refunds, and insurance claims. Used for dashboard notifications and queue management.", "operationId": "da9530608e146035e01d30e5ada32939", "responses": { "200": { "description": "Queue status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/users": { "get": { "tags": [ "Users" ], "summary": "List users", "description": "List users with support for filtering by role, status, organization, and free-text search. Results are paginated and sorted. Global-scoped users see all users; organization-scoped users see only users within their franchise hierarchy.", "operationId": "3d345a750d961acf1d32ea30227ba10f", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "superuser", "csr", "organization_owner", "organization_manager", "fulfillment", "staff" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "deactivated" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "organization_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "email", "first_name", "last_name" ] } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "include", "in": "query", "description": "Comma-separated relations to include (organizations)", "required": false, "schema": { "type": "string", "example": "organizations" } } ], "responses": { "200": { "description": "Users retrieved successfully" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Users" ], "summary": "Create a new user", "description": "Create a new user account with the specified roles. Requires the user.create permission.", "operationId": "78430bc03bfb53e69de94ffaa6a1af07", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequestBody" } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreatedResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Get user by ID", "description": "Retrieve detailed user information by ID. Requires the user.view permission, except when a user requests their own record (self-view). Response fields are filtered by the requesting user's role. Use the include query parameter to eager-load relations.", "operationId": "b137f6f6cd9d5724f17a7cb69036c988", "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "include", "in": "query", "description": "Comma-separated relations to include (roles, permissions, organizations)", "required": false, "schema": { "type": "string", "example": "roles,permissions,organizations" } } ], "responses": { "200": { "description": "User retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Users" ], "summary": "Update user", "description": "Update user profile fields. Self-editing users may update their own name and email without the user.edit permission. Only SUPERUSER may set the email_verified flag.", "operationId": "38306bd4d388fbac8b9d1d22ce3b61cb", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequestBody" } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Deactivate user", "description": "Soft-delete a user by setting deactivated_at. Revokes all OAuth tokens, removes organization assignments, and invalidates cached permissions. Self-deactivation is not allowed.", "operationId": "47e3e56349800317d2dc4c5f62afe23d", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string", "maxLength": 500, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "User deactivated successfully" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/users/{id}/permissions": { "get": { "tags": [ "Users" ], "summary": "Get user permissions", "description": "Retrieve effective permissions for a user, grouped by source (via_roles, direct, all). Each permission includes its scope (global, own, organization). Requires the user.security permission, except when a user requests their own permissions (self-view).", "operationId": "56c9a4c6c1214004bd9734b2ca9d4cec", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "User permissions retrieved successfully" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/users/{id}/roles": { "get": { "tags": [ "Users" ], "summary": "Get user roles", "description": "Retrieve the roles assigned to a user. Requires the user.view permission, except when a user requests their own roles (self-view).", "operationId": "40a8b52776703f0b21496bc3aa60644e", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "User roles retrieved successfully" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Users" ], "summary": "Sync user roles", "description": "Replace all roles assigned to a user. Requires the role.manage permission. Records role change history and invalidates the user's permission cache.", "operationId": "439a4a9a8d7adc7743d10831011b25d1", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "roles" ], "properties": { "roles": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Roles updated successfully" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "AuthorizationResponseSuccess": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Authorized" }, "authorization": { "properties": { "token": { "type": "string", "example": "101|WFLyoQNk65w58PLj8yB..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_at": { "type": "integer", "example": 3600 } }, "type": "object" }, "resources": { "properties": { "user": { "properties": { "id": { "type": "integer", "example": 13 }, "guard": { "description": "Guard used for authentication", "type": "string", "example": "customer" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "AuthorizationResponseNotAuthorized": { "properties": { "message": { "type": "string", "example": "Invalid Credentials" } }, "type": "object" }, "ApiEnvelope": { "required": [ "status", "message", "meta" ], "properties": { "status": { "description": "Standard API response envelope for success responses.\n\nMirrors ApiResponse::buildHttpResponseData() output.", "type": "string", "example": "success" }, "message": { "type": "string", "example": "Success" }, "data": { "description": "Response payload — shape varies by endpoint", "type": "object" }, "meta": { "properties": { "alerts": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "authorization": { "oneOf": [ { "$ref": "#/components/schemas/AuthorizationToken" } ], "nullable": true, "description": "Present only when a new or refreshed token is issued" } }, "type": "object" }, "AuthorizationToken": { "properties": { "token": { "description": "Bearer access token", "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_at": { "description": "Token expiration in seconds", "type": "integer" } }, "type": "object" }, "Address": { "properties": { "id": { "description": "Customer address.", "type": "integer", "example": 456 }, "name": { "type": "string", "example": "Home", "nullable": true }, "type": { "type": "string", "enum": [ "Shipping", "Billing", "Physical" ], "example": "Shipping" }, "street_1": { "type": "string", "example": "123 Main St" }, "street_2": { "type": "string", "example": "Apt 4B", "nullable": true }, "city": { "type": "string", "example": "Anytown" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "12345" }, "country": { "type": "string", "example": "US" } }, "type": "object" }, "CrmData": { "properties": { "id": { "description": "CRM system ID (Sycle or legacy CRM)", "type": "string", "example": "S123456" }, "type": { "type": "string", "example": "Sycle", "nullable": true } }, "type": "object" }, "CustomerAddressListResponse": { "required": [ "status", "message", "data" ], "properties": { "status": { "description": "Response shape for GET /v1/customers/{id}/addresses.", "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Success" }, "data": { "required": [ "addresses" ], "properties": { "addresses": { "type": "array", "items": { "required": [ "id", "type", "street_1", "city", "state", "zip", "country" ], "properties": { "id": { "description": "Address ID", "type": "integer", "example": 456 }, "name": { "description": "Address label/name", "type": "string", "example": "Home", "nullable": true }, "type": { "description": "Address type", "type": "string", "enum": [ "Shipping", "Billing", "Physical" ], "example": "Shipping" }, "street_1": { "description": "Street address line 1", "type": "string", "example": "123 Main St" }, "street_2": { "description": "Street address line 2", "type": "string", "example": "Apt 4B", "nullable": true }, "city": { "description": "City", "type": "string", "example": "Anytown" }, "state": { "description": "State/Province", "type": "string", "example": "CA" }, "zip": { "description": "Postal/ZIP code", "type": "string", "example": "12345" }, "country": { "description": "Country code", "type": "string", "example": "US" } }, "type": "object" } } }, "type": "object" } }, "type": "object" }, "CustomerBilling": { "properties": { "id": { "description": "Billing ID", "type": "string", "example": "B123456" }, "billing_date": { "type": "string", "format": "date", "example": "2020-01-15" }, "day": { "type": "integer", "example": 15 }, "month": { "type": "integer", "example": 1 }, "month_name": { "type": "string", "example": "January" }, "interval": { "type": "string", "enum": [ "Monthly", "Quarterly", "Annually" ], "example": "Monthly" } }, "type": "object" }, "CustomerClaimsResponse": { "required": [ "status", "message", "data" ], "properties": { "status": { "description": "Response shape for GET /v1/customers/{id}/claims.", "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Success" }, "data": { "required": [ "approved", "pending", "denied", "summary" ], "properties": { "approved": { "description": "Approved claims", "type": "array", "items": { "type": "object" } }, "pending": { "description": "Pending review claims", "type": "array", "items": { "type": "object" } }, "denied": { "description": "Denied claims", "type": "array", "items": { "type": "object" } }, "summary": { "description": "Claim statistics and counts", "required": [ "approved_count", "pending_count", "denied_count", "total_count" ], "properties": { "approved_count": { "type": "integer", "example": 3 }, "pending_count": { "type": "integer", "example": 2 }, "denied_count": { "type": "integer", "example": 1 }, "total_count": { "type": "integer", "example": 6 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "CustomerContact": { "properties": { "email": { "description": "Customer contact information.", "type": "string", "format": "email", "example": "john.doe@example.com" }, "phone": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPhone" } } }, "type": "object" }, "CustomerName": { "properties": { "first_name": { "description": "Customer name object.", "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "full_name": { "type": "string", "example": "John Doe" } }, "type": "object" }, "CustomerNote": { "properties": { "id": { "description": "Note ID", "type": "integer", "example": 789 }, "summary": { "description": "HTML content truncated to 300 characters", "type": "string", "example": "

Customer called about billing...

" }, "note": { "description": "Full HTML note content", "type": "string", "example": "

Customer called about billing issue. Resolved by adjusting due date.

" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-01-15T10:30:00.000000Z" }, "editable": { "description": "Whether current user can edit note", "type": "boolean", "example": false }, "author": { "properties": { "id": { "description": "Author user ID", "type": "integer", "example": 456 }, "name": { "description": "Author full name", "type": "string", "example": "Jane Smith" }, "email": { "description": "Author email", "type": "string", "format": "email", "example": "jane.smith@example.com" } }, "type": "object" } }, "type": "object" }, "CustomerPaymentsResponse": { "required": [ "status", "message", "data" ], "properties": { "status": { "description": "Response shape for GET /v1/customers/{id}/payments.", "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Success" }, "data": { "required": [ "past_due", "paid", "failed", "upcoming", "negated", "summary" ], "properties": { "past_due": { "description": "Overdue invoices", "type": "array", "items": { "type": "object" } }, "paid": { "description": "Paid invoices", "type": "array", "items": { "type": "object" } }, "failed": { "description": "Failed payment invoices", "type": "array", "items": { "type": "object" } }, "upcoming": { "description": "Future due invoices", "type": "array", "items": { "type": "object" } }, "negated": { "description": "Negated/voided invoices", "type": "array", "items": { "type": "object" } }, "summary": { "description": "Payment statistics and totals", "required": [ "past_due_count", "paid_count", "upcoming_count", "failed_count", "voids_count", "total_past_due", "total_upcoming" ], "properties": { "past_due_count": { "type": "integer", "example": 1 }, "paid_count": { "type": "integer", "example": 10 }, "upcoming_count": { "type": "integer", "example": 2 }, "failed_count": { "type": "integer", "example": 0 }, "voids_count": { "type": "integer", "example": 0 }, "total_past_due": { "description": "Formatted money amount", "type": "string", "example": "$50.00" }, "total_upcoming": { "description": "Formatted money amount", "type": "string", "example": "$100.00" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "CustomerPhone": { "properties": { "phone": { "description": "Customer phone entry.", "type": "string", "example": "(555) 123-4567" }, "type": { "type": "string", "enum": [ "Primary", "Secondary" ], "example": "Primary" } }, "type": "object" }, "CustomerPoliciesData": { "properties": { "policies": { "description": "Array of policy objects with hearing aid and plan details", "type": "array", "items": { "properties": { "id": { "description": "Response shape for GET /v1/customers/{id}/policies.", "type": "integer", "example": 1 }, "policy_number": { "type": "string", "example": "42.2" }, "policy_start_date": { "type": "string", "format": "date-time" }, "policy_end_date": { "type": "string", "format": "date-time" }, "active": { "type": "boolean", "example": true }, "cancelled": { "type": "boolean", "example": false }, "cancelled_on": { "type": "string", "format": "date-time", "nullable": true }, "renews": { "description": "Renewal info object or false", "oneOf": [ { "properties": { "renewal_date": { "type": "string", "format": "date-time" } }, "type": "object" }, { "type": "boolean", "enum": [ false ] } ] }, "insured": { "properties": { "id": { "type": "integer", "example": 10 }, "type": { "type": "string", "example": "hearing_aid" }, "attributes": { "properties": { "side": { "type": "string", "example": "left" }, "serial_number": { "type": "string", "example": "SN123456" }, "model": { "type": "string", "example": "Oticon More 1" }, "manufacturer": { "type": "string", "nullable": true }, "delivery_date": { "type": "string", "format": "date" }, "mfg_warranty_end_date": { "type": "string", "format": "date", "nullable": true }, "battery_type": { "type": "string", "example": "312", "nullable": true }, "AudioTone": { "type": "boolean" }, "foundation": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "plan": { "properties": { "program_name": { "type": "string", "nullable": true }, "name": { "type": "string", "example": "Gold Plan" }, "display_name": { "type": "string", "example": "Gold" }, "id": { "type": "integer", "example": 5 }, "type": { "type": "string", "example": "extended_warranty" } }, "type": "object" } }, "type": "object" } }, "summary": { "properties": { "total_count": { "description": "Total number of policies", "type": "integer", "example": 5 }, "active_count": { "description": "Number of active policies", "type": "integer", "example": 2 }, "past_count": { "description": "Number of expired policies", "type": "integer", "example": 2 }, "cancelled_count": { "description": "Number of cancelled policies", "type": "integer", "example": 1 } }, "type": "object" }, "customer": { "description": "Customer data object", "type": "object" } }, "type": "object" }, "CustomerResponse": { "required": [ "status", "message", "data" ], "properties": { "status": { "description": "Response shape for GET /v1/customers/{id}.", "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Success" }, "data": { "required": [ "customer" ], "properties": { "customer": { "properties": { "id": { "type": "integer", "example": 123 }, "date_of_birth": { "type": "string", "format": "date", "example": "1965-05-15" }, "gender": { "type": "string", "enum": [ "Male", "Female" ], "example": "Male" }, "created_at": { "type": "string", "format": "date-time", "example": "2020-01-15T10:30:00.000000Z" }, "deactivated_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "suspended_at": { "description": "If null, customer is active", "type": "string", "format": "date-time", "example": null, "nullable": true }, "billing": { "$ref": "#/components/schemas/CustomerBilling" }, "name": { "$ref": "#/components/schemas/CustomerName" }, "contact": { "$ref": "#/components/schemas/CustomerContact" }, "CRM_data": { "$ref": "#/components/schemas/CrmData" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "vendors": { "description": "Store, franchise, and group associations", "type": "array", "items": { "$ref": "#/components/schemas/Vendor" } } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "CustomerVendorsData": { "properties": { "vendors": { "type": "array", "items": { "properties": { "group_name": { "description": "Parent group name", "type": "string", "example": "Hearing Solutions Group" }, "stores": { "type": "array", "items": { "properties": { "name": { "description": "Store location name", "type": "string", "example": "Downtown Location" }, "id": { "description": "Store database ID", "type": "integer", "example": 789 }, "store_id": { "description": "Store custom identifier", "type": "string", "example": "S001" }, "phone_number": { "description": "Store phone number", "type": "string", "example": "(555) 987-6543" } }, "type": "object" } }, "franchises": { "type": "array", "items": { "properties": { "name": { "description": "Franchise name", "type": "string", "example": "West Coast Franchise" }, "id": { "description": "Franchise database ID", "type": "integer", "example": 101 }, "franchise_id": { "description": "Franchise custom identifier", "type": "string", "example": "F001" }, "contact": { "properties": { "name": { "description": "Primary contact full name", "type": "string", "example": "Bob Johnson" }, "email": { "description": "Primary contact email", "type": "string", "format": "email", "example": "franchise@example.com" }, "phone_number": { "description": "Primary contact phone", "type": "string", "example": "(555) 555-1234" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" }, "FranchiseContact": { "properties": { "name": { "description": "Franchise contact information.", "type": "string", "example": "Bob Johnson" }, "email": { "type": "string", "format": "email", "example": "franchise@example.com" }, "phone_number": { "type": "string", "example": "(555) 555-1234" } }, "type": "object" }, "Franchise": { "properties": { "name": { "description": "Franchise within a vendor group.", "type": "string", "example": "West Coast Franchise" }, "id": { "type": "integer", "example": 101 }, "franchise_id": { "type": "string", "example": "F001" }, "contact": { "$ref": "#/components/schemas/FranchiseContact" } }, "type": "object" }, "HeartbeatResponse": { "properties": { "status": { "description": "Response shape for POST /v1/auth/heartbeat.", "type": "string", "example": "success" }, "message": { "type": "string", "example": "Token extended" }, "authorization": { "description": "Only present if new access token was created (proactive refresh)", "properties": { "token": { "type": "string", "example": "Bearer eyJ0eXAiOiJKV1Qi..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 900 } }, "type": "object", "nullable": true }, "data": { "properties": { "token_info": { "properties": { "expires_at": { "description": "ISO 8601 timestamp", "type": "string", "example": "2025-01-17T12:37:00.000000Z" }, "expires_in_seconds": { "type": "integer", "example": 420 } }, "type": "object" }, "token_extended": { "description": "Only present in active mode", "properties": { "new_expiration": { "type": "string", "example": "2025-01-17T12:37:00.000000Z" }, "lifetime_seconds": { "type": "integer", "example": 420 }, "access_token_refreshed": { "type": "boolean", "example": true } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" }, "LoginResponse": { "properties": { "status": { "description": "Response shape for POST /v1/auth/login.", "type": "string", "example": "success" }, "message": { "type": "string", "example": "Authorized" }, "authorization": { "properties": { "token": { "description": "Access token for API requests", "type": "string", "example": "Bearer eyJ0eXAiOiJKV1Qi..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "description": "Access token lifetime in seconds", "type": "integer", "example": 900 }, "refresh_token": { "description": "Refresh token for obtaining new access tokens", "type": "string", "example": "eyJ0eXAiOiJKV1Qi..." }, "refresh_token_expires_in": { "description": "Refresh token lifetime in seconds", "type": "integer", "example": 420 } }, "type": "object" }, "data": { "properties": { "userData": { "properties": { "id": { "type": "integer", "example": 123 }, "email": { "type": "string", "example": "user@example.com" }, "auth_type": { "description": "Authentication guard used (user, customer, or store)", "type": "string", "example": "user" }, "role": { "type": "string", "example": "csr", "nullable": true }, "name": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "full_name": { "type": "string", "example": "John Doe" } }, "type": "object" }, "permissions": { "description": "Spatie permissions granted via the user's role", "type": "array", "items": { "type": "string" }, "example": [ "customer.view", "customer.edit", "user.view" ] } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "LogoutResponse": { "properties": { "status": { "description": "Response shape for POST /v1/auth/logout.", "type": "string", "example": "success" }, "message": { "type": "string", "example": "Logged out successfully" } }, "type": "object" }, "QueueStatusResponse": { "required": [ "status", "message", "data" ], "properties": { "status": { "description": "Response shape for GET /v1/queues/status.", "type": "string", "example": "OK" }, "message": { "type": "string", "example": "Success" }, "data": { "required": [ "status" ], "properties": { "status": { "required": [ "batteryRequests", "referralRequests", "refunds", "claims" ], "properties": { "batteryRequests": { "description": "Pending battery request count", "type": "integer", "example": 5 }, "referralRequests": { "description": "Pending referral request count", "type": "integer", "example": 3 }, "refunds": { "description": "Pending refund count", "type": "integer", "example": 2 }, "claims": { "description": "Pending claim count", "type": "integer", "example": 7 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "RefreshResponse": { "properties": { "status": { "description": "Response shape for POST /v1/auth/refresh.", "type": "string", "example": "success" }, "message": { "type": "string", "example": "Token refreshed" }, "authorization": { "properties": { "token": { "description": "New access token", "type": "string", "example": "Bearer eyJ0eXAiOiJKV1Qi..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "description": "Access token lifetime in seconds", "type": "integer", "example": 900 } }, "type": "object" } }, "type": "object" }, "StoreContact": { "properties": { "name": { "properties": { "first_name": { "description": "Store contact information with nested name.", "type": "string", "example": "Jane", "nullable": true }, "last_name": { "type": "string", "example": "Smith", "nullable": true }, "full_name": { "type": "string", "example": "Jane Smith", "nullable": true } }, "type": "object" }, "email": { "type": "string", "format": "email", "example": "store@example.com" }, "phone_number": { "type": "string", "example": "(555) 987-6543" } }, "type": "object" }, "Store": { "properties": { "name": { "description": "Store within a vendor group.", "type": "string", "example": "Downtown Location" }, "id": { "type": "integer", "example": 789 }, "store_id": { "type": "string", "example": "S001" }, "phone_number": { "type": "string", "example": "(555) 987-6543" }, "contact": { "$ref": "#/components/schemas/StoreContact" } }, "type": "object" }, "UserCreatedResponse": { "required": [ "status", "message", "data" ], "properties": { "status": { "description": "Response shape for POST /v1/users.", "type": "string", "example": "success" }, "message": { "type": "string", "example": "User created successfully" }, "data": { "required": [ "user" ], "properties": { "user": { "$ref": "#/components/schemas/UserObject" } }, "type": "object" } }, "type": "object" }, "UserObject": { "description": "User object (fields vary by caller role and permissions)", "properties": { "id": { "description": "User object shape — grouped by field access tier.\n\nFields vary by the requesting user's role and permissions.", "type": "integer", "example": 1 }, "identity": { "description": "Requires user.view permission", "properties": { "name": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Admin" }, "full_name": { "type": "string", "example": "John Admin" } }, "type": "object" }, "email": { "type": "string", "example": "admin@myessentials.com" } }, "type": "object" }, "status": { "description": "email_verified_at and deactivated_at require user.view; mfa_enabled requires user.security", "properties": { "email_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "mfa_enabled": { "type": "boolean", "example": true }, "deactivated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "admin": { "description": "Requires user.admin permission", "properties": { "last_updated_password_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "roles": { "description": "Always present from roleNames; full sideload via ?include=roles", "type": "array", "items": { "type": "string" }, "example": [ "SUPERUSER" ] }, "permissions": { "description": "Sideloaded via ?include=permissions. Requires user.security permission.", "type": "array", "items": { "type": "string" }, "example": [ "customer.view", "user.manage" ], "nullable": true }, "organizations": { "description": "Hierarchical tree sideloaded via ?include=organizations. Groups → Franchises → Stores, with V6 assignments as top-level items.", "type": "array", "items": { "$ref": "#/components/schemas/UserOrganizationItem" }, "nullable": true } }, "type": "object" }, "UserOrganizationItem": { "description": "Organization hierarchy item. Type discriminates between assignment, group, franchise, and store.", "properties": { "type": { "description": "A single item in the organizations sideload array.\n\nDiscriminated by \"type\": assignment | group | franchise | store.", "type": "string", "enum": [ "assignment", "group", "franchise", "store" ] }, "id": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "custom_id": { "type": "string", "nullable": true }, "organizationId": { "description": "assignment type only", "type": "integer", "nullable": true }, "roleType": { "description": "assignment type only", "type": "string", "nullable": true }, "location": { "description": "store type only", "type": "string", "nullable": true }, "franchises": { "description": "group type only — nested franchises", "type": "array", "items": { "$ref": "#/components/schemas/UserOrganizationItem" }, "nullable": true }, "stores": { "description": "franchise type only — nested stores", "type": "array", "items": { "$ref": "#/components/schemas/UserOrganizationItem" }, "nullable": true } }, "type": "object" }, "UserResponse": { "required": [ "status", "message", "data" ], "properties": { "status": { "description": "Response shape for GET /v1/users/{id}.", "type": "string", "example": "success" }, "message": { "type": "string", "example": "User retrieved successfully" }, "data": { "required": [ "user" ], "properties": { "user": { "$ref": "#/components/schemas/UserObject" } }, "type": "object" } }, "type": "object" }, "Vendor": { "description": "Store, franchise, and group associations", "properties": { "group_name": { "description": "Vendor group with stores and franchises.", "type": "string", "example": "Hearing Solutions Group" }, "stores": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } }, "franchises": { "type": "array", "items": { "$ref": "#/components/schemas/Franchise" } } }, "type": "object" }, "ErrorEnvelope": { "required": [ "status", "message", "meta" ], "properties": { "status": { "description": "Standard API response envelope for error responses.\n\nMirrors ApiResponse::buildHttpResponseData() output on error paths.", "type": "string", "example": "error" }, "message": { "type": "string", "example": "An error occurred." }, "error_code": { "description": "Machine-readable error code", "type": "string", "example": "NOT_FOUND", "nullable": true }, "errors": { "description": "Field-level validation errors keyed by field name", "type": "object", "example": { "email": [ "Email is required." ], "name": [ "Name is too long." ] }, "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "meta": { "properties": { "alerts": { "type": "array", "items": { "type": "string" } }, "request_id": { "description": "Correlation ID for V6 error tracking", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "PaginationMeta": { "properties": { "current_page": { "description": "Pagination metadata as produced by ApiResponse::withPagination().", "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 100 }, "total_pages": { "type": "integer", "example": 4 }, "has_more": { "type": "boolean", "example": true } }, "type": "object" }, "CreateCustomerRequestBody": { "required": [ "first_name", "last_name", "email" ], "properties": { "first_name": { "type": "string", "maxLength": 100, "example": "Jane" }, "last_name": { "type": "string", "maxLength": 100, "example": "Smith" }, "email": { "type": "string", "format": "email", "example": "jane.smith@example.com" }, "primary_phone": { "type": "string", "maxLength": 15, "minLength": 7, "example": "5551234567", "nullable": true }, "primary_phone_type": { "type": "string", "enum": [ "MOBILE", "HOME", "WORK" ], "example": "MOBILE", "nullable": true }, "secondary_phone": { "type": "string", "maxLength": 15, "minLength": 7, "example": "5559876543", "nullable": true }, "secondary_phone_type": { "type": "string", "enum": [ "MOBILE", "HOME", "WORK" ], "example": "HOME", "nullable": true }, "dob": { "description": "Date of birth (YYYY-MM-DD, must be before today)", "type": "string", "format": "date", "example": "1990-05-15", "nullable": true }, "gender": { "type": "string", "enum": [ "M", "F", "O" ], "example": "F", "nullable": true } }, "type": "object" }, "CreateUserRequestBody": { "required": [ "first_name", "last_name", "email", "roles" ], "properties": { "first_name": { "type": "string", "maxLength": 100, "example": "Jane" }, "last_name": { "type": "string", "maxLength": 100, "example": "Smith" }, "email": { "type": "string", "format": "email", "example": "jane.smith@example.com" }, "password": { "description": "Required when send_verification_email is false", "type": "string", "format": "password", "minLength": 8 }, "roles": { "description": "Role names to assign (must exist in roles table)", "type": "array", "items": { "type": "string", "example": "CSR" }, "minItems": 1 }, "email_verified": { "description": "Mark email as pre-verified", "type": "boolean", "example": false }, "send_verification_email": { "description": "Send verification email (defaults to true)", "type": "boolean", "example": true } }, "type": "object" }, "LoginRequestBody": { "required": [ "userIdentifier", "password", "authorizationType" ], "properties": { "userIdentifier": { "description": "Email address or store ID", "type": "string", "example": "admin@example.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "example": "SecurePass1!" }, "authorizationType": { "description": "Authentication guard type", "type": "string", "enum": [ "user", "customer" ], "example": "user" }, "ottp": { "description": "One-time TOTP code (6 digits)", "type": "string", "maxLength": 6, "minLength": 6, "example": "123456", "nullable": true }, "trust_device": { "description": "Trust this device to skip MFA on future logins", "type": "boolean", "example": false } }, "type": "object" }, "UpdateCustomerRequestBody": { "description": "All fields are optional — only supplied fields are updated.", "properties": { "first_name": { "type": "string", "maxLength": 100, "example": "Jane", "nullable": true }, "last_name": { "type": "string", "maxLength": 100, "example": "Smith", "nullable": true }, "email": { "type": "string", "format": "email", "example": "jane.smith@example.com", "nullable": true }, "primary_phone": { "type": "string", "maxLength": 15, "minLength": 7, "example": "5551234567", "nullable": true }, "primary_phone_type": { "type": "string", "enum": [ "MOBILE", "HOME", "WORK" ], "example": "MOBILE", "nullable": true }, "secondary_phone": { "type": "string", "maxLength": 15, "minLength": 7, "example": "5559876543", "nullable": true }, "secondary_phone_type": { "type": "string", "enum": [ "MOBILE", "HOME", "WORK" ], "example": "HOME", "nullable": true }, "dob": { "description": "Date of birth (YYYY-MM-DD, must be before today)", "type": "string", "format": "date", "example": "1990-05-15", "nullable": true }, "gender": { "type": "string", "enum": [ "M", "F", "O" ], "example": "F", "nullable": true } }, "type": "object" }, "UpdateUserRequestBody": { "description": "All fields are optional — only supplied fields are updated. The email_verified field is restricted to SUPERUSER only.", "properties": { "first_name": { "type": "string", "maxLength": 100, "example": "Jane" }, "last_name": { "type": "string", "maxLength": 100, "example": "Smith-Johnson" }, "email": { "type": "string", "format": "email", "maxLength": 255, "example": "jane.smith@myessentials.com" }, "email_verified": { "description": "SUPERUSER only — manually verify email", "type": "boolean", "example": true } }, "type": "object" }, "AuthenticationRequest": { "required": [ "userIdentifier", "password", "authorizationType" ], "properties": { "userIdentifier": { "description": "Email address **or** alphanumeric record ID", "oneOf": [ { "type": "string", "format": "email", "example": "john.doe@example.com" }, { "type": "string", "example": "abc123098" } ] }, "password": { "type": "string", "format": "password", "example": "P@ssw0rd123" }, "authorizationType": { "description": "Which guard should be used", "type": "string", "example": "user|customer" }, "ottp": { "description": "6-digit MFA code", "type": "string", "example": "123456", "nullable": true }, "client_id": { "description": "OAuth client ID (can also be sent via Authorization header as Basic auth)", "type": "string", "format": "uuid", "nullable": true }, "client_secret": { "description": "OAuth client secret (can also be sent via Authorization header as Basic auth)", "type": "string", "nullable": true } }, "type": "object" }, "CreateNoteRequest": { "required": [ "note" ], "properties": { "note": { "description": "Note content (HTML allowed)", "type": "string", "example": "

Customer requested information about warranty coverage.

" } }, "type": "object" } }, "responses": { "Forbidden": { "description": "Forbidden — insufficient permissions", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Access denied." }, "error_code": { "type": "string", "example": "FORBIDDEN" } }, "type": "object" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Resource not found." }, "error_code": { "type": "string", "example": "NOT_FOUND" } }, "type": "object" } } } }, "RateLimited": { "description": "Too many requests — rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Too many attempts. Please try again later." }, "error_code": { "type": "string", "example": "RATE_LIMITED" } }, "type": "object" } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "An unexpected error occurred." }, "error_code": { "type": "string", "example": "INTERNAL_SERVER_ERROR" } }, "type": "object" } } } }, "Unauthenticated": { "description": "Unauthenticated — missing or invalid bearer token", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "ValidationError": { "description": "Validation failed — field-level errors", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Validation failed." }, "error_code": { "type": "string", "example": "VALIDATION_FAILED" }, "errors": { "type": "object", "example": { "email": [ "Email is required." ], "name": [ "Name is too long." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } } }, "parameters": { "IdPath": { "name": "id", "in": "path", "description": "Resource ID", "required": true, "schema": { "type": "integer", "example": 123 } }, "UuidPath": { "name": "id", "in": "path", "description": "Resource UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9e1a3b5c-4d2f-6e7a-8b9c-0d1e2f3a4b5c" } } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth2 password grant flow for user authentication. Use this for login and token refresh endpoints. Client credentials must be provided along with user credentials.", "flows": { "password": { "tokenUrl": "/api/v1/auth/token", "refreshUrl": "/api/v1/auth/refresh", "scopes": { "customer": "Customer access to their own data", "consultant": "Store consultant access", "view-customers": "View customer information", "edit-customers": "Edit customer information", "manage-claims": "Manage insurance claims", "view-policies": "View customer policies" } } } }, "bearerAuth": { "type": "http", "description": "Bearer token authentication for API endpoints. Include the access token received from login in the Authorization header as 'Bearer {token}'.", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Admin", "description": "Admin" }, { "name": "Authentication", "description": "Authentication" }, { "name": "Permissions", "description": "Permissions" }, { "name": "Roles", "description": "Roles" }, { "name": "Customers", "description": "Customers" }, { "name": "Queues", "description": "Queues" }, { "name": "Users", "description": "Users" } ] }